Home›Plugin›Hardware›Firmware SDK

Firmware SDK

Build your own controller for Simulation Instruments Studio · line protocol

Your own switches, knobs, LEDs and displays can talk to Simulation Instruments Studio with nothing more than short lines of plain text. If a microcontroller can print a line over a serial port, it can be a Studio controller. No driver to install, no binary format to decode, and you can watch every message go by in a serial monitor while you debug.

• Use the board you like. The ready-made firmware covers ESP32, Arduino AVR boards and the Raspberry Pi Pico. This page is for everything else, or for when you want your own firmware.
• Same text everywhere. USB serial, Wi-Fi and Bluetooth LE carry exactly the same lines.
• Your instruments don’t change. Instrument scripts keep calling the hw_ functions. Studio turns those calls into the lines below.

If you just want to wire a board and go, use the ready-made firmware on the Hardware page. Everything here is taken from that firmware and from Studio itself.

On this page

1. Line format
2. Connections: USB, Wi-Fi, Bluetooth LE
3. Connecting: HELLO, PINS, WHO and PING
4. Messages from the board
5. Messages to the board
6. Message port payloads
7. Saved settings: CFG, WIFI, HOST, BOARD
8. How each hw_ function maps to lines
9. Which boards support what
10. Example sketch: one button and one LED
11. Limits and known gaps

Line format

• Plain ASCII text, one message per line, ending in a newline (\n). A carriage return (\r) before it is ignored.
• Fields are separated by one space. The first field is the message name, in capitals.
• Pins are the board’s own GPIO numbers, written as plain integers (BTN 32 1).
• Empty lines are ignored. A line the board doesn’t understand should be ignored quietly.

Connections

USB serial (the normal way)

• 115200 baud, 8 data bits, no parity, 1 stop bit (8N1), no flow control. Studio opens the port with DTR and RTS off.
• Studio scans for new serial ports every 3 seconds. It accepts a port when the board sends HELLO within about 1.2 seconds of opening it. If nothing arrives, Studio sends WHO and PING and accepts the port if HELLO or PONG comes back within about 2.5 seconds. Ports that don’t answer are skipped until they are unplugged.
• Many boards reset when the port opens, so the simplest firmware just prints HELLO at start-up. Answering WHO covers boards that don’t reset.
• On ESP32-S3 and ESP32-C3 boards with native USB, turn on USB CDC On Boot so the serial port is the USB port.

These are environment variables, set before Studio starts.

Wi-Fi (TCP port 4731)

Wi-Fi is optional. Studio only uses it when the environment variable SIS_HW_WIFI=1 is set before it starts. The lines on the TCP connection are the same as on USB.

• Access-point mode (no network saved on the board). The ESP32 firmware opens its own open Wi-Fi network named SIS-HW at 192.168.4.1 and listens on TCP port 4731. A computer on that network connects to 192.168.4.1:4731 and keeps the connection open, reconnecting every 3 seconds if it drops. The newest connection wins, so a quick setup connection also works. SIS_HW_HOST and SIS_HW_HOST_PORT change the address and port Studio connects to; SIS_HW_HOST=0 turns this outgoing connection off.
• Station mode (after WIFI and HOST were saved). The board joins your cockpit network and connects out to the computer at HOST, port 4731, where Studio listens. If the connection drops, the firmware tries again every 3 seconds. SIS_HW_WIFI_PORT changes the port Studio listens on.
• Studio pings Wi-Fi boards that connected to it every 2 seconds and closes the link after 10 seconds without hearing anything.
• On a classic ESP32, analog inputs only read on ADC1 pins (GPIO 32 to 39) while Wi-Fi is running.

Bluetooth LE (Windows only for now)

• A Nordic UART style service, with no pairing: service 6E400001-B5A3-F393-E0A9-E50E24DCCA9E, RX 6E400002-B5A3-F393-E0A9-E50E24DCCA9E (Studio writes here) and TX 6E400003-B5A3-F393-E0A9-E50E24DCCA9E (the board sends notifications here).
• The ESP32 firmware advertises as SIS- plus the board name, with _ and spaces turned into -, so ESP32_B becomes SIS-ESP32-B.
• Same text lines as USB. Studio asks for an MTU of 247. The board sends lines in chunks of up to MTU − 3 bytes, and the receiver joins chunks and splits on newlines.
• Send HELLO and the PINS table each time Studio subscribes to TX.
• Studio reconnects remembered boards on its own and pings them every 2 seconds, closing the link after 10 seconds of silence. SIS_HW_BLE=0 turns Bluetooth off.
• Bluetooth works in the Windows version of Studio only for now. Flashing always uses USB.

More than one connection to the same board

If a board with the same HELLO name is on several links, Studio uses USB first, then Bluetooth LE, then Wi-Fi. It sends only on the best link and ignores input from the others until that link goes away. So it’s fine for firmware to send every event on every link it has open.

Connecting: HELLO, PINS, WHO and PING

1. When a connection opens, the board sends HELLO <name> [version], then its pin table: PINS BEGIN, one PINS <line> per entry, PINS END.
2. The name is how instruments address the board (name/12 means GPIO 12 on that board). Use letters, digits and _, no spaces and no /. A second field that contains / (or looks like sis-xxx/1) is treated as a version, not a name.
3. After each HELLO, Studio re-sends every runtime item the open instruments declared (inputs, outputs, displays, steppers, button arrays) and then sends QUERY. Your firmware doesn’t need to remember them across restarts. A second identical HELLO within 3 seconds is not treated as a reconnect.
4. WHO asks the board to send HELLO and its PINS table again. PING asks for PONG. Studio pings every board every 2 seconds. Answer on the link the request came from.

board: HELLO OVERHEAD my-fw/1
board: PINS BEGIN
board: PINS BTN 32
board: PINS SW 25
board: PINS END
app:   IN 4
board: SW 4 0
app:   QUERY
board: SW 25 1
board: BTN 32 0
app:   PING
board: PONG

Messages from the board

For BTN, SW, DIAL, ENC and ADC, Studio reads the second field as the pin and the third as a number. Lines with a non-numeric third field are ignored.

Messages to the board

Outputs

Inputs added at run time

Character displays

On MAX7219 the ready-made firmware can show digits 0 to 9, -, E, H, L, P, blank and .; other characters show blank. Text is left-aligned.

Stepper motors

Connection and setup

The ids in CHR, STEP and BA are numbers Studio picks; they are unique while Studio runs. IN, ADC, DAC, PWM, SRV, OUT, CHR, STEP and BA are not saved on the board; Studio sends them again after every HELLO.

Message port payloads

MSG <port> <msg_id> <type> <payload> works in both directions. port is the port name (no spaces), msg_id an integer, and the payload is everything after the fourth space, so it may contain spaces.

Escaping: %, carriage return and newline are sent as %25, %0D and %0A. Undo it when reading (lower-case %0a and %0d are accepted too).

When an instrument sends, Studio writes the type in capitals (default STRING). True and false become 1 and 0, and a table becomes its values joined by commas. Example: MSG radio 7 STRING COM1%0A118.50.

Saved settings: CFG, WIFI, HOST and BOARD

These lines are kept in the board’s own storage and survive a restart. Studio sends them from the Hardware tab.

Studio sends a pin table as BOARD (when a name is set), CFG CLEAR, one CFG line each, then CFG END. Setup over the access point sends WIFI, HOST and BOARD on one connection. All saved inputs use the internal pull-up and are active LOW.

How each hw_ function maps to lines

A pin written name/12 goes only to the board that said HELLO name; a bare 12 goes to every board. The board name is removed before the line is sent.

Pin names such as ESP32_GPIO_27, GPIO27 or D2 become the plain number at the end. The full call reference is on the hw_ functions page.

Which boards support what

The AVR and Pico firmware name themselves after the board type and a channel letter, for example HELLO ARDUINO_NANO_A sis-avr/1, followed by ID ARDUINO_NANO A. CHANNEL B changes the letter, saves it and sends HELLO again. Lines a board doesn’t support are ignored.

Example sketch: one button and one LED

An Arduino-style sketch for any board with a USB serial port. A button from GPIO 4 to ground is reported as BTN 4, and GPIO 2 follows LED and OUT. The board calls itself MYPANEL.

// Minimal Simulation Instruments Studio controller: one button, one LED.
const char *NAME = "MYPANEL";
const int BUTTON = 4;   // to ground, internal pull-up
const int LED_PIN = 2;

bool down = false, raw = false;
unsigned long since = 0;
String line;

void hello() {
  Serial.print("HELLO "); Serial.print(NAME); Serial.println(" my-fw/1");
  Serial.println("PINS BEGIN");
  Serial.print("PINS BTN "); Serial.println(BUTTON);
  Serial.println("PINS END");
}

void report() {
  Serial.print("BTN "); Serial.print(BUTTON); Serial.print(' '); Serial.println(down ? 1 : 0);
}

void handle(const String &s) {
  int pin, value;
  if (s == "PING") { Serial.println("PONG"); return; }
  if (s == "WHO") { hello(); return; }
  if (s == "QUERY" || s == "QUERY " + String(BUTTON)) { report(); return; }
  if (sscanf(s.c_str(), "LED %d %d", &pin, &value) == 2 || sscanf(s.c_str(), "OUT %d %d", &pin, &value) == 2) {
    if (pin == LED_PIN) { pinMode(LED_PIN, OUTPUT); digitalWrite(LED_PIN, value ? HIGH : LOW); }
  }
  // Anything else is ignored.
}

void setup() {
  Serial.begin(115200);
  pinMode(BUTTON, INPUT_PULLUP);
  down = raw = digitalRead(BUTTON) == LOW;
  delay(100);
  hello();
}

void loop() {
  while (Serial.available()) {
    char c = Serial.read();
    if (c == '\r') continue;
    if (c != '\n') { if (line.length() < 200) line += c; continue; }
    line.trim();
    if (line.length()) handle(line);
    line = "";
  }
  bool now = digitalRead(BUTTON) == LOW;   // debounce: must hold 20 ms
  if (now != raw) { raw = now; since = millis(); }
  else if (now != down && millis() - since >= 20) { down = now; report(); }
}

In an instrument:

local led = hw_led_add("MYPANEL/2", 0)
hw_button_add("MYPANEL/4",
  function() hw_led_set(led, 1) end,
  function() hw_led_set(led, 0) end)

Limits and known gaps

• Bluetooth LE works in the Windows version of Studio only for now.
• No UDP or WebSocket. The connections are USB serial, TCP 4731 and Bluetooth LE.
• Character displays: the ready-made firmware drives MAX7219 7-segment modules only (up to 2 chains of 8). Character LCDs, TM1637 and I2C displays need your own firmware. The line field in CHR TXT is sent, but the ready-made firmware shows one line per display.
• Buttons, switches and dials declared with hw_button_add, hw_switch_add or hw_dial_add are not announced to the board. The board has to report those pins on its own, for example from its saved CFG table.
• LED lines and stepper CAL lines are not sent again after a reconnect; the other outputs are.
• Line length: the ESP32 firmware keeps up to 400 characters per line, the AVR and Pico firmware 95. Keep lines short.
• Table sizes in the ESP32 firmware: 16 buttons, 8 switches, 8 dials, 8 encoders, 8 analog inputs, 2 displays, 4 steppers, 2 button arrays. AVR and Pico: 48 inputs, 16 analog inputs, 8 encoders, 2 button arrays.
• Analog change threshold: the ESP32 firmware reports a move of 16 or more (checked every 20 ms); AVR and Pico report a move of more than 8.
• Wi-Fi network names can’t contain spaces in WIFI; passwords can.
• There is no checksum or acknowledgement. Studio relies on PING/PONG, re-sending after HELLO and QUERY to stay in step.