Usage¶
The command line interface can be useful for method discovery and testing
purposes. It currently has two subcommands: list
, which shows a list of
available methods and call
for calling methods. For more information, use
the -h
option.
$ simple_rpc -h
Note
Please note that the initialisation procedure has a built in two second
delay which can be modified with the -w
parameter. For each invocation
of list
or call
, the device is reset and reinitialised, so using
the command line interface for time critical or high speed applications is
not advised. For these types of applications, the Library should be
used directly instead.
Connecting¶
To detect serial devices, we recommend using the arduino-cli toolkit.
$ arduino-cli board list
Port Type Board Name FQBN Core
/dev/ttyACM0 Serial Port (USB) Arduino Mega or Mega 2560 arduino:avr:mega arduino:avr
This command will not detect any devices connected via ethernet or WiFi. Use a
URL (e.g., socket://192.168.1.50:10000
) instead.
Method discovery¶
When the device is known, the list
subcommand can be used to retrieve all
available methods.
$ simple_rpc list /dev/ttyACM0
Alternatively, for ethernet and WiFi devices.
$ simple_rpc list socket://192.168.1.50:10000
If the Arduino has exposed the functions inc
and set_led
like in the
example given in the device library documentation, the list
subcommand
will show the following.
inc a
Increment a value.
int a: Value.
returns int: a + 1.
set_led brightness
Set LED brightness.
int brightness: Brightness.
Calling a method¶
Any of the methods can be called by using the call
subcommand.
$ simple_rpc call /dev/ttyACM0 inc 1
2
Alternatively, for ethernet or WiFi devices.
$ simple_rpc call socket://192.168.1.50:10000 inc 1
2
Please see the list of handlers for a full description of the supported interface types.
Complex objects¶
Complex objects are passed on the command line interface as a JSON string. Binary encoding and decoding is taken care of by the CLI. The following example makes use of the demo sketch in the device examples.
$ simple_rpc call /dev/ttyACM0 vector '[1, 2, 3, 4]'
[1.40, 2.40, 3.40, 4.40]
$ simple_rpc call /dev/ttyACM0 object '["a", [10, "b"]]'
["b", [11, "c"]]
Low throughput networks¶
When working with low throughput networks (e.g., LoRa), device initialisation can take a long time. To counteract this problem, it is possible to save the interface definition to a file, which can subsequently be used to initialise the interface without having to query the device.
An interface definition can be saved to a file using the -s
option of the
list
subcommand.
$ simple_rpc list -s interface.yml /dev/ttyACM0
A saved interface definition can be loaded to skip the initialisation procedure
by using the -l
option of the call
subcommand.
$ simple_rpc call -l interface.yml /dev/ttyACM0 inc 1
2