Upgraded firmware for Simone Giertz's Every Day Calendar that links an ATProto-powered ESP32, for sync with goals.garden 🌱
docs: improvements to README
+86
-40
+86
-40
README.md
+86
-40
README.md
···
5
5
## Features
6
6
7
7
- **WiFi sync with goals.garden** - Your completions sync bidirectionally with your goals.garden account
8
-
- **Real-time updates** - Changes on goals.garden appear instantly via Jetstream WebSocket
8
+
- **Real-time updates** - Changes on goals.garden appear appear in just a few seconds, via Jetstream WebSocket
9
9
- **Web UI for goal selection** - Visit `http://everydaycalendar.local` to choose which goal to track
10
10
- **Offline support** - Keep using the calendar when WiFi is unavailable; changes sync when reconnected
11
11
- **Light wave animation** - Satisfying ripple effect when you mark a day complete
12
12
13
-
## Hardware Setup
14
-
15
-
### What You'll Need
13
+
## What you'll need
16
14
17
-
- [Adafruit QT Py ESP32-S3](https://www.adafruit.com/product/5426) (~$13)
18
-
- A Stemma QT / Qwiic cable (any length - you'll cut it)
15
+
- [Adafruit QT Py ESP32-S3](https://thepihut.com/products/adafruit-qt-py-esp32-s3-wifi-dev-board) (~£12~)
16
+
- [A Stemma QT / Qwiic cable](https://thepihut.com/products/stemma-qt-qwiic-jst-sh-4-pin-cable-100mm-long) (at least ~8cm - you'll cut it)
19
17
- Soldering iron and solder
20
18
- Small Phillips screwdriver
21
19
22
-
### Wiring the ESP32
20
+
> [!IMPORTANT] Good WiFi needed
21
+
> These tiny devices have tiny WiFi antennas. You'll need good signal wherever you hang your calendar. There are [variants with antennas](https://www.adafruit.com/product/5348) you may want to try!
22
+
23
+
<details>
24
+
<summary>Don't have a QT Py ESP32-S3? Considering other boards?</summary>
25
+
26
+
If you don't have or can't find a QT Py ESP32-S3 _many_ other devices will work here! There's no need to buy new stuff if you have existing stuff that'll work lying around!
27
+
28
+
Things to consider when picking another device:
29
+
30
+
- It'll need Wifi (obviously)
31
+
- This code has been built for ESP32 hardware, you'll likely need to make significant changes if you want to use a different platform
32
+
- Watch for space: the height between the rear & front boards of the calendar isn't much, and the width between the foam padding and the wooden edge of the calendar is small too
33
+
- my QT Py gives off a fair amount of heat (it holds a constant WiFi connection), don't use a board that can't cope with that
34
+
- You don't need a Qwiic connector, you can hardwire I2C lines if that's easier
35
+
- The esp32's program/sketch is quite large (~1MB for my esp32-s3), don't skimp on program space!
36
+
37
+
You'll need to change the `board` in `platformio.ini` to match whatever you go for.
38
+
39
+
</details>
40
+
41
+
## Hardware hacking
23
42
24
-
1. **Cut the Stemma QT cable in half** - You'll need about 8cm of cable with the connector on one end.
43
+
> [!TIP] Backup your data!
44
+
> I've tried to ensure your calendar data is never lost, but don't risk it! Take a photo of your calendar with its lights on before you start, just in case things go wrong.
25
45
26
-
2. **Strip and tin the wires** - Strip about 3mm of insulation from each wire and add a small amount of solder to the exposed copper.
46
+
1. **Cut the Stemma QT cable in half**
47
+
48
+
You'll need about 8cm of cable with the connector on one end.
49
+
50
+
2. **Strip and tin the wires**
51
+
52
+
Strip about 3mm of insulation from each wire and add a small amount of solder to the exposed copper (this helps it 'stick' to the pads when we connect them).
53
+
54
+
3. **Open the calendar**
55
+
56
+
Remove the screws from the back panel. Carefully lift off the front panel - it separates easily but can crack if flexed too much.
27
57
28
-
3. **Open the calendar** - Remove the screws from the back panel. Carefully lift off the front panel - it separates easily but can crack if flexed too much.
58
+
4. **Locate the two front-panel jumper holes**
29
59
30
-
4. **Locate the I2C header** - Find the two 3-pin jumper headers (J2) near the top of the PCB.
60
+
Find the two 8-pin jumper headers near the top of the rear PCB; these are the holes the long prongs from the front panel go into.
31
61
32
-
5. **Solder the wires** to the header pads:
62
+
5. **Solder the wires to the right pads**
33
63
34
64
| Wire Color | Connection | Location |
35
65
| ------------ | ---------- | --------------------------------------- |
66
+
| Black (GND) | Ground | Top-right pad of LEFT jumper |
36
67
| Red (3.3V) | Power | Bottom-right pad of LEFT jumper |
37
-
| Black (GND) | Ground | Top-right pad of LEFT jumper |
68
+
| Blue (SDA) | Data | Middle-top right pad of RIGHT jumper |
38
69
| Yellow (SCL) | Clock | Middle-bottom right pad of RIGHT jumper |
39
-
| Blue (SDA) | Data | Middle-top right pad of RIGHT jumper |
40
70
41
71
42
72
43
-
6. **Connect the ESP32** - Plug the Stemma QT connector into the ESP32's Stemma QT port.
73
+
6. **Connect the ESP32**
44
74
45
-
7. **Mount the ESP32** - You may want to use double-sided tape to secure it inside the calendar housing, but be careful, this little board gets warm, so don't enclose it entirely.
75
+
Plug the Stemma QT connector into the ESP32's Stemma QT port. It'll only go all the way in one way up, so don't push too hard if it isn't working.
46
76
47
-
## Software Setup
77
+
7. **Mount the ESP32**
78
+
79
+
You may want to use double-sided tape to secure it inside the calendar housing, but be careful, this little board gets warm, so don't enclose it entirely.
80
+
81
+
8. **Flash the firmware**
82
+
83
+
Physical work done! See below for how to handle the software/firmware…
84
+
85
+
## Software setup
48
86
49
87
### Install PlatformIO
50
88
···
58
96
pip install platformio
59
97
```
60
98
61
-
### Configure the ESP32
99
+
### Configuration
62
100
63
-
1. **Copy the config template:**
101
+
1. **Copy the config template**
64
102
65
103
```bash
66
104
cp firmware/esp32/GoalsGardenSync/config.local.h.example \
67
105
firmware/esp32/GoalsGardenSync/config.local.h
68
106
```
69
107
70
-
2. **Edit `config.local.h`** with your WiFi credentials, ATProto username & app-password, and any other details.
108
+
2. **Edit your new `config.local.h`**
71
109
72
-
### Flash the Firmware
110
+
It'll _need_ your WiFi credentials, ATProto username & app-password (so it can stay connected indefinitely); you can also add some preferences for how it should operate (eg. your timezone, and what happens when your internet connection is down).
73
111
74
-
Before starting, make sure to plug your calendar in with the usual 5V power supply. (We don't want to power all those LEDs directly from your computer's USB!)
112
+
## Flash firmware
75
113
76
-
1. **Flash the calendar (ATmega328P):**
114
+
> [!WARNING] Use the power supply
115
+
> Before starting, make sure to plug your calendar in with the usual 5V power supply. (We don't want to power all those LEDs directly from your computer's USB!)
77
116
78
-
Connect the calendar via USB Type-B cable.
117
+
1. **Flash the calendar (ATmega328P)**
118
+
119
+
Connect the calendar via USB Type-B cable,then flash & monitor its output:
79
120
80
121
```bash
81
122
pio run -e calendar -t upload && pio device monitor -e calendar
82
123
```
83
124
84
-
(This also starts the serial monitor, so you can see that they start properly — you can exit that with Ctrl-c any time you like)
125
+
You can exit the monitor when you're happy by pressing Ctrl-c, any time.
85
126
86
-
2. **Flash the ESP32:**
127
+
2. **Flash the new ESP32**
87
128
88
-
Connect the ESP32 via USB-C cable.
129
+
Similarly for the ESP32 via USB-C cable:
89
130
90
131
```bash
91
132
pio run -e esp32sync -t upload && pio device monitor -e esp32sync
92
133
```
93
134
94
-
(This also starts the serial monitor, so you can see that they start properly — you can exit that with Ctrl-c any time you like)
135
+
> [!NOTE]
95
136
96
-
### First Boot
137
+
At this point things _should_ already be fully working, but naturally you'll not be able to press any buttons.
97
138
98
-
1. **Reassemble the calendar** - Carefully replace the front panel and screws. (You can power on before replacing the front panel if you want, you just won't be able to press any buttons.)
139
+
To make sure things are all set up correctly you may want to:
99
140
100
-
2. **Power on** - The ESP32 will connect to WiFi and sync with goals.garden — it'll take a good minute or two to connect to your WiFi & sync with your PDS.
141
+
- Visit [http://everydaycalendar.local](http://everydaycalendar.local) to see if the website loads (it'll be _slow_, be patient)
142
+
- Choose which online goal you want to track with your calendar
143
+
- Visit [goals.garden](https://goals.garden), swao to the relevant goal, and check that adding a new day online turns on the relevant LED
101
144
102
-
3. **Select your goal** - Visit `http://everydaycalendar.local` in your browser to choose which goal to track.
145
+
> [!NOTE] Slight update delay
146
+
> Updates between the site and the physical calendar may take a moment (hopefully not more than 5 seconds).
103
147
104
-
Assuming you left the offline sync option as the default:
148
+
## Troubleshooting
149
+
150
+
- **Can't find `everydaycalendar.local`**
105
151
106
-
- If you have existing data on the calendar, it will create a new "Everyday Calendar" goal and upload your completions
107
-
- If the calendar is blank, it will sync from your first goal on goals.garden
152
+
Try the IP address instead (it should be in the serial monitor output, while the ESP32 is connected to your computer).
108
153
109
-
## Troubleshooting
154
+
- **Sync not working**
110
155
111
-
- **Can't find `everydaycalendar.local`** - Try the IP address instead (check your router's DHCP list), or ensure mDNS is working on your network.
112
-
- **ESP32 not responding** - Check the serial monitor (`pio device monitor -e esp32sync`) for error messages.
113
-
- **Calendar not syncing** - Verify your ATProto credentials and that you have at least one goal on goals.garden.
156
+
Check the serial monitor (`pio device monitor -e esp32sync`) for error messages. If it works at your desk, but not on your wall, your WiFi may also not be strong enough for this little device at that location. There are QT Py ESP32 devices with [external antennas](https://www.adafruit.com/product/5348) that may help here?
114
157
115
158
## Built on top of [The Every Day Calendar](https://yetch.studio/products/every-day-goal-calendar)
116
159
117
160
118
161
119
-
This repository contains firmware and schematics for the [Every Day Calendar](https://yetch.studio/products/every-day-goal-calendar) by Simone Giertz. Thank you for making this beautiful piece of hardware!
162
+
This repository contains [firmware and schematics](https://gitlab.com/simonegiertz/the-every-day-calendar) for the [Every Day Calendar](https://yetch.studio/products/every-day-goal-calendar) by Simone Giertz. Thank you for making this beautiful piece of hardware!
163
+
164
+
It also incorporates [improvements made by
165
+
Momin Khan](https://github.com/foolmoron/EverydayCalendar2) on Github — I love the starburst animation!
120
166
121
167
## License
122
168