Skip to main content

Arduino API

The public API of the IOSignal Arduino library (#include <IOSignal.h>, as of 9.21.0). The steps for a first connection are in Get started with Arduino and D1 mini and ESP32-C3 channel messaging; the source of truth is IOSignal.h.

#include <IOSignal.h>

WiFiClient client;
IOSignal io;

void onReady() { // on every connection, reconnections included
io.subscribe("#homeButton");
}

void onMessage(char* tag, uint8_t type, uint8_t* payload, size_t size) {
if (strcmp(tag, "#homeButton") == 0) { /* ... */ }
}

void setup() {
io.setRxBuffer(200); // before begin()
io.onReady(onReady);
io.onMessage(onMessage);
io.begin(&client, "io.iosignal.net", 55488);
}

void loop() {
io.loop(); // call it all the time
}

Connection​

MethodDescription
begin(Client* client, const char* host, uint16_t port)Starts connecting to the server's TCP port. Client is the board's network client, such as WiFiClient or EthernetClient. Do not put ws:// in the host.
loop()Handles receiving, reconnecting and connection checks. Call it from loop() all the time. It does not block while reconnecting.
setRxBuffer(size_t size)The largest frame the board receives (80 bytes by default). The size is sent to the server on connecting, and the server does not send this board anything larger. Call it before begin().
close(uint8_t reason)Tells the server and closes the connection.

After a lost or failed connection, the library tries again after 3 seconds. Without the server's first reply within 10 seconds of connecting, it closes and tries again; when nothing has arrived for pingPeriod (50 seconds by default) it sends a PING and reconnects if there is no reply within 15 seconds. The whole flow is in connection and CID lifecycle.

Authentication​

MethodDescription
auth(const char* idKey)Sets a device key in "id.key" form. It logs in automatically on every connection and gets the fixed CID registered on the server. Call it before begin().
auth(const char* id, const char* key)The same, with ID and key apart.
login(const char* id, const char* key)Logs in once on the current connection. Sent only when the server is ready or the state is ready.

When the same key logs in elsewhere and replaces this connection, the library clears the credentials and stops in IO_STOP, and onError is called with IO_AUTH_CLEAR. The server's reason stays in lastReason. Authentication clear and logs

Callbacks​

MethodCallbackWhen
onReady(cb)void cb()Every time the board gets a CID and can send and receive. Subscribe and send the first state here.
onMessage(cb)void cb(char* tag, uint8_t type, uint8_t* payload, size_t size)When a signal arrives. Everything arrives in this one callback.
onError(cb)void cb(uint8_t code)IO_AUTH_FAIL (login refused), IO_AUTH_CLEAR (authentication clear), CongPacket::OVER_SIZE (a frame larger than the receive buffer was skipped) and others
setLog(cb)void cb(const char* line)One line per connection or authentication event. Without it the library prints nothing.

type in onMessage is one of the payload types below. Before using a payload as a string, check that type == IOSignal::TEXT and that the last byte is 0. A direct signal (<my CID>@topic) arrives with the tag @topic.

Subscriptions​

MethodDescription
subscribe(const char* tag)Subscribes to a tag; a comma list sends several at once. It is sent only when ready, so call it in onReady. The server forgets a lost connection's subscriptions, so subscribe again on every connection.
unsubscribe(const char* tag = "")Stops a subscription. An empty tag stops all of them.

Direct signals (@, @topic) need no subscription.

Sending​

Everything is sent only when ready, and tags are 255 bytes at most.

MethodData sent
signal(tag)No data (EMPTY)
signal(tag, const char* text)A string (TEXT)
signal(tag, const char* a, const char* b)Two strings (MJSON); JS receives (tag, a, b). Leave out double quotes, backslashes and control characters.
signal(tag, const uint8_t* data, uint32_t len)Binary (BINARY)
signal2(target, topic, …)Sends like signal() above with target and topic joined as the tag. For example, signal2(targetCid, "@", "on") sends on to <targetCid>@.
signal_e2e(tag, const uint8_t* data, uint32_t len, const char* key)Binary encrypted with a key known only to both ends; even the server cannot read it.

JS compatibility per type is in payload formats and JS–Arduino compatibility.

State and fields​

NameMeaning
cidThe CID received (12 characters at most). Empty before ready.
stateThe connection state. The board sends and receives in IO_READY (19). Others include IO_CONNECTING, IO_OPEN, IO_SERVER_READY, IO_AUTH_REQ, IO_AUTH_FAIL, IO_AUTH_CLEAR, IO_CLOSED, IO_STOP and IO_REDIRECTING.
lastReasonThe reason the server gave in the last authentication clear
pingPeriodSeconds without receiving before a PING is sent (50 by default)

Payload types​

ValueNameMeaning
0IOSignal::EMPTYNo data
1IOSignal::TEXTA string
2IOSignal::BINARYBinary
3IOSignal::OBJECTOne JS object (JSON)
4IOSignal::MJSONSeveral arguments (a JSON array)
5IOSignal::MBASeveral arguments with binary

Arduino does not unpack OBJECT, MJSON or MBA; it hands over the raw bytes.

Constants​

ConstantValueMeaning
DEFAULT_RX_BUF_SIZE80The receive buffer when setRxBuffer() was not called
DEFAULT_TX_BUF_SIZE50Larger sends allocate memory of their own
MAX_CID_LEN12The longest CID
SERVER_HELLO_TIMEOUT_MS10000How long to wait for the server's first reply
RECONNECT_WAIT_MS3000How long to wait before connecting again
PONG_TIMEOUT_MS15000How long to wait for a reply after a PING

Board settings IOSignalConfig (ESP32, ESP8266)​

With #include <IOSignalConfig.h>, Wi-Fi, server, device key and sketch settings are entered from a browser over USB and stored by the board. Stored values win over the sketch values. Usage is in board settings.

MethodDescription
begin(Serial, name, ssid, pass)Starts the settings support. When ssid and pass are not the placeholder ("WIFI_SSID"), the sketch values are used.
setServer(host, port) / setKey("id.key")The sketch's default server and device key
host(), port(), key()The server and key to use (stored > sketch). When key() is set, log in with io.auth(config.key()).
loop()Handles browser requests and Wi-Fi reconnection. Call it from loop() all the time.
connected()Whether Wi-Fi is connected. Call io.loop() when it is true.
printServer()Prints the server to use on serial.