2 releases
0.2.2 | Mar 7, 2021 |
---|---|
0.2.0 | Oct 27, 2020 |
#4 in #socket-server
160KB
3K
SLoC
Table of Contents
ricsctl
ricsctl, or Remote Inter-Connected Streams is a server, client and library that allows the virtualisation of bus and stream connection. Typical usage include adding virtual or simulated modules to a bus such as a CAN bus, or allow easy control and monitoring of busses.
Installation
Windows
The build process on Windows I use is a bit weird, so an installer is provided in the release section. If your usage requires a custom build please open an issue.
Linux
Requirements:
- protoc
- lua 5.4
Installation:
cargo install --path .
Usage
RICS uses a server client approach in order to connect multiple processes to each other. Each client can send different types of messages to each other in a configurable routing pattern. Each client is also able to configure the server.
RICS can use two connection systems, Unix Domain Sockets and TCP Sockets. The server can be started to listen on multiple connections from the command line. The default socket are /tmp/rics.socket
on Linux, and localhost:7299
on Windows.
To configure the allowed connection points, start the server with the --tcp
or --uds
command line arguments.
Examples:
ricsctl start # Starts the server listening only on the default connection point
ricsctl --tcp 192.168.1.100:1000 start # Starts the server listening only on the tcp socket 192.168.1.100 port 1000
ricsctl --uds /tmp/path.socket start # Starts the server listening only on the unix domain docket /tmp/path.socket (must not exist)
ricsctl --tcp 192.168.1.100:1000 --tcp localhost:80000 --uds uds.socket start # Start the server listening on the three provided locations
Once the server is started, multiple packet types can be sent. The following table shows all the supported packet types. Multiple options can be used to configure the server response to different protocol types
Name | Description |
---|---|
RAW | Raw packet type, used internally |
STREAM | Part of a stream-like communication protocol |
CAN | CAN bus emulation |
DATAGRAM | Datagram based communication protocol |
SYNC | Syncing packet for timing critical protocols |
The environment variable RUST_LOG
can be used to configure the verbosity of the output. RUST_LOG=trace
will show all debug information.
Server configuration
All the following commands can use the --tcp
and --uds
options to select the server to configure.
ricsctl list
Lists the connected nodes.
ricsctl stop
Stops the connected server.
ricsctl route SOURCE -t TARGET1 TARGET2
Connect the node named SOURCE
to the targets TARGET1
, TARGET2
. Add the flag -d
to disconnect instead. All messages sent by SOURCE
will be received by TARGET1
and TARGET2
, but not the other way around.
ricsctl can broadcast true/false
Sets the CAN broadcast flag. If the CAN broadcast is set to true, all messages of type CAN will be sent to every other node.
Server usage
The command line tool also provide some common client operations.
ricsctl log
Display all received messages.
ricsctl can connect CANIFACE
Connects the server to the socketcan interface CANIFACE. (Linux only)
ricsctl can serial PORT [BAUD]
Connect to a serial to CANbus converter. I use this internally, please open a issue if you are interested in using this.
ricsctl can log
Display all received can messages.
ricsctl can send --id 12 --data '{0,1,2,3}'
Send a CAN message. The data and id parameters must be valid Lua.
ricsctl plugin --lua file.lua
ricsctl plugin --dynlib dynlib.dll/dynlib.so
Provides a easy way to run a user application on the server. The Lua and Dynlib api are described below.
Lua API
The lua file must contain the following lua functions:
function rics_start(svr, node) -- Called on server connection (node is your node number)
return true
end
function rics_update(svr) -- Called frequently
return true
end
function rics_init() -- Called as soon as the Lua engine is loaded
return true
end
function rics_can_callback(svr, id, data) -- Called when a can message is received
return true
end
TODO Dynlib API
Please open an issue if you are interested in using this.
Rust API
A rust library can be used to build user applications. The rust documentation can be built with cargo doc
.
A simple example of using the RICS library:
extern crate rics;
use rics::server;
fn main() {
server::RICSServer::with_server(server::ConnectTo::Default, move|mut svr| {
svr.connect(true); // Connect as node
let node = svr.who_am_i(); // Get node number
println!("My node name is: {}", node);
svr.send_packet(server::can_packet(12, vec![node])); // Send the node id on packet
});
}
Dependencies
~10–23MB
~325K SLoC