Smatfarm Firmware Changes

Change log for the two pieces of firmware that drive the two Smatfarm G5 reef LED fixtures over this system's second tank, both live there since November 2026: a small patch inside each fixture's own GD32F130 chip, which replaced the dead touch panel with a serial command interface, and the ESP32 controller that talks to it. The full story – how the firmware was read out, where the patch lives, and how to flash it yourself – is in the how-to, Smatfarm LED Touch Bypass. This page is the running record of what changed and why, in the same form as the doser's firmware changes. Not affiliated with Smatfarm.

Fixture patch, first version (GD32F130, impl.c)

  1. A serial command interface in place of the touch panel. Writing 0xA0–0xA5 selects channel A–F and the next byte (0–100) sets its brightness, written into the same setpoint buffer the fixture's own controls use, at 115200 baud on the fixture's serial port. It was placed over a function believed to be dead touch-handling code. It was the fan controller (fan on whenever any channel is at 20% or more), so the cooling fan on the patched fixture never ran again. The misread came from a nearby value that belonged to the previous function, not this one; disassembling the original bytes would have shown it at once. Fixed in the second version below.

Fixture patch, second version (impl.c, impl.ld, tramp.s)

  1. The patch moved to empty flash, and the fan control came back. The original function's space now holds a single jump to the patch at 0x0800a000, in a 24 KB stretch of flash the stock firmware never uses. The patch first does what the overwritten function did – fan on when any channel setpoint is at 20% or more – and then handles the serial commands. Flashing writes only the pages that change, and writes the jump last: if the jump went in first and the patch write then failed, the fixture would jump into blank flash on every pass of its main loop.
  2. The linker put the wrong function first, and it shipped. A jump to a fixed address needs the patch's entry function to be the very first byte of its page. A plain linker script does not guarantee that; the first build placed a small helper there, so the jump landed in the wrong function, the fan still never ran and no serial byte was ever read. It went unnoticed at first because the fixture had only been driven over the debug port, never over its serial line. Fixed by giving each function its own section, placing the entry function first explicitly, and adding a build-time check that fails if it is not at the start of the page.
  3. The patch's own variables ran past the end of the chip's memory. They were first placed where they extended beyond the top of the 8 KB of RAM. They now sit just below the top, above the stock firmware's stack, in RAM nothing in the stock firmware uses. The stock startup code only clears its own variables, so ours start as random values after power-up; a marker value written on first run tells the patch to initialise them.
  4. Readback: the controller can see what the fixture is doing. Sending 0xB0 returns a frame: 0xB0, a length byte, then the schedule mode (whether our control is holding or the fixture has taken back its own schedule), the fan state, the temperature (from the fixture's own thermistor, in tenths of a degree), a tick counter, the six commanded setpoints, the six live values after the fixture's internal fade, and an XOR checksum. The length byte lets a controller cope with the frame growing later. The schedule-mode byte is the important one: it is how the controller notices that the fixture lost power and quietly went back to its own schedule.
  5. The fixture's own log output could land on top of the checksum. The fixture also prints its own debug messages on the same serial line, for example for every infrared remote code it receives. One of those characters was seen sitting exactly where the checksum should have been. The frame now ends with two harmless line-ending bytes after the checksum, which absorb that, and the controller resyncs on the 0xB0 header rather than assuming a clean line.
  6. Failsafe: if the controller goes quiet, the fixture takes over again. 0xB2 hands control back to the fixture's own sunrise/sunset schedule immediately. Without any command for a set time (default one hour, changeable with 0xB3), the patch hands back by itself, so a dead controller cannot leave the lights frozen at its last value over a reef. A readback also counts as a sign of life, because a controller only writes when a value changes and a midday plateau can go for hours without one. The stock main loop calls the patch once a second, so one tick is one second; a first draft assumed a much faster loop and would have set the default to over a year.
  7. A "burst drain" that does not do what its comment says. Once the patch sees a byte waiting, it keeps reading for about half a millisecond to catch a burst of bytes in one pass. In practice that almost never helps: the chip's serial port holds only one byte, the patch runs once a second, and a burst arrives at a random moment, so by the time the patch looks, all but the last byte have been overwritten. It costs nothing and is left in, but the controller does not rely on it and paces every byte instead (item 11).
  8. Optional: hand the display to the controller. A build option sets the four display pins to inputs on every pass, so an external controller can drive the fixture's 128×32 OLED. Off in the published download, so it never blanks someone else's working screen.

Fixture #1: repairing what a bad firmware read destroyed

  1. The first firmware read was silently corrupt, and was written back. The read-out over the debug port zeroed parts of the upper half of flash in a repeating pattern – an artifact of the adapter's bulk read, not of the chip. Writing that image back to fixture #1 zeroed its fonts and menu labels, the temperature lookup table and the wireless pairing word for real. The lighting itself was never affected. On 2026-10-27 those pages were restored from the untouched fixture #2, read back one word at a time (a different path through the adapter) and cross-checked, and every page was verified after writing. The how-to now tells readers to verify a read before trusting it, and to write back only the pages the patch changes: Verify your dump before you trust it.

ESP32 controller (smatfarm.py, main.py, ui.html), version 1.1.6

  1. Every byte is paced more than a second apart. The fixture's serial port holds one byte and the patch reads it once a second, so sending a channel byte and its value together lost the first: the second overwrote it before the patch ever looked. The controller now leaves 1.15 s between bytes. A six-channel change takes about 14 seconds, which is slow but certain.
  2. A frame reader that expects interference. It looks for the 0xB0 header, reads the length byte, checks the checksum and discards anything else, since the fixture's own log text shares the line. It waits up to 1.6 s for a reply, enough for one full poll of the fixture's main loop plus the frame.
  3. It notices when the fixture takes back control. When the readback shows the fixture back on its own schedule – after a power cut, for example – the controller re-asserts the commanded values. "Hand back to fixture" (/release) gives control back deliberately and stops the controller re-asserting for 12 hours; /failsafe sets the patch's timeout.
  4. The brightness sliders hold your change. The web page refreshes its status every few seconds, which used to snap a slider back to the old value while a 14-second write was still under way. A slider you moved now stays yours for three minutes, or until the fixture reports the value you asked for.
  5. Channel E is red, not "3000K warm white". The manual and the fixture's own menu call it warm white. Driving each channel on its own showed a red emitter. It is relabelled in the controller, and a reef lighting mix that ran it at 20% (assuming warm white) now runs it at 5%. Channel F was confirmed as 500 nm green the same way; the labels for A–D still come from the manual and have not been checked individually.
  6. Updates over the network, file by file. The controller downloads a manifest, fetches only changed files, checks each one's hash as it downloads, and renames them into place only once every file has arrived and verified – so a power cut or bad connection mid-update leaves the running version untouched.

Fixture patch, third version: the screen (v3.0–v3.6)

  1. The controller writes to the fixture's own screen, through the fixture's firmware. Instead of rewiring the OLED to the ESP32 (the earlier build option), the ESP32 sends text lines over the serial link and the patch draws them into the firmware's own display buffer, using the firmware's own font and drawing routines. No extra wires, and the fixture's menus keep working.
  2. The firmware's clock kept painting over it. The stock home screen redraws once a second, so our text flashed up and vanished. The patch now steps in front of that one routine: while the controller owns the screen, the clock is skipped; open a menu and the firmware's own screens come back.
  3. The screen stays on, and dims at night. The screensaver limit is rewritten by the firmware every second from its own setting, so changing it once did nothing; the patch re-raises it every tick instead. Brightness follows the day: normal by day, lowest at night.
  4. Text bytes were lost while interrupts ran. The serial port has no receive buffer beyond one byte, and the fixture's other interrupts sometimes delayed the read long enough to lose one. A line of text then arrived with letters missing and was silently discarded. Text is now received with interrupts briefly held off (a few milliseconds), the fixture confirms each line, and the controller retries up to three times.
  5. Memory survives the reset after flashing. After a flash over the debug port only the processor core resets; RAM keeps its contents. A new build that used the same "already initialised" marker as the old one skipped its own set-up and ran on leftover values. The marker now changes with every build.
  6. Two status icons. A Wi-Fi symbol, set by the controller, and a link symbol the fixture draws itself, struck through when it has not heard from the controller for five minutes. At power-up the screen says it is waiting for the controller, and falls back to the fixture's own clock after ten minutes.
  7. Quiet boot. At power-up the stock firmware ramps every channel up to full and back down, about twelve seconds of a light test. Harmless on a bench; over a reef after a night-time power cut it is a full-power flash. The patch skips it.
  8. The fixture says hello. After a restart it announces itself every second until the controller answers, so the light curve is put back within seconds instead of at the controller's next scheduled check.
  9. A pictorial screen (v3.6). A large clock, bars for the six channels, a sun or moon, the fan and the fixture temperature, and a blinking alarm. The controller rotates pages every fifteen seconds: light, the latest water tests, system status, and alarms when there are any; at night only the light page. One bug found on the way: the receive check rejected every large-font line, so alarm banners never appeared while the controller spent three retries on each.

Updating the fixture without a debug probe (A/B slots)

  1. A small permanent core plus two update slots. The core does only what must never break: the serial commands, fan control, the failsafe and the updater. The screen and radio features live in one of two slots. An update is written into the inactive slot over the controller's serial link, its header goes in last, and the fixture switches only when the whole slot checks out. Rolling back revokes the new slot and the old one takes over again. On the fixture an update takes about four seconds, with the lights untouched.
  2. The watchdog was never running. The firmware feeds a hardware watchdog in its main loop but never starts it, and the chip's option bytes leave it off. So a hang would simply have frozen the lights. The core now starts it itself (about 26 seconds), and a crash guard marks a slot bad if the fixture resets three times within a minute, falling back to the other slot.
  3. Tested on an emulator running the real firmware, then on the fixture. The fixture's own firmware dump plus the patch runs in an emulator, with tests for every command, a corrupted upload, rollback, the crash guard, and a power cut at 84 points in the middle of an update. On hardware it was proven with the debug probe still attached as a safety net: an update into the second slot, a switch, and a rollback.
  4. The controller checks for updates and asks. At start-up and every six hours it compares against the published version and shows an arrow on the screen, a banner on its web page, and a notification. Installing stays a button press, never automatic.

Radio failover between the two lamps (v3.8)

  1. The fixtures have a radio, and its stock behaviour is unsafe. One lamp can be set as master and the other follows it. But a stock follower whose master dies simply freezes at the last value it received, indefinitely.
  2. Both lamps lead, and the survivor takes over. Normally each lamp runs from its own controller and transmits. If a lamp hears nothing from its controller for five minutes, it switches to following the other lamp. If it then hears no radio for a minute, it runs its own sunrise/sunset schedule, and retries every ten minutes. When its controller comes back, it leads again and the controller re-applies all six channels.
  3. Tested live. With one controller unplugged, its lamp switched to following after 308 seconds, tracked the other lamp through a step in the light curve without a jump, and went back to leading when the controller was plugged in again.
  4. The setting is stored with the firmware's own flash routine, not a hand-written one. Checked over the debug port on one lamp: exactly one byte of the settings page changed.
  5. Touch keys switched off. The front keys are disabled in firmware; the infrared remote still works.

ESP32 controller, versions 1.1.7–1.5.0

  1. 1.1.7: clock and start-up. The time comes from the update server's own replies, so the controller does not need internet access for NTP. After a restart it waits for the fixture's first status report before driving it, and re-asserts the curve at once if the fixture has taken back control.
  2. Two controllers, one set of files, two update channels. The second lamp's ESP32 board has a different memory type and needs a different MicroPython build. The controller files themselves are identical, but each lamp updates from its own channel, so one can be tested before the other.
  3. 1.2–1.3: screen pages. The reef server now sends, along with the light curve, the latest water tests, doser and main-display light status, moon phase, cloud cover and active alarms, and the controller turns them into the screen pages above.
  4. 1.4: fixture updates over the serial link, with the update check and install and rollback buttons. 1.5: radio settings on the controller's page, and the six channels re-applied when a failover ends.

Still open. The absolute light level has not been measured: the curve is right in shape, but setting it against a coral needs a PAR meter. After a controller restart the water-test and status pages stay empty until the reef server's next push, up to fifteen minutes. A factory copy of fixture #2's firmware is kept as the reference image.

Current state, 15 November 2026: both fixtures are live over the second tank, each with its own ESP32 controller on version 1.5.0, fixture patch v3.8 in the update slot, touch keys off, and radio failover between them.