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
| Method | Description |
|---|---|
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
| Method | Description |
|---|---|
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
| Method | Callback | When |
|---|---|---|
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
| Method | Description |
|---|---|
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.
| Method | Data 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
| Name | Meaning |
|---|---|
cid | The CID received (12 characters at most). Empty before ready. |
state | The 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. |
lastReason | The reason the server gave in the last authentication clear |
pingPeriod | Seconds without receiving before a PING is sent (50 by default) |
Payload types
| Value | Name | Meaning |
|---|---|---|
| 0 | IOSignal::EMPTY | No data |
| 1 | IOSignal::TEXT | A string |
| 2 | IOSignal::BINARY | Binary |
| 3 | IOSignal::OBJECT | One JS object (JSON) |
| 4 | IOSignal::MJSON | Several arguments (a JSON array) |
| 5 | IOSignal::MBA | Several arguments with binary |
Arduino does not unpack OBJECT, MJSON or MBA; it hands over the raw bytes.
Constants
| Constant | Value | Meaning |
|---|---|---|
DEFAULT_RX_BUF_SIZE | 80 | The receive buffer when setRxBuffer() was not called |
DEFAULT_TX_BUF_SIZE | 50 | Larger sends allocate memory of their own |
MAX_CID_LEN | 12 | The longest CID |
SERVER_HELLO_TIMEOUT_MS | 10000 | How long to wait for the server's first reply |
RECONNECT_WAIT_MS | 3000 | How long to wait before connecting again |
PONG_TIMEOUT_MS | 15000 | How 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.
| Method | Description |
|---|---|
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. |