Connecting SA Engine Nano

To interact with SA Engine Nano it needs to be connected to a federation through a relay with a full SA Engine instance. The instance on the relay is called SA Twin.

The overall steps to do such a connection are:

1. Ensure that SA Engine is installed on the intended relay device. The device can be for example a laptop or a Raspberry Pi. Refer to the manual of full version SA Engine for installation instructions for different platforms.

2. Physically connect the microcontroller with SA Engine Nano to the relay device using a serial cable. Use the device manager or another relevant tool to verify the COM port.

3. Set up a federation that the SA Twin can connect to. A federation is several instances of SA Engine that are connected to each other. At minimum, a federation consists of a nameserver that edges and clients can connect to. Read more below.

4. Start an instance of SA Engine on the relay device. Turn it into an SA Twin by running the microedge_relay OSQL function. This will connect the SA Engine Twin instance to the SA Engine Nano instance as well as connect it to the nameserver. Read more below.

Setting up a federation

At minimum, a federation consists of a nameserver which is an instance of SA Engine with this role. The nameserver can reside on an in-house or cloudbased server.

It is also possible to set up a local nameserver on the relay device and use for development and testing purposes. The setup then looks like this:

SA Nano connected to a local federation on a relay laptop.

To start a nameserver, open a new instance of SA Engine and run the commands:

start_nameserver();
reregister("me");

This will start a nameserver and connect the instance you are running from as a client.

A local nameserver can also be started on another computer. For details on how to select a port for communication to the nameserver, refer to Starting a nameserver in the edge connection guide for full SA Engine.

The relay connection command

The microedge_relay(Charstring edgespec, Record southbound_config) OSQL function turns an SA Engine instance into an SA Twin by connecting it to both a federation and a microcontroller.

The edgespec string specifies how the twin should connect to a federation. An edge specification has the format edge-name[@server[:port]].

If only the edge-name is provided, the edge will try to connect to a nameserver on the local machine on port 35021. If no nameserver is running, or if no nameserver is listening to the port, an error message will be displayed and the edge will try to reconnect every few seconds.

If the nameserver is running on a separate computer, the IP or hostname of the computer hosting the nameserver must be included. For example, to connect to a nameserver listening to port 443 on a remote computer with IP 10.0.0.1, the edge specification would be my-edge@10.0.0.1:443.

The record southbound_config specifies the connection to the microcontroller. The available options vary slighlty depending on the nano platform.

To create a config for Arduino, the following function can be used:

function southbound_config(Charstring t, Number connection_loss_to, Record com_options) -> Record

where

• t is the type of connection. Use "SERIAL-COM"
• connection_loss_to should normally be set to 5
• com_options is a record that should be defined on the form: {"port": 7, "baudrate": 115200, "flow_control": "DSR/DTR"} where port is the COM port number.

As an example, to connect an SA Twin as "edge1" to a local federation on the relay, and to SA Nano on a microcontroller throgh COM port 7 with baudrate 115200, the command would look like this:

microedge_relay("edge1", southbound_config("SERIAL-COM", 5, {
    "port": 7,
    "baudrate": 115200,
    "flow_control": "DSR/DTR"
  }));

Interaction

Once the SA Twin is connected, queries can be sent from the federation client to SA Engine Nano on the microcontroller. SA Twin will forward everything to SA Engine Nano.

For instructions on how to send to queries to edges, refer to Edge queries and functions in the full SA Engine manual. Queries and functions are sent to the SA Twin with the edge name used to register it in the edge specification.

Note that since SA Twin forwards everything, it is not possible to execute anything on this instance after running the microedge_relay function. Functions that should be run on the relay should be run before calling this function. Examples of such functions are debug commands and loading of system models. System models that are to be used on the microcontroller should be loaded on the Twin.

Setting up an SA Twin script in the relay

It is convenient to create a small connections script with the microedge_relay options and any commands that should be run before. If such a script is placed in a file called eg. small-connect.osql, the SA Twin can be started and connected with one command (to be run in the same folder as the script):

sa.engine -O small-connect.osql

The script could look for example like:

// Enable debug print-outs in the relay
lisp;
(trace-serial t)

:osql

// Load system models
// ...

// Edit to use the correct COM port etc
microedge_relay("edge1", southbound_config("SERIAL-COM", 5, {
    "port": 7,
    "baudrate": 115200,
    "flow_control": "DSR/DTR"
  }));