Skip to content

Commit a860b3a

Browse files
daniel-frenkelclaude
daniel-frenkel
and
claude
committed
README: full rewrite for ESPHome firmware
The README described the legacy Arduino build (HTTP control, hall-effect sensors, old hardware layout). Rewrite it for the current ESP32-C6 + TMC2209 ESPHome firmware: browser/Home Assistant/REST control, StallGuard + vibration stall + over-temp + anti-tamper safety, built-in scheduling, GitHub OTA updates, updated repo layout and hardware/v2.0 3D-print paths, and links to the rewritten wiki. Product/marketing copy (use cases, kits, fit guidance) kept. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 163129c commit a860b3a

1 file changed

Lines changed: 190 additions & 52 deletions

File tree

‎README.md‎

Lines changed: 190 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,115 +1,253 @@
1-
# Glasscalibur: Automated Horizontal Window Opener
1+
# Glasscalibur — Automated Horizontal Window Opener
22

3-
Glasscalibur is a smart window opener that uses HTTP requests to open and close your windows. Combine it with Node-RED, Home Assistant, or any other system capable of sending HTTP requests and get your window to open and close automatically.
3+
Glasscalibur is a smart opener for horizontal-sliding windows. A NEMA stepper
4+
motor drives a lead screw that slides your window open and closed, controlled by
5+
an ESP32‑C6 running [ESPHome](https://esphome.io). Control it from **any web
6+
browser** with no app and no cloud account, pair it natively with **Home
7+
Assistant**, or automate it with schedules, sunrise/sunset, or any system that
8+
can send an HTTP request (Node‑RED, scripts, IFTTT‑style webhooks, etc.).
49

5-
# Build Guides
6-
7-
You can find the assembly instructions and video in the [hardware folder](/hardware).
8-
9-
You can find the window attachment guide in the [hardware folder](/hardware).
10+
![window opener main](/media/readme/window-gif.gif)
1011

11-
## Use cases
12+
> The video above has the top cover removed so you can see the mechanism. Under
13+
> the cover, a custom PCB with an **ESP32‑C6** and a **TMC2209** stepper driver
14+
> runs the motor; **limit switches** at each end of travel give the cover an
15+
> absolute, self‑correcting position.
1216
13-
While you can use Alexa, Google or other voice control, home automation is where this device shines.
17+
![window opener top](/media/readme/top-gif.gif)
1418

15-
1. Use an indoor air quality sensor (like an Awair) to trigger the window to air out the room
16-
2. Check Purple Air sensors hourly and close your windows when bad outdoor air is detected
17-
2. Measure indoor and outdoor temperatures and cool your room when necessary
18-
3. Check weather APIs if it's raining to open/close your window
19-
4. Set a schedule to listen to the morning birds chirp
19+
---
20+
21+
## Features
22+
23+
- **Browser control, no cloud** — open `http://glasscalibur-XXXXXX.local` on
24+
your network and drive the cover, tune the motor, and set schedules. No Home
25+
Assistant or account required.
26+
- **Native Home Assistant** — auto‑discovered over the ESPHome API as a real
27+
cover entity (no `command_line`/curl glue).
28+
- **Built‑in scheduling** — open/close at fixed times **or** at sunrise/sunset
29+
(with minute offsets), all editable from the browser. Survives reboots.
30+
- **Obstruction & stall protection** — TMC2209 **StallGuard** plus an
31+
accelerometer‑based **vibration‑stall** backstop stop the motor when the
32+
window jams, is locked, or something gets in the way, and save the position.
33+
- **Over‑temperature cutoff** — an on‑board temperature sensor stops the motor
34+
if it exceeds 80 °C.
35+
- **Anti‑tamper alarm** — the accelerometer flags if a mounted unit is moved or
36+
tilted and sounds a buzzer.
37+
- **Over‑the‑air updates** — a one‑click **Update Firmware** button pulls the
38+
latest release straight from GitHub. No computer needed.
39+
- **Instant manual override** — the whole device lifts off the window in a
40+
couple of seconds for cleaning or emergencies (see GIF below).
41+
42+
---
2043

2144
## How it works
2245

23-
![window opener main](/media/readme/window-gif.gif)
46+
Glasscalibur uses a **NEMA 17 stepper motor** connected to a **lead screw**. As
47+
the screw turns, a nut travels along it and pushes/pulls the window sash. A
48+
custom PCB with an **ESP32‑C6‑MINI** and a **TMC2209** silent stepper driver
49+
runs the motor over a single‑wire UART link.
2450

25-
This video has the top cover removed to help you see it better.
51+
![window opener PCB](/media/readme/model-h-pcb.jpg)
2652

27-
![window opener top](/media/readme/top-gif.gif)
53+
Two **limit switches** — one at each end of travel — give the cover a known
54+
absolute position: every time the carriage hits a limit, the firmware
55+
re‑calibrates its step count, so position never drifts. The board also carries:
2856

29-
Glasscalibur uses a NEMA 17 stepper motor that is connected to a lead screw. A custom PCB with an ESP32 and TMC2209 drives the motor. Two hall effect sensors on each end stop the motor when it reaches the end.
57+
- a **TMP1075** temperature sensor (motor over‑temp cutoff),
58+
- a **LIS2DH12** 3‑axis accelerometer (vibration‑stall + anti‑tamper),
59+
- a **piezo buzzer** (tamper alarm), and
60+
- physical buttons (a control button and a Wi‑Fi‑reset button).
3061

31-
![window opener top](/media/readme/model-h-pcb.jpg)
62+
The firmware is a single ESPHome configuration — see
63+
[`firmware/esphome/`](/firmware/esphome) for the full, heavily commented config
64+
and a flashing guide.
3265

66+
---
3367

3468
## Safety features
3569

36-
Safety is the primary concern with this device.
70+
Safety is the primary concern with this device.
3771

38-
In case of emergencies, the entire device can be instantly removed for your window. (see GIF above)
72+
**Instant removal.** In an emergency the entire device lifts straight off the
73+
window — no tools, a couple of seconds.
3974

40-
![window opener main](/media/readme/hand-gif.gif)
75+
![instant removal](/media/readme/hand-gif.gif)
4176

42-
In case an object or limb gets in the way during window operations, the device will automatically stop and save its location. Only 5 lbs. of force is required to trigger it to stop.
77+
**Obstruction & lock detection.** While moving, the cover watches for a stall
78+
two ways: the TMC2209's StallGuard reads the motor's mechanical load, and the
79+
accelerometer watches for the hard vibration a jammed mechanism produces. If
80+
something gets in the way, or the window is locked, the motor stops and saves
81+
its position. Both detectors have adjustable sensitivity so you can tune them to
82+
your window.
4383

44-
In the event that you leave the window locked, the device will automatically detect a locked window and stop the motor.
84+
**Over‑temperature cutoff.** If the motor sensor reads above 80 °C, motion stops
85+
automatically.
4586

87+
**Anti‑tamper.** Once armed, the accelerometer learns the device's resting
88+
orientation; if a mounted unit is bumped, tilted, or pried, it raises a Tamper
89+
alert and sounds the buzzer.
90+
91+
---
4692

4793
## Will it work on your window?
4894

49-
Before you get too excited and buy/build this, please be sure it will work on your window. The height of your window sill is the primary factor to consider.
95+
Before you build or buy, check that the device fits your window. Window **sill
96+
height** is the main factor.
5097

5198
### Is your window sill the correct height?
5299

53-
![window opener GIF](/media/readme/window-sill.jpg)
100+
![window sill](/media/readme/window-sill.jpg)
54101

55-
The maximum distance from the top of the window frame to the sill is 2 inches (Red text in the image above). Any more than 2 inches and you will need to raise the window opener. One solution is to use a piece of wood such as a 1x4 or 2x4 in order to elevate the entire device.
102+
The maximum distance from the top of the window frame to the sill is **2 inches**
103+
(red text above). More than that and you'll need to raise the opener — a piece
104+
of wood such as a 1×4 or 2×4 under the whole device works well.
56105

57-
In order to properly attach the window mount (white piece in the above photo), your window needs 14mm of the lower sash of the window to be exposed.
106+
To attach the window mount (white piece above), you need **14 mm** of the lower
107+
sash exposed.
58108

59109
### Is your window wide enough?
60110

61-
The device is just under 22" from end to end. This means your window needs to be at least 44" wide. Also add in 2 inches to be safe. So your window needs to be 46" wide from end to end.
111+
The device is just under **22 in** end to end, so your window needs to be at
112+
least **44 in** wide — add 2 in to be safe, so target **46 in**.
62113

63114
### Is your window too heavy?
64115

65-
The motor has been tested to move up to 40 lbs. However, this is extremely heavy and may cause problems. If your window is this heavy, lubricate it with dry silicone spray and check if that helps.
116+
The motor has been tested up to **40 lb** of window. That's very heavy and can
117+
cause problems; if your window is that heavy, lubricate the track with dry
118+
silicone spray first and see if that helps.
119+
120+
---
121+
122+
## Controlling it
123+
124+
You have several options, and they all work at once:
125+
126+
| Method | How |
127+
| --- | --- |
128+
| **Web browser** | Open `http://glasscalibur-XXXXXX.local` (the `XXXXXX` MAC suffix is printed on the USB serial log at boot). Full control panel — cover, motor tuning, schedule, diagnostics. |
129+
| **Home Assistant** | The device is auto‑discovered over the native ESPHome API as a `cover` entity. No YAML, no curl. |
130+
| **HTTP / REST** | The ESPHome web server exposes a REST API, e.g. `POST http://glasscalibur-XXXXXX.local/cover/glasscalibur/set?position=0.5` (position is `0.0`=closed … `1.0`=open), and `/open`, `/close`, `/stop`. Drive it from Node‑RED, scripts, or webhooks. |
131+
132+
### Scheduling
66133

134+
Two browser‑editable modes, gated by a master **Schedule Enabled** switch:
135+
136+
- **Fixed times** — set an **Open Time** and **Close Time**.
137+
- **Sunrise/sunset** — turn on **Sun Schedule**, set your **latitude/longitude**,
138+
and optionally an open/close **offset** in minutes (e.g. `-30` to close 30 min
139+
before sunset).
140+
141+
### Home automation ideas
142+
143+
Home automation is where this device shines:
144+
145+
1. Use an indoor air‑quality sensor (e.g. Awair) to air out a stuffy room.
146+
2. Poll PurpleAir hourly and close the window when outdoor air goes bad.
147+
3. Compare indoor/outdoor temperature and cool the room when it helps.
148+
4. Check a weather API and close the window when rain is forecast.
149+
5. Open at sunrise to wake up to the birds.
150+
151+
Full step‑by‑step guides for all of the above live in the
152+
[**project wiki**](https://github.com/Valar-Systems/Glasscalibur/wiki).
153+
154+
---
155+
156+
## Repository layout
157+
158+
| Path | Contents |
159+
| --- | --- |
160+
| [`firmware/esphome/`](/firmware/esphome) | **Current firmware** — the ESPHome config (`Glasscalibur-esphome.yml`) and a flashing/release guide. |
161+
| [`firmware/arduino/`](/firmware/arduino) | Legacy Arduino firmware (the original ESPUI/HTTP build). Kept for reference. |
162+
| [`hardware/v2.0/`](/hardware/v2.0) | 3D‑printable parts — STEP CAD files plus a ready‑to‑slice print platter (`platter-v1.3mf`). |
163+
| [`media/`](/media) | Images and GIFs used in the docs. |
164+
165+
---
67166

68167
## How to build it
69168

70-
To make this affordable to build, we have created a kit. Otherwise, sourcing the screws and hardware individually gets very expensive.
169+
To keep it affordable, there's a kit — sourcing the screws and hardware
170+
individually gets expensive fast.
71171

72-
### Kits
172+
![window kit](/media/readme/window-kit.jpg)
73173

74-
There are two versions of the kit. One with plastics and one without. If you have a 3D printer, feel free to print your own.
174+
Two kit versions are available — one with the 3D‑printed plastics and one
175+
without (print your own):
75176

76-
* [Link to kit **Excluding** 3D printed parts](https://valarsystems.com/products/automatic-window-opener?variant=39590892240955)
77-
* [Link to kit **Including** 3D printed parts](https://valarsystems.com/products/automatic-window-opener?variant=39590892208187)
78-
79-
![window opener GIF](/media/readme/window-kit.jpg)
177+
- [Kit **excluding** 3D‑printed parts](https://valarsystems.com/products/automatic-window-opener?variant=39590892240955)
178+
- [Kit **including** 3D‑printed parts](https://valarsystems.com/products/automatic-window-opener?variant=39590892208187)
179+
180+
Full assembly instructions and a build video are in the
181+
[**Assembly Guide**](https://github.com/Valar-Systems/Glasscalibur/wiki/Assembly-Guide).
80182

81183
## How to 3D print it
82184

83-
Your window might open **from** the left **to** the right, or it might open **from** the right **to** the left.
185+
The printable parts are in [`hardware/v2.0/`](/hardware/v2.0):
84186

85-
The only version available is the ability to open from right to left. The other version will be added later.
187+
- **`platter-v1.3mf`** — a ready‑to‑slice [PrusaSlicer](https://www.prusa3d.com/prusaslicer/)
188+
project with the parts laid out on the bed. Print in **PETG** at **0.25 mm**
189+
layer height.
190+
- The individual **`.step`** files are the CAD source for each part if you want
191+
to modify or re‑orient them.
86192

87-
Go to the repo folder ["hardware" -> "Plastics"](/hardware/Plastics)
193+
See the [**3D Printing Guide**](https://github.com/Valar-Systems/Glasscalibur/wiki/3D-Printing-Guide)
194+
for details.
88195

89196
## How to install it
90197

91-
Installation is **super easy**. Total install time is just a few minutes. Attach 2 mounts, wait 24 hours for the adhesives to build some strength, and start using.
198+
Installation is **fast** — a few minutes of work, then a 24‑hour wait for the
199+
adhesive to cure.
200+
201+
![window mount](/media/readme/mount-gif.gif)
202+
203+
1. Attach the **window mount** (to the sash).
204+
2. Attach the **sill mount**.
205+
3. Wait **24 hours** for the adhesives to set, then start using the opener.
92206

93-
![window opener mount](/media/readme/mount-gif.gif)
207+
Both mounts are adhesive; if needed you can add a screw into the sill, but that
208+
hasn't been required. Full details are in the
209+
[**Window Installation Guide**](https://github.com/Valar-Systems/Glasscalibur/wiki/Installation-Guide).
94210

95-
There are 2 mounts that are attached with adhesive. If necessary, you can also use a screw into the sill, but that has not been required.
211+
---
96212

97-
First attach the window mount.
213+
## Firmware: flashing & updates
98214

99-
Next, attach the sill mount.
215+
- **First flash** of a blank board is over **USB** with the ESPHome CLI
216+
(`esphome run firmware/esphome/Glasscalibur-esphome.yml`) or via
217+
[web.esphome.io](https://web.esphome.io).
218+
- After that, update **over the air**: open the web UI → **Diagnostics** →
219+
**Update Firmware (GitHub)**, and the device pulls the
220+
[latest release](https://github.com/Valar-Systems/Glasscalibur/releases/latest)
221+
and reflashes itself.
100222

101-
Wait 24 hours for the adhesives to set and you can now use the window opener.
223+
The build, release, and OTA process is documented in
224+
[`firmware/esphome/README.md`](/firmware/esphome/README.md).
102225

226+
---
103227

104-
## Sending commands
228+
## Documentation
105229

106-
Commands are sent via HTTP requests
230+
The [**project wiki**](https://github.com/Valar-Systems/Glasscalibur/wiki) has
231+
the full guides:
107232

108-
Follow the instructions outlined in the ![firmware](/firmware) folder.
233+
- [3D Printing](https://github.com/Valar-Systems/Glasscalibur/wiki/3D-Printing-Guide)
234+
- [Assembly](https://github.com/Valar-Systems/Glasscalibur/wiki/Assembly-Guide)
235+
- [Window Installation](https://github.com/Valar-Systems/Glasscalibur/wiki/Installation-Guide)
236+
- [Wi‑Fi Setup](https://github.com/Valar-Systems/Glasscalibur/wiki/WiFi-Setup)
237+
- [Web UI](https://github.com/Valar-Systems/Glasscalibur/wiki/Web-UI-Guide)
238+
- [Motor & Stall Tuning](https://github.com/Valar-Systems/Glasscalibur/wiki/Motor-Setup)
239+
- [Scheduling](https://github.com/Valar-Systems/Glasscalibur/wiki/Scheduling-Guide)
240+
- [Security & Tamper](https://github.com/Valar-Systems/Glasscalibur/wiki/Security-and-Tamper)
241+
- [API](https://github.com/Valar-Systems/Glasscalibur/wiki/API-Guide)
242+
- [Home Assistant](https://github.com/Valar-Systems/Glasscalibur/wiki/Home-Assistant-Guide)
243+
- [Firmware Updates](https://github.com/Valar-Systems/Glasscalibur/wiki/Firmware-Updates)
109244

245+
---
110246

111-
## Node-RED workflow
247+
## License
112248

113-
Use Node-RED in Home Assistant to automate everything. Click the image below to watch a YouTube video on how it works.
249+
The firmware is licensed under the **GNU GPL v3** — see
250+
[`firmware/LICENSE`](/firmware/LICENSE).
114251

115-
[![Youtube Link](/media/readme/node-red-flow.jpg)](https://youtu.be/ou7uRED_ff0)
252+
If this project is useful to you, you can support it via
253+
[GitHub Sponsors](https://github.com/sponsors/valar-systems).

0 commit comments

Comments
 (0)