Table of Contents

1. ricsctl
   1. Installation
      1. Windows
      2. Linux
   2. Usage

      1. Server configuration

      2. Server usage

      3. Lua API

      4. Dynlib API

      5. Rust API

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

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
    });
}