Fork me on GitHub

RPC - Remote Procedure Calls

RPC means Remote Procedure Call. Mongoose OS RPC (MG-RPC) service is simply a C or JavaScript function that:

  • Has a name, for example GPIO.Toggle,
  • Takes a JSON object with function arguments,
  • Gives back a JSON object with results.

These JSON messages could be carried out by many different channels. Mongoose OS by default supports Serial (UART), HTTP/Restful, WebSocket, MQTT channels. mos tool provides an easy way to call device's RPC services over the serial connection or over the network.

That means, you can write a function call it remotely via multiple protocols. Consider an RPC service Sum that adds two numbers a and b:

RPC.addHandler('Sum', function(args) {
  return args.a + args.b;
});

Here is how you can call it:

Via serial connection, if a device is attached to a serial port:

mos --port /dev/ttyUSB0 call Sum '{"a":1, "b": 2}'
3

Via WebSocket, if a device is in the local network:

mos --port ws://192.168.0.206/rpc call Sum '{"a":1, "b": 2}'
3

Via RESTful call, if a device is in the local network:

curl -d '{"a":1, "b": 2}' 192.168.0.206/rpc/Sum
3

Via an MQTT server, talking to an device idendified by its ID esp32_6732ac:

mos --port mqtt://my.mqtt.server:1883/esp32_6732ac call Sum '{"a":1, "b": 2}'
3

To see a list of all RPC services implemented by a device, call RPC.List:

mos call RPC.List
[
  "I2C.WriteRegW",
  "I2C.WriteRegB",
  "I2C.ReadRegW",
  "I2C.ReadRegB",
  ...

Remote management

Mongoose OS has many built-in RPC services: for managing files, accessing hardware peripherals, performing over-the-air updates, etc. In fact, the majority of mos command talks to a device via an RPC call.

An ability to call RPC services via network add an incredible level of control, implementing remote management capabilities at the highest levels.

Example: scan I2C bus and return addresses of I2C peripherals from a device at IP address 192.168.1.4 using mos tool in a command line mode:

mos --port ws://192.168.1.4/rpc call I2C.Scan
[
  31
]

Example: connect to a remote device via the MQTT server and manage it using mos tool Web UI:

Programming documentation and examples

See RPC library documentation.

The following videos demonstrate how to make a device remotely controllable by adding a custom RPC service.

See Quickstart section on how to add RPC service in C/C++ or JavaScript.