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}'

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

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

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

curl -d '{"a":1, "b": 2}'

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}'

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

mos call RPC.List

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 using mos tool in a command line mode:

mos --port ws:// call I2C.Scan

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.