1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
# FastForge - AGENTS.md
Pebble Intermittent Fasting Tracker Development Guide
Fedora Linux + Rebble Pebble SDK 4.9+ (April 2026)
This file is the primary workflow reference for FastForge contributors.
## 1. One-Time Initial Setup
```bash
sudo dnf update
sudo dnf install -y python3-pip nodejs SDL-devel dtc uv just
uv tool install pebble-tool --python 3.13
export PATH="$HOME/.local/bin:$PATH"
pebble sdk install latest
```
## 2. After Every Reboot - Restore uv Tool PATH
```bash
export PATH="$HOME/.local/bin:$PATH"
pebble --version
```
Optional permanent fix:
```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
## 3. Justfile Workflow
Available commands:
- `just`: list commands
- `just dev`: build + install to emulator
- `just logs`: live logs (second terminal)
- `just kill`: stop emulator
- `just clean`: remove build artifacts
- `just rebuild`: clean + full rebuild + install
- `just quick`: quick rebuild + install
- `just screenshot`: screenshot of emulator
- `just sdk-version`: print Pebble SDK/tool version
- `just test`: run host unit tests (expects `TZ=UTC` for deterministic date/streak results)
Daily loop after reboot:
1. Restore PATH (`export PATH="$HOME/.local/bin:$PATH"`).
2. `cd /path/to/fastforge`
3. `just dev`
4. In a second terminal run `just logs`
## 4. Headless Basalt Testing
When `just dev` / `just logs` are not enough for runtime verification, use a
single headless basalt emulator and drive it through the QEMU monitor.
### Clean emulator reset
If the emulator hangs on the Pebble boot screen or `pebble install` gets stuck
at `Waiting for the firmware to boot`, reset the persisted basalt flash:
```bash
pebble kill
mv ~/.pebble-sdk/4.9.148/basalt/qemu_spi_flash.bin \
~/.pebble-sdk/4.9.148/basalt/qemu_spi_flash.bin.bak.$(date +%s)
```
Then start a fresh live session:
```bash
pebble install -vv --emulator basalt --logs
```
Important:
- Wait for `Firmware booted.`
- Wait for `App install succeeded.`
- The verbose output prints the QEMU monitor port, for example:
`-monitor tcp::46951,server,nowait`
### Capture screenshots from the monitor
Use the monitor port from the install output:
```bash
python - <<'PY'
import socket, time
s = socket.create_connection(('127.0.0.1', 46951), timeout=2)
s.sendall(b'screendump /tmp/fastforge.ppm\n')
time.sleep(0.4)
s.close()
PY
tesseract /tmp/fastforge.ppm stdout --psm 6
```
That gives you a real basalt screen capture plus OCR for quick verification.
### Send button input through the monitor
Use Pebble button semantics via QEMU `sendkey`:
- `up`: top button
- `down`: bottom button
- `s`: select button
- `q`: back button
Example:
```bash
python - <<'PY'
import socket, time
MON = ('127.0.0.1', 46951)
def cmd(text, wait=0.25):
s = socket.create_connection(MON, timeout=2)
s.sendall((text + '\n').encode())
time.sleep(wait)
s.close()
cmd('sendkey down', 0.5)
cmd('sendkey s', 0.8)
cmd('screendump /tmp/after_select.ppm', 0.3)
PY
```
### Proven runtime checks
This workflow was used successfully to verify:
- main menu
- preset submenu
- current timer
- history screen
- statistics screen
- settings screen
- backup export logs
## 5. Commit Policy
Commit these project files when changed:
- `README.md`
- `AGENTS.md`
- `PLAN.md`
- `Justfile`
- `package.json`
- `wscript`
- `src/c/fastforge.c`
- `src/c/fastforge_core.c`
- `src/c/fastforge_history.c`
- `src/c/fastforge_internal.h`
- `.gitignore`
Do not commit generated artifacts:
- `build/`
- `*.pbw`, `*.elf`, `*.bin`, `*.o`, `*.map`
- `.lock-waf*`, `.wafpickle*`, `config.log`
## 6. Troubleshooting
- `pebble: command not found`: restore PATH from section 2.
- Emulator does not start: run `just kill` then `just dev`.
- Build fails: run `just clean` then `just rebuild`.
- Change app version: update `package.json`, then run `just dev`.
- `Waiting for the firmware to boot` forever: reset
`~/.pebble-sdk/4.9.148/basalt/qemu_spi_flash.bin` as described in section 4.
- `pebble logs --emulator basalt` and `pebble install --emulator basalt` each
spawn their own emulator instance. For headless runtime testing, prefer one
`pebble install -vv --emulator basalt --logs` session and use its monitor
port for screenshots/input.
- Repeated hot reinstalls may show a `pypkjs` / `geventwebsocket` traceback in
the toolchain logs. In the verified workflow the app still installed and ran,
so treat that as a tool-side warning unless the watch UI actually breaks.
Last updated: April 12, 2026 (follow-up fix)
Maintained for: FastForge agents
|
