Rpc
From NESTFE Wiki
Contents |
Overview
Rpc is a tool that allows the user to declare a function or interface with @rpc and then can use the functions from a pc-side tool. The difference between RPC and AM is that the data is typed. This tool is meant to be used with the Rpc module in the python development environment Development Environment Demo, which has a full typing system. It is not intended for mote-mote communication, which should just use AM.
Rpc can use various underlying transport mechanisms. By default, it communicates over drip and drain. A complete sample application can be found in contrib/hood/apps/TestRpc. The Hood libraries can be found in tos/lib/Rpc. Some documentation of the API is below.
API
Similar to Registry and Hood, Rpc allows one to declare a function or interface rpc-able with a simple declaration as follows:
provides interface Attribute<uint16_t> as Light @rpc();
or
provides function result_t myFunc(uint8_t param) @rpc();
Once a funtion is tagged @rpc, it should show up in the pc-side tool. Once an interface is tagged @rpc, all functions in that interface should show up in the pc-side tool.
If you are having a problem with RPC, you can use the add the following flag to your makefile:
#PFLAGS += -DRPC_LEDS
It indicates that a green light should toggle whenever an rpc command is received and a red led toggles whenever a response is sent. A yellow led toggles whenever an error in rpc is detected.
Commands, Events and Pointers
All rpc-able commands and events must be "provided" by the module that tags them @rpc.
If an interface is tagged @rpc, it's commands will be made rpc-able if it is "provided" and it's events will be made rpc-able if it is "used". If a "provided" interface has any events, the RpcM module will handle these events. This may change the "default" behavior of those events, which may be undesireable, and a compile time warning is thrown. The same applies to "used" interfaces that have commands.
rpc-commands cannot have void* parameters or return values, which are inherently untyped. They can, however, have typed pointers as parameters or return values. In such a case, it is assumed that the pointer is being used as a pass-by-reference, the the receiver of the data will copy the buffer, and that the true data buffer is still owned by the origini of the buffer (ie., no buffer swapping with the pointers!) The use of pointers in rpc commands is not intended to be the normal mode of use, but rather a hacky way to do things otherwise not possible.
Setting Up
In order to use the API described above, the user must:
- use the new makesystem by setting the Makerules environment variable to point to the tinyos-1.x/tools/make/Makerules file
- add the following include directories to their makefile
CFLAGS += -I$(TOSDIR)/../tos/lib/Rpc
- wire the RpcC module somewhere in their application
- invoke the rpc.extra file in their make process by either declaring "rpc" on the command line when making the application as follows
make telosb rpc
or adding registry to the GOALS variable in their makefile
GOALS+=rpc
and finally, include Rpc.h in any file which tags functions with @rpc()
includes Rpc;
For problems, the Pytos Installation Instructions setup instructions may contain more details.
Implementation
The nesc tools simple create a module called RpcM that receive the rpc command message, unpack the parameters, call the function, pack the return value, and send the return message. This file is automatically generated using the /contrib/hood/scripts/generateRpc.pl script, along with the RpcC.nc file, both of which are stored in the build/platform/ directory. The same script generates the rpcSchema.xml file, which is used by the pc-side tools.
Transport Mechanisms
By default, Rpc uses Drip to send messages and Drain to receive. These defaults can be overriden by defining the following c preprocessor symbols: RPC_NO_DRIP and RPC_NO_DRAIN.
If RPC_NO_DRAIN is set, Rpc will not receive any messages via Drain. If RPC_NO_DRIP is sent, Rpc will not send any messages via Drip. In either case, Rpc can still receive messages from the GenericComm stack. Note that without Drip and Drain, Rpc messages will not be propagated throughout a multi-hop network. Disabling Drip and Drain may still be useful when working with a single node connected to a PC, or with node(s) within direct reach of a TOSBase.
To get a better idea of what is going on, take a look at the automatically generated RpcC.nc and RpcM.nc files in build/<platform>/.
