Fork me on GitHub

RPC - Remote Procedure Calls

MG-RPC frame format

Request frame format

{
  "method": "Math.Add",     // Required. Function name to invoke.
  "args": {                 // Optional. Call arguments
    "a": 1,
    "b": 2
  },
  "src": "joe/32efc823aa",  // Optional. Used with MQTT: response will be sent
                            // to that value followed by "/rpc", so in this
                            // case it'll be "joe/32efc823aa/rpc".
  "tag": "hey!",            // Optional. Any arbitrary string. Will be repeated in the response
  "id": 1772                // Optional. Numeric frame ID.
}

Successful response frame format

{
  "result": { ... },        // Required. Call result
  "tag": "hey!"             // Optional. Present if request contained "tag"
}

Failure response frame format

{
  "error": {
    "code": 123,
    "message": "oops"
  }
}

If the error key is present in the response, it's a failure. Failed response may also contain a result, in order to pass more specific information about the failure.

C API Reference mgos_rpc.h

#include "mgos_rpc.h"


bool mgos_rpc_common_init(void);

struct mg_rpc *mgos_rpc_get_global(void);

struct mg_rpc_cfg *mgos_rpc_cfg_from_sys(const struct sys_config *scfg);

void mgos_rpc_channel_ws_out_cfg_from_sys(
    const struct sys_config *scfg, struct mg_rpc_channel_ws_out_cfg *chcfg);

typedef void (*mgos_rpc_eh_t)(struct mg_rpc_request_info *ri, const char *args,
                              const char *src, void *user_data);

FFI-able signature of the function that receives RPC request

typedef void (*mgos_rpc_result_cb_t)(const char *result, int error_code,
                                     const char *error_msg, void *cb_arg);

FFI-able signature of the function that receives response to a request.

void mgos_rpc_add_handler(const char *method, mgos_rpc_eh_t cb, void *cb_arg);

FFI-able function to add an RPC handler

bool mgos_rpc_send_response(struct mg_rpc_request_info *ri,
                            const char *response_json);

FFI-able function to send response from an RPC handler

bool mgos_rpc_call(const char *dst, const char *method, const char *args_json,
                   mgos_rpc_result_cb_t cb, void *cb_arg);

FFI-able function to perform an RPC call

JAVASCRIPT API Reference api_rpc.js

load("api_rpc.js");


RPC.addHandler(name, handler)

Add RPC handler. name is a string like 'MyMethod', handler is a callback function which takes args arguments object.

Return value: none.

Example:

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

The installed handler is available over Serial, Restful, MQTT, Websocket, for example over Websocket:

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

Or, over familiar RESTful call:

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

RPC.call(dst, method, args, callback)

Call remote or local RPC service. Return value: true in case of success, false otherwise.

If dst is empty, connected server is implied. method is a string like "MyMethod", callback is a callback function which takes the following arguments: res (results object), err_code (0 means success, or error code otherwise), err_msg (error messasge for non-0 error code), userdata. Example:

```javascript RPC.call(RPC.LOCAL, 'Config.Save', {reboot: true}, function (resp, ud) { print('Response:', JSON.stringify(resp)); }, null);