iosignal-cli
v2.2.0
Published
IOSignal server and client CLI program.
Downloads
18
Maintainers
Readme
IOSignal CLI
iosignal supports real-time communication between web browsers, node.js, and arduino. It also provides secure authentication and encrypted communication. The signaling protocol is built-in, so the server can be used without programming.
iosignal-cli program that makes it simple to run a iosignal server and client. It uses the iosignal library and uses Redis for authentication database functionality.
[Kr] iosignal 은 웹브라우저, node.js , arduino 간의 실시간 통신을 지원합니다. 또한 보안 인증과 암호통신 기능도 제공됩니다. 시그널링 프로토콜이 내장되어 있어서 서버는 프로그래밍 없이 사용 가능합니다.
supports
Windows, Mac, and Linux.
install
Linux, Mac and shell
# global install.
$ npm install -g iosignal-cli
# If you encounter a permissions error, use sudo.
$ sudo npm install -g iosignal-cli
windows as admin permission
# global install.
$ npm install -g iosignal-cli
IOSignal server
- use
io-server
command. ios
is a shortened name for io-server.
% io-server -h
Usage: io-server [options] (--listen <port> )
Options:
-V, --version output the version number
-l, --listen <port> listen on port (start WebSocket Server)
-L, --listen-congport <port> listen on cong port (start CongSocket
Server)
-d, --auth-file <path> auth data file path
-e, --auth-param <id.key.level> auth data from argument:
id.key.level,id2.key2.level2
-E, --auth-env auth data from shell env BOHO_AUTH
-r, --auth-redis connect to redis. if exist use env
REDIS_HOST, REDIS_PORT or localhost:6379
-t, --timeout <milliseconds> ping period & timeout
-m, --metric <type> show metric <number> 1:traffic, 2:echo
-s, --show-message <none|message> show receive message.
-f, --file-logger write log files.
-a, --api-list [list...] one or multiple api names: -a api_1 api_2
-o, --show-options show server init options.
-h, --help display help for command
IOSignal over WebSocket
Use the -l option to specify the port number for websocket connections.
Supports web browser and node.js client access.
% io-server -l 7777
IOSignal Over CongSocket
- Use the -L option to specify the port number for CongSocket connections.
- CongSocket is IOSignal's own protocol that is lighter than WebSocket.
- It was developed specifically for low-end devices like Arduino.
- Supports Arduino and node.js client access.
% io-server -L 8888
WebSocket and CongSocket can be supported together.
- This allows the Arduino and web browser to communicate with each other.
% io-server -l 7777 -L 8888
opening WebSocket Server: 7777
opening CongSocket Server: 8888
┌───────────────────────────────────────────┐
│ │
│ Serving │
│ │
│ IOSignal Over WebSocket │
│ │
│ Web Browser & Node.js │
│ - Local: ws://localhost:7777 │
│ - Network: ws://192.168.0.72:7777 │
│ │
│ IOSignal Over CongSocket │
│ │
│ Node.js │
│ - Local: cong://localhost:8888 │
│ - Network: cong://192.168.0.72:8888 │
│ │
│ Arduino │
│ - host: 192.168.0.72 │
│ - port: 8888 │
│ │
└───────────────────────────────────────────┘
Monitor Server
Viewing incoming messages
- To view server incoming signal messages, use the -s option.
ios
is a shortened name forio-server
.
% ios -l 7777 -s message
...
#1(undefined) [ CID_REQ ] <Buffer c1>
#1(?ayTp) [ SIGNAL ] <Buffer d0 02 68 69 00>
#1(?ayTp) [ PING ] <Buffer cd>
Viewing metrics
-m 1
: channels, clients, traffic-m 2
: clients-m 3
: channels
$ ios -l 7777 -m 1
...
monitor metric type: 1
┌─────────┬───────────┬───────────┬──────────┬──────────┬──────────────┐
│ (index) │ rss │ heapTotal │ heapUsed │ external │ arrayBuffers │
├─────────┼───────────┼───────────┼──────────┼──────────┼──────────────┤
│ 0 │ 108232704 │ 57294848 │ 24523112 │ 1389925 │ 59260 │
└─────────┴───────────┴───────────┴──────────┴──────────┴──────────────┘
┌─────────┬──────────┬─────────┬──────────┬─────────┬─────────┐
│ (index) │ lastSSID │ remotes │ channels │ txBytes │ rxBytes │
├─────────┼──────────┼─────────┼──────────┼─────────┼─────────┤
│ 0 │ 2 │ 2 │ 1 │ 57 │ 18 │
└─────────┴──────────┴─────────┴──────────┴─────────┴─────────┘
$ ios -l 7777 -m 2
...
monitor metric type: 2
┌─────────┬───────────────┐
│ (index) │ Values │
├─────────┼───────────────┤
│ 0 │ '#1:?9P-i(7)' │
│ 1 │ '#2:?zNuW(7)' │
└─────────┴───────────────┘
$ ios -l 7777 -m 3
...
monitor metric type: 3
┌─────────┬───────────────────────┐
│ (index) │ Values │
├─────────┼───────────────────────┤
│ 0 │ 'PRIVATE:#homeButton' │
└─────────┴───────────────────────┘
iosignal client
- use
io-client
command. io
is a shortened name for io-client.
usage
% io -h
Usage: io [options] (--connect <url> )
Options:
-V, --version output the version number
-t, --timeout <milliseconds> ping period & timeout
-c, --connect <url> connect to a server
-i, --id <id> userId
-k, --key <key> userKey
-a, --auth-idKey <idkey> auth id.key
-j, --join-channel <channelName> join to channel
-h, --help display help for command
connection
To connect to a server, specify the server address and port number with the -c option.
The server address specifies one of the following protocols: ws, wss, or cong.
ws
://url:port (WebSocket)In the case of localhost, ws can be omitted.
wss
://url:port (WebSocket TLS)cong
://url:port ( CongSocket)
% io -c ws://localhost:7777
{ connect: 'ws://localhost:7777' }
Connecting to ws://localhost:7777
ready: cid: ?cybL
>
% io -c cong://localhost:8888
{ connect: 'cong://localhost:8888' }
Connecting to cong://localhost:8888
ready: cid: ?yVAQ
>
- On successful client connection, the
cid
is displayed with aready
indication. - The CID is a unique communication ID issued by the server.
- The CID of an unauthenticated client changes with each connection.
- Authenticated clients use a fixed, predefined CID.
- You can use CIDs for one-to-one communication or CID subscriptions.
io-client cli command list
- When connected to the server with the io-client CLI program, you can communicate, subscribe, and issue signals with the commands below.
- The CLI program can also communicate with browsers and Arduino connected to the server.
io-client cli commands:
.sig
.signal .publish .pub is the same as .sig.
.sub
.subscribe is the same as .sub.
.listen : subscirbe and print the received messages to the screen.
.unsub
.ping
.pong
.id
.iam
.open
.connect
.close
.login
.auth
.quit
.exit
tutorial
signaling
- multi-cast: publish/subscribe channel_name
- uni-cast: use cid(communication id)
- start server
$ io-server -l 7777
- start client A.
$ io -c localhost:7777
Connecting to ws://localhost:7777
ready: cid: ?c3Nr
> .subscribe channel_name
# subscribe some channel
- start client B.
$ io -c localhost:7777
Connecting to ws://localhost:7777
ready: cid: ?rr75
>
# multicast.
> .signal channel_name some_message
# unicast to A.
> .signal ?c3Nr@ direct_message
# IMPORTANT.
# unicast signal tag must include '@' charactor. tag = 'cid' + @
authentication
type1. auth data from file.
- for personal use only
- raw plain password string. (Not Hashed)
- each device have 4 values:
deviceId
,deviceKey
,deviceCId
,level
- you can find sample auth_file.mjs and auth_file.json in root folder.
$ io-server -l 7777 -d auth_file.json
or
$ io-server -l 7777 -d auth_file.mjs
auth_file.json structure
- deviceId string size limit: 8 charactors.
- No passphrase string limit. (It will be digested 32bytes with sha256.)
- CID string size limit: current 20 chars. can be changed.
- JSON file does not support comment.
[
["id","key","cid",0],
["did2","did2key","did2-cid",0],
["uno3","uno3-key","uno3-cid",1]
]
auth_file.mjs
- support comments.
// *.mjs file support comments.
export const authInfo = [
// device id, key, communication id, level:Number(0~255)
["did","passowrd","cid",0],
["device1","device1_key","device1_cid",0],
["root","root-key","root-cid",255], // default admin_root level is 255
["uno","uno-key","uno",1]
]
type2. auth data from Redis(or other DataBase)
- Recommended
- you can find source and examples here.
iosiganl
"/src/auth/"iosignal-cli
"/test_auth_redis/"
Before running the server, you need to make sure that your Redis server is up and running and that you have registered your device credentials. A simple credentials enrollment example is included in the source above.
start server with local redis-auth-system
$ io-server -l 7777 -r # redis://localhost:6379
auth client
- start auth server.
- connect and login
$ io -c localhost:7777
ready: cid: ?YXDr
> .login uno3 uno3-key
try manual login: uno3
> >> QUOTA_LEVEL : 1
current quota: {"signalSize":255,"publishCounter":10,"trafficRate":100000}
ready: cid: uno3-cid
# now device have (pre-registered) CID.
Support for both web browsers and Arduino
Specifying two types of ports
IOSignal uses websockets for web browser peer connections. If you want to use an Arduino connection, you must specify the use of the CongSocket port using the -L option.
The -l option specifies the Websocket port, and the -L option specifies the CongSocket port for the Arduino.
$ io-server -l 7777 -L 8888
# -l option for WebSocket port
# -L option for CongSocket port ( Arduino connection)
Local Network IP Address
If you need the IP address of the server to access it from your local network, you can check the local network IP address of the server.
$ ioip
192.168.0.72
IOSignal Arduino Library
Search for IOSignal
in the Arduino library manager and install it, or see the iosignal-arduino
github repository