The MeshCore app, over Bluetooth
The official MeshCore Android app drives the device over BLE: the phone shows the device's nodes, channels and messages, and sends through it. The device stays its own node with its own screens; the phone is a second way in.
Status: step 1 done (2026-11-13): Bluetooth fits, in one firmware (Q332, Q334). Step 2 done: the protocol, host-tested. Step 3 done (2026-11-17): the app pairs, reconnects and shows the device's contacts and channels, with Wi-Fi on beside it (Q335). Step 4 done (2026-11-17): every "Done when" checked with the phone and the Heltec, and the user guide written. Step 5 done (2026-11-17): rooms, as a client (Q339–Q343).
Goal: the official MeshCore Android app drives the device over BLE: the phone shows the device's nodes, channels and messages, and sends through it. The device stays its own node with its own screens; the phone is a second way in.
Reference: the owner's Android phone with the official MeshCore app (its version recorded here in step 4), and the Heltec V4 of M4 on the other end (Q329).
What the first measurement found
Before the round ended, a throwaway build linked Arduino's BLE library (NimBLE, already enabled in the rebuilt framework) and tried to start it (2026-11-11, branch probe-ble-heap, not pushed):
- Linked, never started, BLE takes about 27 KB of free heap: 65.0 KB free at idle with the VPN up became 37.4 KB, the largest block 31.7 KB became 24.6 KB. Most of it is the controller's code in IRAM (+21.7 KB), which on the S3 comes out of the same internal RAM; static RAM +2.1 KB. The firmware grows by 244 KB, to 82% of its partition.
- Starting the controller crashed the device, 3 times in 3: the interrupt watchdog, in task
btController, inside the controller's ROM initialisation (r_lld_core_init), with the VPN up or down, before advertising. Nothing printed before. What it costs once running isn't known; upstream's boards suggest 30–50 KB more.
With IRC on TLS the firmware already fell to 4.5 KB free (M5, Q318): BLE can't simply be added.
Decisions (design round 2026-11-11)
| # | Decision |
|---|---|
| Q319 | M6 is the companion protocol over BLE, for the official Android app. The repeater, the room server and the other roles move to M7. USB and Wi-Fi transports of the same protocol are out of M6. |
| Q320 | One node, two screens. The app sees the device's own node: its key (M5, Q306), its nodes, channels and messages. A message sent from the phone shows in the Mesh App, and the other way round. Not upstream's model, where the phone owns everything and the device is a radio. |
| Q321 | Our own implementation of the protocol, host-tested, on MeshNode and the Mesh Service. Upstream's companion firmware (about 3,400 lines, tied to its storage and boards) is the specification at our pin: command codes and frame layout. It isn't vendored. Tests use frames taken from upstream's code and from the real app. |
| Q322 | Settings → Bluetooth, Off by default. Pairing shows a random 6-digit PIN on the device for the phone to enter; the bond is kept, and Settings can forget it. No fixed PIN (upstream's default is 123456). |
| Q323 | The device's rules hold for the app. It sends only while Mesh is Sending, within the 10% airtime (M5, Q305). It can't export or import the key (USB only, Q306) and can't confirm the region. What the device refuses (changing the radio settings, for one) gets the protocol's error reply, and the device's own state is unchanged. |
| Q324 | The first usable set of commands: device and self info, the node list, waiting messages, private and channel messages, the channel list and editing it, adverts, setting the time from the phone, battery. The rest of the roughly 105 commands (radio settings, remote login, telemetry and others) gets the error reply, and can come later. |
| Q325 | The phone's time is a valid clock (Q308), as GNSS and Wi-Fi time are: sending works from the phone with neither. A later GNSS fix or Wi-Fi time overrides it. |
| Q326 | The app's contacts are the node list (the 24 verified nodes most recently heard, M4, Q297, Q313). Removing a contact in the app drops the node until its next advert is heard. Auto-add is always on; turning it off is refused. |
| Q327 | Messages waiting for the phone: while it is away, channel and private messages received are queued for it, the last 16 (about 2.8 KB), the oldest going first. Reading one on the device doesn't take it from the queue. A restart empties it; older messages are on the card and in the Mesh App, not offered to the app. |
| Q328 | Where the connection shows: a B in the Status Bar while a phone is connected; a dialog with the PIN while pairing; ble status in the Shell (the state, the bonded phone, frames exchanged). One bonded phone at a time. |
| Q329 | The reference is the owner's Android phone and the official app, with the Heltec V4 on the other end; the app's version is recorded here. |
| Q330 | Step 1 is a feasibility check, and the milestone stops there if it fails: why the controller crashes; what BLE costs running; what it can be brought to when off (the controller run from flash rather than IRAM, NimBLE's memory cut down); and where the 5 KB of Q318 went. M6 goes on only if Q332's limit can be met, or Q333's fallback is taken. |
| Q331 | Replaced by Q335. Bluetooth or Wi-Fi, not both. With Bluetooth on, Wi-Fi is off, and the VPN, IRC, SSH and Gemini with it: the phone has the internet, the device is its mesh radio, its own screens still work. Bluetooth off brings Wi-Fi back. To be revisited if step 1 finds room for both. |
| Q332 | What BLE may cost when off: 8 KB of free heap at most, measured at idle against v0.27.0, and the floors (G1, Q86; M4, Q314) still hold with the VPN and IRC on TLS. |
| Q333 | If step 1 can't get under 8 KB: a second signed firmware, "with Bluetooth", built and released alongside the normal one (ADR 0008), chosen when installing; an update keeps a device on the firmware it has. Not the USB-only companion, which would need no Bluetooth stack. Not needed (step 1). |
| Q334 | Decided in step 1 (2026-11-13). Bluetooth's cost is found elsewhere in the firmware first, so nothing does worse than v0.27.0. Within Q332's 8 KB, the 6 KB it took at idle still kept IRC on TLS from starting beside the mesh and the VPN (its own 60 KB start floor). The firmware gave back about 13 KB: the update task exists only while it has work, and four stacks are cut to what they use (ADR 0012). |
| Q335 | Decided in step 3 (2026-11-14), replaces Q331. Bluetooth and Wi-Fi together. The firmware made room for both (ADR 0012): 17.5 KB of code moved from IRAM to flash, and IRC's task exists only while IRC is wanted. With Bluetooth on, what needs a TLS connection (IRC, Gemini, update checks) finds too little memory and waits, saying so; the VPN, SSH, the Debug Console and the mesh work. An Update File pushed over Wi-Fi needs Bluetooth off for the time of the install. |
| Q336 | Decided in step 4 (2026-11-17). The app can mark a node as a favourite, and nothing else about it. ADD_UPDATE_CONTACT for a node in the list takes only the favourite flag; any other change, or a new contact, is refused (Q326). A favourite is kept on the 24-node list when it's full, as upstream keeps its favourite contacts, and on the card: its node line's location column reads LF or -F, which a firmware from before skips rather than misreads. |
| Q337 | Decided in step 4 (2026-11-17). The Mesh App gets its history back at start. The mesh reads the newest messages of each channel followed, and of the 8 private conversations most recently written to, back from the card, within the RAM limits of Q299 and Q313 (50 a conversation, 4 KB and 3 KB in all). Messages sent from the app are in them, as the device's own. A private conversation is named by the node on the card whose key its file's name starts with; one with no such node stays in its file. |
| Q338 | Decided in step 4 (2026-11-17). An own message's state is on the card too, so it comes back with it: the line says me:sending or me:sent where it said me, and each later state (delivered, failed, heard repeated) is a status line after it, =delivered in that field with the message's timestamp and no text. Firmware from before skips the new lines: pre-1.0, the card's format may change. |
| Q339 | Decided 2026-11-17, step 5. Room client: log in to a MeshCore room server, read its posts and post to it, from the MeshCore app and from the Mesh App alike. The radio side is upstream's chat node's (sendLogin, signed messages); keep-alives aren't sent, as upstream's companion no longer does. |
| Q340 | Decided 2026-11-17, step 5. A room is a conversation in the Mesh App, marked as a room; each post reads "author: text", the author named from the node list, or by the first bytes of its key when unknown. |
| Q341 | Decided 2026-11-17, step 5. The device remembers each room's password (in the settings, as Wi-Fi's, never shown again), typed once on the device or given by the app; it logs in when the room is opened, not at every start. |
| Q342 | Decided 2026-11-17, step 5. A room's "since" is kept with its node on the card, so a restart doesn't fetch every post again: one more field on the node line (pre-1.0, the format may change). |
| Q343 | Decided 2026-11-17. Rooms as a client are M6's step 5, released as v0.29.0; serving others (repeater, room server) stays M7. |
Measured
Step 1, feasibility (2026-11-12 and 13). On the device, with the probe build (env:cardputer-adv-ble-probe, never released: ble trial, ble log), against the released v0.27.0. The Debug Console was on throughout.
- Why the controller crashed: it asks for one contiguous 30,720-byte block when it starts and doesn't get it; the failed allocation ends in an assert that spins with interrupts off until the interrupt watchdog fires. Found by keeping the log in RTC memory, which survives that reset. Arduino's own precompiled framework does the same.
- The controller from flash (ADR 0012) takes its code out of IRAM and its memory out of the heap until it starts. Two link fixes make that mode work with Arduino's precompiled list of libraries (
scripts/ble_controller_flash.py). - Running, with Wi-Fi off (Q331), the mesh listening, advertising for 4 minutes: 46.7 KB free, the largest block 31.7 KB. BLE takes about 50 KB, once NimBLE is cut to one connection and the peripheral role (70 KB as it comes, and stopping it then left the heap fragmented: the largest block 19.4 KB until a restart). Stopped, it gives everything back. A phone connecting wasn't tried: step 3.
- Off, linked: 4.7 KB of static RAM (IRAM 2.3 KB of controller code that must stay there, NimBLE's tables 2.4 KB) and about 1.5 KB at run time: about 6 KB, under Q332's 8 KB. But that was enough to stop IRC on TLS starting beside the mesh and the VPN, so the firmware made room for it (Q334):
| Free heap, mesh Sending, VPN up | v0.27.0 | Bluetooth linked, off, and the room made |
|---|---|---|
| Idle | 64.5–65.4 KB | 74.6–75.2 KB |
| IRC online on TLS, steady | 23.5 KB | 27.9 KB¹ |
| IRC on TLS, the lowest | 3.4 KB | 6.6 KB¹ |
| Mesh off, the update task running for a Gitea check | refused: under 80 KB | refused: under 80 KB² |
¹ Measured before the last 3 KB (the Debug Console's, the network events' and esp_timer's stacks). ² 80.1 KB idle on v0.27.0, 89.5 KB here; the check's own objects take it under the 80 KB a TLS connection asks for (R1, Q172), on both. Not new: with the VPN and the Debug Console on, a check needs IRC and the mesh off.
- The room made (Q334, ADR 0012): the update task (7 KB of stack) lives only while it checks, installs or receives an Update File; the main loop listens on 3232. esp_timer's stack 8 → 3.5 KB and the FreeRTOS timer task's 3.1 → 2 KB (ESP-IDF's defaults; Arduino's are larger, nothing of ours runs on them), Arduino's network event task 4 → 3 KB, the Debug Console's 6 → 4.5 KB, each against its highest use measured (0.6, 0.7, 1.2, 3.1 KB). Tried and dropped: Wi-Fi's send buffers allocated when needed, and 6 receive buffers instead of 8, which changed nothing measurable.
- Found on the way: an Update File pushed while memory was short aborted the device (
newthrowing ininstall()); it is refused now. And the first version of the task-on-demand never accepted again after a request refused at once (a race on the task's handle): fixed, tried with two refused checks and a push after. - Q318's 5 KB: not in the image. v0.26.0 and v0.27.0 differ by 0.3 KB of static RAM; the lowest point is where TLS meets IRC's traffic and varies from one connection to the next (4.5 KB in M5, 3.4 KB here, on the same firmware).
- Firmware size: the probe is 2.95 MB, 88.5% of the app slot, with verbose logging (v0.27.0: 2.68 MB).
- Gotcha: pioarduino keeps the last framework settings in the generated
sdkconfig.defaultsand in its own package, and an interrupted rebuild leaves the hash matching: settings seemed applied and weren't. Removingsdkconfig.defaultsand the packageframework-arduinoespressif32-libsgives a clean rebuild. CI builds from a clean volume.
Step 2, the protocol (2026-11-13). lib/companion speaks MeshCore's companion protocol on a Device interface: device and self info, the node list as contacts (streamed as upstream does, since honoured), the 16 waiting messages, private messages with the app's retries answered as the first send, channel messages, the 8 channel slots, adverts, time, battery, and 01 01 for everything else (Q323, Q324). lib/companion/PROTOCOL.md is the specification read from upstream's companion firmware at our pin, with file and line for each frame, and a section on where ours differs. MeshNode gained what the app needs: a node's route, forgetting a node until its next advert (Q326) or its route, whether a message came direct, and an event when a route is learned. Host-tested: 23 protocol tests, with upstream's worked frames byte for byte and the ACK code checked against upstream's own hash, and one more two-node test (788 in all).
Step 3, the link (2026-11-14 to 17). BleLink (src/platform/ble_link.cpp) is upstream's Nordic UART service on Arduino's BLE library; CompanionService is the Device behind lib/companion, its state allocated only while Bluetooth runs; Settings → Network → Bluetooth switches it, shows the bonded phone and forgets it; ble status|on|off|forget in the Shell. With the owner's phone and MeshCore app v1.51.1: the app pairs with the PIN the device shows, reconnects by itself after a restart with the bond kept, and shows the device's name, battery, contacts and channels. A message from the app to roro-private was accepted and sent on the air; with no second radio at hand, its reception isn't checked yet (step 4).
| Free heap, mesh Sending, VPN up, Debug Console on | v0.27.0 | Step 3 |
|---|---|---|
| Bluetooth off, idle | 64.5–65.4 KB | 96.7 KB |
| Bluetooth on, advertising | (Wi-Fi off, Q331) | 44.4 KB, the largest block 31.7 KB (before the central role was back) |
| Bluetooth on, the app connected | – | about 44 KB, the lowest 30.6 KB |
| IRC on TLS, Bluetooth off, the lowest | 3.4 KB | 20.9 KB |
| IRC on TLS, Bluetooth on | – | refused: "not enough memory (38 KB free, 60 KB needed)", retried every 30 s |
- Where the 32 KB came from (ADR 0012): code moved from IRAM to flash, 17.5 KB (
.iram0.text85.8 → 68.3 KB): FreeRTOS's (its interrupt functions stay), the ring buffer's, the LED driver's (RMT), the radio PHY's helpers, newlib's misc functions, the I2C driver's interrupt handler. And IRC's task (6 KB of stack) lives only while IRC is wanted, as the update task does since step 1. - Tried and dropped: Wi-Fi's buffer settings. Arduino's
WiFiGeneric.cppsets its own at run time (no static send buffers, 4 static receive buffers) unlessuseStaticBuffers, so the framework's settings change nothing; that's why step 1 measured nothing either. And the heap's functions to flash (6 KB more): ESP-IDF allows it only if no interrupt allocates while flash is busy, which can't be ruled out for Wi-Fi. - Why pairing failed, five causes in turn, each found in the device's log over the Debug Console:
- Arduino's BLE library asks the phone to pair as soon as it connects (
setForceAuthentication, on by default), and again when it subscribes to a characteristic marked encrypted. The app asks its phone to bond at the same moment; the two pairings stalled each other until the 30 s timeout, before any PIN. Now the device never starts a pairing: TX carries no encryption flag (nothing is sent on it before the link is paired) and RX's write needs one, as upstream. - NimBLE's GATT client depends on the central role, which step 1 had cut. Without it, the indication the phone sends right after connecting went unanswered ("ATT handler not found; op=0x1d"), and the phone left 5 s later, while the PIN was being typed. The central role is back (
platformio.inisays why). - The link was cut on any failed pairing step, and NimBLE reports some while the pairing still runs. Now the phone ends a pairing that fails.
- After pairing, the device keeps one bonded phone by dropping the others' bonds (Q328). It recognised the new one by the address it connected with, a private one; the bond is under the identity address the phone gives while pairing. So the bond just made was dropped, and the link with it. Now it compares identity addresses.
- Not a cause, but it hid two of them: a new firmware confirms itself once Wi-Fi is up after its first frame; restarting before that (
ble onrestarts) rolls back to the previous one, silently. Each test build now has its own version, and the console's banner is checked after each restart.
- Arduino's BLE library asks the phone to pair as soon as it connects (
- NimBLE's buffers (8 of each kind, step 1) weren't a cause: put back to the defaults, nothing changed but 14 KB of memory; they are cut down again.
- The PIN is shown large (9x15 at twice the size). NimBLE's host task has 6 KB of stack instead of 5: pairing's key computation is its heaviest work, and it had 2.2 KB spare before.
- What the app refuses to get: each refused command is in the log, with its number and why. On connecting, v1.51.1 asks for
SET_FLOOD_SCOPE_KEY(54, protocol v8, not implemented) and one channel slot past the 8 (31, "not found", as upstream answers). The app's "Configure your device" wizard reported errors: it sets the name, the position and the radio, which the device keeps to its own Settings (Q323); skipping it is fine. What it asks exactly is to be read in the log in step 4. - Firmware size: 3.10 MB, 93% of the app slot.
Step 4, with the phone and the Heltec (2026-11-17). Checked by the owner with app v1.51.1 and the Heltec V4: a message from the app on roro-private reaches the Heltec, and the Heltec's reply shows in the app and in the Mesh App; a private message from the app to the Heltec is marked delivered, and the Heltec's reply reaches the app; messages the Heltec sent while the app was away show delivered at once (the device received them) and reach the app when it connects again. Marking the Heltec as a favourite in the app failed: the app sends the whole contact back (ADD_UPDATE_CONTACT), which the device refused; now it takes the flag (Q336). The app asked for two commands outside Q324, now answered as upstream does: GET_CONTACT_BY_KEY (30), the contact record of one node, and GET_ADVERT_PATH (42), the path a node's last advert came by and when (kept per node since the start, not on the card). Then: with Mesh on Listening, the app's message is refused (the app says "Bad State") and Sending again lets it through; Forget the phone in Settings, and the phone forgotten on its side, asks for a new PIN; restarted with Wi-Fi and GNSS off, the device took the phone's time when the app connected ("bluetooth: the time from the phone") and sent its advert with it. The app's "Configure your device" wizard couldn't be run again, and was dropped: it sets what Settings owns (Q323), and the guide says to skip it. FIRMWARE_VER_CODE 10 (PROTOCOL.md, section 8) is enough for v1.51.1: nothing it needs was missing but the commands above. The user guide has a Bluetooth page, and Bluetooth in Settings, the Status Bar, the FAQ, Updates and the memory how-to.
Step 5, rooms as a client (2026-11-17). MeshNode logs in to a room (login, upstream's sendLogin with the room's "since"), reads its answer (onContactResponse: "OK" from an older server, or RESP_SERVER_LOGIN_OK and the permissions) and its posts (onSignedMessageRecv, the author's 4 bytes with each; a post pushed again is dropped), and posts to it as to a chat node. The Mesh Service keeps the passwords (mesh_rooms, setting mesh_rooms), the state per room since the mesh started, each post in the room's conversation as "author: text", and the room's "since" in its node line (a twelfth field). lib/companion answers SEND_LOGIN, HAS_CONNECTION and LOGOUT, pushes LOGIN_SUCCESS or LOGIN_FAIL, and gives a post to the app as signed (txt_type 2, the author before the text). In the Mesh App, m on a room's page opens it, logging in with the password kept or asking for it; Ctrl+L asks again. Checked with the Heltec as a room server: logged in from the Mesh App and from the MeshCore app, posts from both delivered. A post from another member couldn't be checked, with no second client: it is covered by the host tests only. 796 host tests.
Later, from the architecture re-check (2026-11-19). Three holes in what Q336-Q338 and Q342 decided, found by reading and closed:
- Mesh off and on (Settings, a key imported, the key made) showed each private conversation twice: the channels' messages were dropped when the mesh stopped, the private ones stayed in RAM, and the read-back (Q337) added the same messages from the card again. The private conversations are now read back once a boot, by the first start whose read-back runs (it runs only with a card), so an off and on keeps them in RAM, as it always did without a card, a start from cold still reads them, and a boot without the card reads them at the first off and on after it is in. What the read-back brings and what is in RAM already (heard since the start, or kept since a boot without the card) follow one rule, for the channels and the private conversations alike, "restored, then live" (
MessageHistory::restore,DirectHistory::restore): the messages in RAM are taken out, the card's go in first by the ordinary caps, as at a cold boot (50 a conversation, the bytes, each private conversation keeping at least its newest, the least recent cut first; the private ones in the room the live ones leave), each left out that is the card's line of one in RAM (the same own flag and timestamps, its text as the card writes it,tidyText), and those in RAM come back after them as they were, ids, states and unread counts. So the caps only ever take a message from the card before a live one, one shows once, and an own message on its way keeps its state rather than its line's (me:sendingreads back failed). The read-back belongs to the start that queued it: the first Sending queues two back to back, and the earlier one's is dropped, never written while the main loop frees it; one handed over after its stop is freed before the next start measures the heap. - A private message still on its way when the mesh stopped was never closed (Q311): it stayed
sendingin RAM, and read back from itsme:sendingline it stayed so for good, out of Ctrl+R's reach. The next node's ids start at 1 again, so a new message could share an id with an old one in the same conversation, and the old one took its delivered or failed (its status line written with the old timestamp) while the new one stayedsending; the companion app's entries were matched the same way, so a new message's ACK could confirm an old one to the phone. Now the node fails what is waiting or in flight as the mesh is switched off or a key imported, each with its status line (Q338), and the companion lets a failed message's id go; an update reaches only a message still sending or sent (the newest with that id). A device restart doesn't stop the node: an own message whose last line on the card sayssendingcomes back failed, one already on the air (last linesent) comes backsent. - A node's own marks (favourite, Q336; a room's "since", Q342) ride on its advert line, the newest winning, and were lost three ways: a room pushed off the full 24-node list came back with its next advert at since 0; a room on the card but not among the 24 given to the table at start did the same; either way the line at since 0 was the newest from then on, and the next login fetched every post again. And a node heard before the card was read back made
restoreskip the card's record, so its favourite and since were dropped. One rule now brings two records of a node together (mergeOwnMarks: since the larger, the favourite the card's unless chosen since the start), applied inrestore, which then reports the node so its line on the card carries them again; the lines of one node on the card come together the same way (mergeNodeLines: the newest advert's line, since the largest of them all); the since of a room overwritten, or left out of the table at start (those with a password kept first), is kept (12 rooms at most, one overwritten later pushing out the oldest without a password, and not kept itself, without one, when all 12 have one) and given back when it is heard again; and a node line heard since the start began (written before the read-back ran, without the mark) doesn't clear a favourite the card holds, unless the time was unknown then; such lines are read all the same, so a clock that was ahead can't hide a node or its conversation.
Done when
- The app pairs with the PIN the device shows, and reconnects by itself with the bond kept; forgetting the bond in Settings makes it ask again.
- The app shows the device's name and key, and the node list as its contacts.
- A private message from the app to the Heltec shows delivered in the app, and appears in the Mesh App's conversation; the Heltec's reply reaches both.
- A message from the app on roro-private shows on the Heltec, and in the Mesh App.
- Messages received while the phone was away arrive in the app when it connects again, 16 at most.
- Connected with no Wi-Fi and no GNSS fix, the phone's time lets the device send.
- The app can't change the radio settings or reach the key; with Mesh on Listening, its messages are refused and it says so.
- With Bluetooth on, Wi-Fi stays on, and what needs TLS waits for memory, saying so (Q335).
- With Bluetooth off, free heap at idle is within 8 KB of v0.27.0's, and the floors hold with the VPN and IRC on TLS (Q332). Or, failing that, both firmwares are released and installable (Q333).
Work breakdown
- Feasibility (Q330): the controller's crash; BLE's cost started and stopped; its cost when off, made as small as the framework allows; the 5 KB of Q318. Ends with the measurements here and the choice between one firmware and two (Q332, Q333), and an ADR for the Bluetooth stack.
- The protocol (
lib/companion, host-tested): frames in and out, the commands of Q324 onMeshNodeand the Mesh Service, the waiting queue (Q327), the error reply for the rest, frames from upstream and from the app as tests. - The BLE link: Nordic UART service as upstream's, Settings → Bluetooth, the PIN and the bond, the
Bmark,ble status, Bluetooth and Wi-Fi together (Q335). If two firmwares: the second build in CI, the release and the install page. - With the phone and the Heltec: every "Done when"; the app's version; the user guide (a Bluetooth page, Settings, the FAQ, the Status Bar) at the release.
- Rooms, as a client (Q339–Q343): login, posts and posting in
MeshNode, the Mesh Service andlib/companion; a room's conversation and its password in the Mesh App; checked against the Heltec as a room server.
This page is generated from docs/milestones/M6.md in the repository. To change it, change that file and run site/tools/gen_dev_docs.py.