Arduino API
IOSignal Arduino 라이브러리(#include <IOSignal.h>, 9.21.0 기준)의 공개 API입니다. 처음 연결하는 순서는 Arduino 시작하기와 D1 mini·ESP32-C3 채널 송수신에, 기준 소스는 IOSignal.h에 있습니다.
#include <IOSignal.h>
WiFiClient client;
IOSignal io;
void onReady() { // 연결될 때마다(재접속 포함)
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); // begin() 전에
io.onReady(onReady);
io.onMessage(onMessage);
io.begin(&client, "io.iosignal.net", 55488);
}
void loop() {
io.loop(); // 계속 호출
}
연결
| 메서드 | 설명 |
|---|---|
begin(Client* client, const char* host, uint16_t port) | 서버의 TCP 포트로 연결을 시작합니다. Client는 WiFiClient, EthernetClient처럼 보드의 네트워크 클라이언트입니다. 호스트에 ws://를 붙이지 않습니다. |
loop() | 수신 처리, 재접속, 연결 확인을 합니다. loop()에서 계속 호출합니다. 다시 연결하는 동안에도 멈추지 않습니다. |
setRxBuffer(size_t size) | 받을 수 있는 가장 큰 프레임(기본 80바이트)입니다. 크기는 접속할 때 서버에 전달되고, 서버는 그보다 큰 메시지를 이 보드에 보내지 않습니다. begin() 전에 호출합니다. |
close(uint8_t reason) | 서버에 종료를 알리고 연결을 닫습니다. |
연결이 끊기거나 연결에 실패하면 3초 뒤 다시 시도합니다. 연결 뒤 10초 안에 서버의 첫 응답이 없으면 닫고 다시 시도하고, 아무것도 받지 못한 채 pingPeriod(기본 50초)가 지나면 PING을 보내 15초 안에 응답이 없을 때 다시 연결합니다. 흐름 전체는 연결과 CID 수명주기에 있습니다.
인증
| 메서드 | 설명 |
|---|---|
auth(const char* idKey) | "id.key" 형식의 장치 키를 정합니다. 연결될 때마다 자동으로 로그인하고, 서버에 등록된 고정 CID를 받습니다. begin() 전에 호출합니다. |
auth(const char* id, const char* key) | 위와 같고 ID와 키를 따로 받습니다. |
login(const char* id, const char* key) | 지금 연결에서 한 번만 로그인합니다. 서버 준비나 ready 상태일 때만 보냅니다. |
같은 키로 다른 곳에서 로그인해 이 연결이 교체되면 라이브러리는 인증 정보를 지우고 IO_STOP 상태로 멈추며, onError가 IO_AUTH_CLEAR로 불립니다. 서버가 보낸 사유는 lastReason에 남습니다. 인증 해제와 로그
콜백
| 메서드 | 콜백 | 언제 |
|---|---|---|
onReady(cb) | void cb() | CID를 받아 송수신할 수 있게 될 때마다. 구독과 첫 상태 알림을 여기서 합니다. |
onMessage(cb) | void cb(char* tag, uint8_t type, uint8_t* payload, size_t size) | 신호를 받을 때. 모든 수신이 이 콜백 하나로 옵니다. |
onError(cb) | void cb(uint8_t code) | IO_AUTH_FAIL(로그인 거부), IO_AUTH_CLEAR(인증 해제), CongPacket::OVER_SIZE(수신 버퍼보다 큰 프레임을 건너뜀) 등 |
setLog(cb) | void cb(const char* line) | 연결·인증 상황을 한 줄씩 받습니다. 설정하지 않으면 아무것도 출력하지 않습니다. |
onMessage의 type은 아래 데이터 유형 값입니다. 문자열로 쓰기 전에 type == IOSignal::TEXT인지, 마지막 바이트가 0인지 확인합니다. 직접 수신(<내 CID>@topic)은 태그가 @topic으로 옵니다.
구독
| 메서드 | 설명 |
|---|---|
subscribe(const char* tag) | 태그를 구독합니다. 쉼표로 여러 개를 한 번에 보낼 수 있습니다. ready일 때만 보내므로 onReady에서 호출합니다. 서버는 끊긴 연결의 구독을 잊으므로 연결마다 다시 구독해야 합니다. |
unsubscribe(const char* tag = "") | 구독을 해제합니다. 빈 태그는 모든 구독을 해제합니다. |
직접 수신(@, @topic)은 구독하지 않습니다.
보내기
모든 송신은 ready일 때만 나가며, 태그는 255바이트 이하입니다.
| 메서드 | 보내는 데이터 |
|---|---|
signal(tag) | 데이터 없음(EMPTY) |
signal(tag, const char* text) | 문자열(TEXT) |
signal(tag, const char* a, const char* b) | 문자열 두 개(MJSON). JS는 (tag, a, b)로 받습니다. 따옴표·역슬래시·제어문자는 넣지 않습니다. |
signal(tag, const uint8_t* data, uint32_t len) | 바이너리(BINARY) |
signal2(target, topic, …) | target과 topic을 이어 붙인 태그로 위 signal()과 같이 보냅니다. 예: signal2(targetCid, "@", "on")은 <targetCid>@로 on을 보냅니다. |
signal_e2e(tag, const uint8_t* data, uint32_t len, const char* key) | 양 끝만 아는 키로 암호화한 바이너리. 서버도 읽지 못합니다. |
유형별 JS 호환은 데이터 형식과 JS·Arduino 호환성에 있습니다.
상태와 필드
| 이름 | 뜻 |
|---|---|
cid | 받은 CID(최대 12자). ready 전에는 비어 있습니다. |
state | 연결 상태. IO_READY(19)일 때 송수신합니다. 그 밖에 IO_CONNECTING, IO_OPEN, IO_SERVER_READY, IO_AUTH_REQ, IO_AUTH_FAIL, IO_AUTH_CLEAR, IO_CLOSED, IO_STOP, IO_REDIRECTING 등 |
lastReason | 마지막 인증 해제에서 서버가 보낸 사유 |
pingPeriod | 받은 것이 없을 때 PING을 보내는 간격(초, 기본 50) |
데이터 유형
| 값 | 이름 | 뜻 |
|---|---|---|
| 0 | IOSignal::EMPTY | 데이터 없음 |
| 1 | IOSignal::TEXT | 문자열 |
| 2 | IOSignal::BINARY | 바이너리 |
| 3 | IOSignal::OBJECT | JS 객체 하나(JSON) |
| 4 | IOSignal::MJSON | 여러 인자(JSON 배열) |
| 5 | IOSignal::MBA | 바이너리가 섞인 여러 인자 |
Arduino는 OBJECT·MJSON·MBA를 자동으로 풀지 않고 원시 바이트로 넘깁니다.
상수
| 상수 | 값 | 뜻 |
|---|---|---|
DEFAULT_RX_BUF_SIZE | 80 | setRxBuffer()를 부르지 않았을 때의 수신 버퍼 |
DEFAULT_TX_BUF_SIZE | 50 | 이보다 큰 송신은 메모리를 따로 잡아 보냅니다 |
MAX_CID_LEN | 12 | CID 최대 길이 |
SERVER_HELLO_TIMEOUT_MS | 10000 | 서버 첫 응답을 기다리는 시간 |
RECONNECT_WAIT_MS | 3000 | 다시 연결하기 전 기다리는 시간 |
PONG_TIMEOUT_MS | 15000 | PING 뒤 응답을 기다리는 시간 |
보드 설정 IOSignalConfig (ESP32·ESP8266)
#include <IOSignalConfig.h>를 쓰면 Wi-Fi, 서버, 장치 키, 스케치 설정을 USB로 연결한 브라우저에서 넣고 보드가 저장합니다. 저장된 값이 스케치 값보다 우선합니다. 자세한 사용법은 보드 설정에 있습니다.
| 메서드 | 설명 |
|---|---|
begin(Serial, name, ssid, pass) | 설정 기능을 시작합니다. ssid·pass가 자리 표시 값("WIFI_SSID")이 아니면 스케치 값을 씁니다. |
setServer(host, port) / setKey("id.key") | 스케치의 기본 서버와 장치 키 |
host(), port(), key() | 쓸 서버와 키(저장된 값 > 스케치 값). key()가 있으면 io.auth(config.key())로 로그인합니다. |
loop() | 브라우저 요청 처리와 Wi-Fi 재연결. loop()에서 계속 호출합니다. |
connected() | Wi-Fi가 연결되어 있는지. true일 때 io.loop()를 부릅니다. |
printServer() | 쓸 서버를 시리얼에 출력합니다. |