본문으로 건너뛰기

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)

데이터 유형​

값이름뜻
0IOSignal::EMPTY데이터 없음
1IOSignal::TEXT문자열
2IOSignal::BINARY바이너리
3IOSignal::OBJECTJS 객체 하나(JSON)
4IOSignal::MJSON여러 인자(JSON 배열)
5IOSignal::MBA바이너리가 섞인 여러 인자

Arduino는 OBJECT·MJSON·MBA를 자동으로 풀지 않고 원시 바이트로 넘깁니다.

상수​

상수값뜻
DEFAULT_RX_BUF_SIZE80setRxBuffer()를 부르지 않았을 때의 수신 버퍼
DEFAULT_TX_BUF_SIZE50이보다 큰 송신은 메모리를 따로 잡아 보냅니다
MAX_CID_LEN12CID 최대 길이
SERVER_HELLO_TIMEOUT_MS10000서버 첫 응답을 기다리는 시간
RECONNECT_WAIT_MS3000다시 연결하기 전 기다리는 시간
PONG_TIMEOUT_MS15000PING 뒤 응답을 기다리는 시간

보드 설정 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()쓸 서버를 시리얼에 출력합니다.