Interfacing Using RPC

There are many occasions when its useful to be able to talk to your mbed from a computer. This could be to control actuators using the mbeds outputs, gather data using the mbeds sensors or create remote applications over a network. Creating an interface between mbed and a computer can be difficult because it requires you to specify a communication format and then to write code on both the mbed and the computer you are interfacing with.

The mbed is capable of receiving and interpreting RPC commands and this can be used to greatly simplify creating an interface. The RPC commands are in a predefined format and can be sent over any transport mechanism that can send a stream of text. They allow you to directly interact with objects on mbed.

This page shows the code that needs to be running on mbed for RPC to work, we've also created libraries for several popular languages which allow you to use RPC over several transport mechanisms without having to have to do any work to set up the transport mechanism or formatting of your messages. Libraries have been developed for: MATLAB, LabVIEW, Python, Java and .NET.

Information

RPC Commands are in the format: "/<Object name>/<Method name> <Arguments separated by spaces>

If you send just "/" mbed will return a list of objects that can be used

If you send "/<object name>/" then mbed will return the methods which can be used on this object.

This is an example of the RPC command required to create an LED object and turn it on:

/DigitalOut/new LED1 myled
/myled/write 1

You can also interact with objects that are created in code on the mbed you just refer to them by their name.

Troubleshooting!

If you want to interact with an object then make sure you define it on mbed with a name: DigitalOut myled(LED1, "myled")

On mbed you need to pass these commands into the rpc function:

char buf[256], outbuf[256];
strcpy(buf, "/DigitalOut/new LED1 myled");
rpc(buf, outbuf); 

You can use any communication method to receive the string and pass it into RPC function

RPC Over Serial

To carry out RPC over serial you need to receive the commands from the serial port and then pass them into the RPC function. Finally you return the result. This can be done using a program like this:

Import program

00001 #include "mbed.h"
00002 #include "mbed_rpc.h"
00003 
00004 /**
00005  *  This example program has been updated to use the RPC implementation in the new mbed libraries.
00006  *  This example demonstrates using RPC over serial
00007  */
00008 
00009 //Use the RPC enabled wrapped class  - see RpcClasses.h for more info
00010 RpcDigitalOut myled(LED4,"myled");
00011 
00012 Serial pc(USBTX, USBRX);
00013 int main() {
00014     //The mbed RPC classes are now wrapped to create an RPC enabled version - see RpcClasses.h so don't add to base class
00015     
00016     // receive commands, and send back the responses
00017     char buf[256], outbuf[256];
00018     while(1) {
00019         pc.gets(buf, 256);
00020         //Call the static call method on the RPC class
00021         RPC::call(buf, outbuf); 
00022         pc.printf("%s\n", outbuf);
00023     }
00024 }

Or here is a bin file which you can download straight on to your mbed: rpc_serial_lpc1768.bin Note that its not a case of either having rpc or your own code. You can do both at the same time you just need to make sure you receive the serial commands when they are sent.

Once you have this running on mbed you can control mbed from a terminal by just typing commands in the format above (make sure you have your terminal set to transmit CR+LF).

RPC Over HTTP

The HTTP Server has an rpc handler, so by using the HTTP server example program below and download it on to your mbed you will be able to use RPC over HTTP. The rpc commands are sent by adding them to the URL of the mbed in a browser.

Information

RPC Commands over HTTP are in the format: http://<url of mbed>/rpc/<Object name>/<Method name> <Arguments separated by spaces>

The mbed will pass the URL it is assigned over the USB serial. You will need to wait to see what IP address is assigned to your mbed to properly connect with it in the client. You can view the address by starting the program and viewing print information in a serial terminal set to 9600 baud. The terminal will also allow you to view the information being recieved/sent over HTTP.

The important line of code for RPC is to add the RPC handler.

 svr.addHandler<HTTPRpcRequestHandler>("/rpc");

It is also important to add the RPC classes you are using. For instance, the following line of code is important if you intend to use RPC on a DigitalOut object.

RPC::add_rpc_class<RpcDigitalOut>();

Import programRPC_HTTP

RPC over HTTP example.

Adding RPC to your own code

Nearly all projects involve using more than just the mbed's Digital and Analog I/O and so the RPC interface above can rapidly become insufficient and you're back to creating your own communication protocol and programming the low level communication on both the mbed and in your software application. The RPC Interface Library provides a mechanism which can help over come these problems by allowing you to call custom functions over RPC and read and write to variables on mbed using RPC. The cook book page for the RPC Interface Library gives detailed information on how to use this library within your own code.

Software Libraries

You now have a program running on mbed which handles the RPC commands. To make a complete application your software needs to set up the transport mechanism on its end and format the commands into strings. To make this easier we've created libraries that not only give you simple access to the RPC from several programming languages but also include classes for much of the mbed API. The software libraries also include classes for the RPC Interface Library to help extend RPC into your own code.

They all use a consistent interface which is a close as possible to the interface for programming on mbed. They've been designed so that is easy to switch between transport mechanisms and so that an application can control multiple mbeds.