RadioScope: Software Design

Software Design

The meat of the RadioScope project is in the software. The firmware which runs on the 6811 is a fully functional implementation of the StarMode Radio Internet Protocol (STRIP), as well as partial implementations of the Internet Protocol (IP) and the User Datagram Protocol (UDP). Full implementations of these protocols would be quite taxing for the 6811 (and, incidentally, a pain in the butt to write). The RadioScope firmware implements enough of these protocols to successfully, reliably, and robustly fulfill its functional goals--namely, to receive commands from other Internet hosts and reply with the sample data requested.

Program Flowchart

The various routines in the firmware code translate packet buffers between different protocol formats, interpret packet headers in each format, read commands from received packets, and write data samples into outgoing packets. If at any time in this basically linear process there is an error or some sort of unexpected result, the packets which are being worked on are discarded and the process starts over. Some errors which may be expected to crop up are:

bit/byte errors on the serial port or within a STRIP packet
non-STRIP data received from the radio (perhaps an error message)
IP packets which are not in UDP format
UDP packets which are not identified as RadioScope format
RadioScope request packets which have bad sampling parameters

There is no error notification sent to the client; in many error cases, the client is unknown anyway. Thus, if the client does not receive a response with the data it asked for in a "reasonable" amount of time, it should retransmit its request.

             +-----------+
             |   init    |
             +-----------+
                   |
                   V
       +-----------------------------------+
       | wait for a STRIP packet to arrive |
       | and read it into RBUF buffer      | <--------------\
       +-----------------------------------+                |
                   |                                        |
                   V                                        |
       +-----------------------------------+      if error  |
       | unstuff STRIP packet from RBUF    | ---------------+
       | into UDP/IP packet in IPBUF       |                | 
       +-----------------------------------+                |
                   |                                        |
                   V                                        |
       +-----------------------------------+      if error  |
       | check fields in IP and UDP hdrs   | ---------------+
       | within IPBUF; rearrange fields    |                | 
       | so response is routed to client   |                | 
       +-----------------------------------+                |
                   |                                        |
                   V                                        |
       +-----------------------------------+      if error  |
       | read sampling parameters from     | ---------------+
       | UDP packet                        |                | 
       +-----------------------------------+                |
                   |                                        |
                   V                                        |
       +-----------------------------------+      if error  |
       | grab samples and store 'em        | ---------------+
       | directly in the UDP packet        |                | 
       +-----------------------------------+                |
                   |                                        |
                   V                                        |
       +-----------------------------------+      if error  |
       | stuff modified UDP/IP packet in   | ---------------+
       | IPBUF into STRIP packet in RBUF   |                | 
       +-----------------------------------+                |
                   |                                        |
                   V                                        |
       +-----------------------------------+                |
       | send STRIP pkt in RBUF to radio   | ---------------+
       +-----------------------------------+

Communication Protocols

The commands and data which are passed between the RadioScope and its client (the program running on another device which is asking for samples from the RadioScope) are actually quite simple. The commands are just a few bytes which specify the RadioScope sampling parameters and such. The sample data is just filled in following these control bytes, and the big chunk of bytes is returned to the client with the new data filled in.

Communicating across the Internet, though, requires this chunk of bytes to be packaged in such a way that all the routing devices which the packet goes through know how to send it towards its destination, and since I wanted the RadioScope to be reasonably robust, it must also be able to distinguish proper sampling commands from other (spurious) Internet traffic which might find its way to the RadioScope.

The layers of packaging are as follows:

   +--------------------------------------------------------------------+
   |                     STRIP packet                                   |
   +--------------------------------------------------------------------+
        |                                                               |
        V                                                               V
        +-----------+------------+--------------------------------------+
        | IP header | UDP header |       RadioScope commands/data       |
        +-----------+------------+--------------------------------------+

StarMode Radio Internet Protocol (STRIP)

STRIP was developed by Stanford University Ph.D. candidate Stuart Cheshire. The STRIP packet consists of the link-layer address of the Ricochet radio the RadioScope is communicating with (the "peer"), a few bytes of protocol identification ("SIP0"), and then an IP packet (described below), encoded with a byte-stuffing protocol of Stuart's design. This byte-stuffing protocol allows in-band signalling (character #13) to be used to signal the end of the packet, while allowing any string of characters to be transmitted in the IP packet and keeping the size of the transmitted STRIP packet within the constraints of Ricochet's StarMode packets (the maximum transmission length is 1183 bytes).

By using the STRIP packet format to encapsulate the IP packet which contains the RadioScope commands and data, the RadioScope is able to communicate with any host on the Internet through gunpowder.stanford.edu, a host which routes packets between Stanford's Internet connection and the Ricochet radio network using STRIP.

Internet Protocol (IP)

The IP packet which the RadioScope sends and receives consists of an IP header and then the UDP packet (described below). The IP header contains 12 fields, six of which are used by the RadioScope.

version--must be IPv4
fragment flag--the packet must not be fragmented
protocol--the contents of the IP packet must use the UDP protocol
source and destination IP addresses--these are swapped so that the sample data is sent back to the client which asked for it
header length--tells the code where to find the UDP packet

As is alluded to above, the RadioScope does not really know its own IP address; it just figures that the router (gunpowder) will be smart enough to only route packets to the RadioScope that have the RadioScope's IP address as their destination. Then it just swaps the source and destination addresses. Another neat trick which is used in the RadioScope program is that the IP header checksum field (computed only over the header itself) is not dependent on the order of fields within the header; thus, even though the source and destination addresses are reversed, the old checksum can be reused on the reply packet, saving the RadioScope the trouble of computing a new one.

User Datagram Protocol (UDP)

The UDP packet which the RadioScope sends and receives consists of a UDP header and then the RadioScope commands and data (described below). The UDP header contains four fields, three of which are used by the RadioScope.

source and destination port number--the RadioScope does know that RadioScope request packets should be sent to UDP port $2020, and will throw out any packets which are not sent to this port number (thus eliminating most spurious Internet traffic from affecting RadioScope operation); for packets which pass this test, the source and destination port numbers will be swapped so that data is returned to the proper client
checksum--the RadioScope sets this field to 0 so that it is ignored by other Internet hosts; thus, the RadioScope escapes the need to calculate a checksum

RadioScope commands/data

field length (bytes) legal values description

version 1 0 allows for future protocol revisions

transaction ID 1 0~255 allows client to distinguish among request responses

channel number 1 0~3 input to sample from

sample rate 1 0~255 number of 16-us periods to skip between samples plus 1 (1 means skip 0, 2 means skip 1, 0 means skip 255)

number of samples 2 0~950 number of samples to capture

sample data up to 950 anything space to fill in with sample data (one byte per sample)

The client must send the RadioScope a packet with room for all of these fields, and it must fill in all of them (except the sample data) with the requested sampling parameters. The RadioScope will send back an identical packet, except that the sample data will be filled in. (Although I lose some efficiency by sending all the fields back in the return message, the number of bytes is pretty small, and it provides the client with information about the sampling parameters it requested in case it forgot.)

Note that even though the client does not need to fill in any values for the sample data, it must send the RadioScope a UDP packet with enough space to fill in all the requested samples without lengthening the UDP packet; that would require the RadioScope to mess with the IP header, compute a new checksum, etc.

field	length (bytes)	legal values	description
version	1	0	allows for future protocol revisions
transaction ID	1	0~255	allows client to distinguish among request responses
channel number	1	0~3	input to sample from
sample rate	1	0~255	number of 16-us periods to skip between samples plus 1 (1 means skip 0, 2 means skip 1, 0 means skip 255)
number of samples	2	0~950	number of samples to capture
sample data	up to 950	anything	space to fill in with sample data (one byte per sample)