Five-minute quickstart
Requirements: Node.js 22.16.0 or later, npm, and three terminals.
Success: the receiver prints hello#message and Hello, IOSignal!.
To find the right order for your goal, choose a path.
1. Prepare a project
mkdir iosignal-hello
cd iosignal-hello
npm init -y
npm install iosignal
The .mjs extension enables ES modules without changing package.json.
2. Start the server
Save as server.mjs:
import { Server } from 'iosignal';
const server = new Server({ port: 7777 });
server.on('ready', () => console.log('Server ready: ws://localhost:7777'));
In terminal 1, run node server.mjs and leave it running.
3. Start the receiver
Save as receiver.mjs:
import { IO } from 'iosignal';
const io = new IO('ws://localhost:7777');
io.listen('hello#message', (tag, message) => {
console.log(tag, message);
});
io.on('ready', () => console.log('Receiver ready:', io.cid));
io.on('error', console.error);
In terminal 2, run node receiver.mjs and wait for Receiver ready. listen() registers the handler and schedules the subscription when the connection becomes ready.
4. Send a message
Save as sender.mjs:
import { IO } from 'iosignal';
const io = new IO('ws://localhost:7777');
io.on('ready', () => {
io.signal('hello#message', 'Hello, IOSignal!');
console.log('Message sent');
});
io.on('error', console.error);
In terminal 3, run node sender.mjs. The receiver should print hello#message Hello, IOSignal!. Here hello is the channel and message is the topic. Stop each process with Ctrl+C.
Try it with the CLI, no code
You can check the same flow without code using iosignal-cli. Stop the Node.js server above, then use three terminals.
npm install -g iosignal-cli
io-server -l 7777
Leave terminal 1 running. In terminals 2 and 3, connect a client and wait for ready and a CID.
io-client -c ws://localhost:7777
Send to a channel: enter listen demo in client 2 and signal demo hello in client 3. The receiver prints < -message: demo hello.
Send directly to a CID: enter id in the receiver to find its CID, then enter signal actualCID@ hello in the sender, including a leading ? for an anonymous CID. Direct messages need no listen.
Exit a client with exit, quit, or Ctrl+C. CLI arguments are split on whitespace; shell quoting and JSON are not parsed. See CLI client and CLI server options for all commands. For Arduino, add -L 8888 to the server and use matching TCP settings on the board.
Next steps
- Tags and delivery patterns: channels, direct messages, and CID publishing.
- Client API: methods, events, and limits.
- Troubleshooting: diagnose setup, connection, and delivery failures.