somfy-thread developer guide ← Setup Hardware GitHub

Serial console

The firmware exposes a line-oriented console over the ESP32-C6 native USB (USB Serial/JTAG), 115200 baud, 8N1. The setup wizard on the home page drives it through WebSerial — everything below is the same command surface, so you can also type these into any serial terminal (screen, picocom, PlatformIO monitor…).

Only one process can hold the port at a time. Close the setup page's serial session (or your terminal) before opening the other.

Commands are case-sensitive. Addresses are hex (24-bit), rolling codes and indices are decimal. Most commands answer OK, OK <idx>, an ERR … line, or a one-line JSON document.

Command reference

CommandWhat it doesResponse
versionFirmware id, version and store protocol.somfy-thread <ver> proto <n>
log [0|1]Get/set Thread+Matter diagnostic logging.{"log":0}
radioRadio status: rf link, frequency, rssi, power, rxbw and the selectable options.JSON object
listAll shades as JSON. Reports the live mid-move estimate for a shade in motion.JSON array (see below)
add [hexaddr] [rolling] [name…]Register a shade in the first free slot and bring its Matter endpoint online. No address ⇒ a MAC-derived one is invented (PROG path); rolling defaults to 1.OK <idx> · ERR full · ERR endpoint
remove <idx>Take the shade off Thread and free its slot.OK · ERR bad idx
on <idx> <0|1>Exposure switch. 1 resumes the endpoint on Thread (same stable id); 0 destroys it, keeping the id for later.OK
link <idx> <hexaddr> [rolling]Monitor a physical wall remote so pressing it mirrors the shade's position. Never transmitted as. link <idx> 0 clears it.OK
unlink <idx>Stop monitoring the linked remote.OK
tx <idx> <up|down|my|stop|prog> ⚠️Transmits RF. Sends a Somfy command and advances the rolling code.OK · ERR bad idx/cmd
name <idx> <text>Rename a shade (≤15 chars).OK
freq [mhz]Get/set the radio frequency (e.g. 433.42). Applied live.current freq
power [idx]Get/set TX power (index into the radio power options).current index
rxbw [idx]Get/set RX bandwidth (index into the radio rxbw options).current index
reg [hexaddr] [hexval]Dump / read / write CC1101 registers (debug).register dump
addr <idx> <hex24>Set the 24-bit Somfy address the shade transmits as.OK
roll <idx> <value>Set the rolling code counter (decimal). Use to sync from an existing controller.OK
pos <idx> <up_ms> <down_ms> [my_pct] [invert] [up_lag_ms] [down_lag_ms]Position-estimate parameters. Trailing args left unchanged if omitted. 0 travel time ⇒ snap instead of ramp.OK
exportFull shade table for backup (settled positions).JSON array (see below)
qrMatter onboarding QR payload.MT:… string
pairOpen the commissioning window and print the manual pairing code.pairing code
mstatMatter status: commissioned fabric count, Thread role, commissioning window.{"fabrics":0,"thread":0,"win":1}
fabricsCommissioned fabrics (index, vendor, fabric id).JSON array
dumpDebug: aggregator endpoint + per-cover NodeLabel.text
resetReset Matter + Thread (keeps shades) and reboot.reboots
factoryFull factory reset: erase shades and Matter/Thread, reboot.reboots
rebootReboot the device, no data change.reboots

Shade JSON (list / export)

One object per used slot, on a single line:

{"idx":0,"name":"Salon","addr":"0EB998","rolling":1498,"on":true,
 "remote":true,"link":"6FDA96","up_ms":35000,"down_ms":30000,
 "my":255,"invert":true,"up_lag":0,"down_lag":0,"pos":0}
FieldMeaning
idxSlot index — stable per shade, used by every mutating command.
nameDisplay name (≤15 chars).
addr24-bit Somfy address (hex) the shade transmits as.
rollingRolling-code counter. Must stay ahead of what the motor last accepted.
onExposed as a Matter WindowCovering endpoint over Thread.
remoteCloned from a physical remote (true) vs PROG-paired (false).
linkAddress of a monitored wall remote (000000 = none).
up_ms / down_msFull-open / full-close travel times (ms). 0 = snap to target.
myFavourite ("my") position 0–100. 255 = unset.
invertSwap open/close for reversed installs.
up_lag / down_lagStartup dead-time before the shade visibly moves (ms).
posCurrent lift estimate, 0–10000 (hundredths of a percent, 0 = open).

Expectations & gotchas