Localino Code Documentation

Localino Code Documentation

To make any two localinos communicate there are three processes that must happen. The traffic director node must run on one computer that will serve as a base station for the other two computers that have localinos attached. On each of these computers launch localino_nodes. All nodes can be run via the roslaunch files in the launch folder.

Communication Process Described

In order to facilitate multiple localinos getting range measurements on a single frequency, all packets being transmitted contain 2 ID numbers. The 1st is the intended receiver ie localino 1 or localino 2... The 2nd is the packet sender. When the localino firmware receives a packet it first checks the intended receiver ID and ignores every packet not intended for itself. It then compares the packet sender ID with the ID of the localino it was expecting to communicate with and will ignore unwanted packets. But in order to keep the localino firmware completely identical between localinos, the ID numbers of all localinos are assigned at runtime. The order of events are as follows:

1. localino_node starts up, reads its ROBOT_NAME environment variable and makes a rosservice quest to the traffic director
2. traffic director receives that request, records the localino's name, and responds with an ID number and a timeout. This ID is passed onto the localino firmware and stored on board the chip for future use. (The timeout is used when the localino_node has requested that the localino firmware contact another localino, but no reply has been given). With every new service request the traffic director calculates the different communication combos ie locA -> locB, locB -> locA, locA -> locC ... .
3. Once the traffic director has received two localino's it publishes the localino_node's instruct topic (/ROBOT_NAME/instruct) the name, ID number of the localino to measure, and a frequency channel to measure on. The name is used when the localino_node publishes the range data to its distance topic, discussed below. (Frequency channel has not been implemented yet, since for the COHRINT labs purposes, single channel communication is fast enough)
4. Once the localino_node receives the instruction, it relays the ID of the localino to measure to the localino firmware and awaits a reply. See the section localino firmware for more info. Once the localino firmware responds with a range accurate to 2 decimal places, the localino_node takes that data and publishes to its topic /ROBOT_NAME/distances with the name of the localino it contacted (one the items given by the traffic director in its instruction msg) and the range given by the localino firmware.
5. After publishing to its distance topic, the localino informs the traffic director it successfully completed its instruction by publishing to the /meas_complete topic and passing its name. (This model would allow for multiple frequency channels just by always publishing the name of who completed the measurement. More plumbing is needed on both the traffic director and localino_node to allow this to happen).
6. Once the traffic_director is informed that the measurement is complete, it checks the next localino communication combo on its list and instructs the first localino to contact the 2nd. Its communcation combo list is regenerated every time a new localino makes a request to its add_name_traffic service as seen in step 2.

Timeout Layers

There are 3 layers of timeouts in this model. Once the traffic director sends an instruction to a localino it starts a timeout. If triggered it will increment communication to the next pair of localinos. This is to prevent blocking on bad networking connection. The 2nd layer happens when the localino_node instructs the localino firmware to contact another localino. This is to prevent the localino_node hanging up if the localino firmware has a fault. The 3rd layer of timeout occurs when the localino firmware instructs the localino driver module to contact another localino. This timeout will cancel the current operation, inform localino_node and wait for a future localino ID to contact. These 3 layers provide a robust atmosphere at runtime and quicken the zeroing in of causes for experiment failures.

Localino Firmware

The firmware is organized into 2 modes: Tag and Anchor. A tag starts communication by initially sending out a signal to the anchor. The Anchor first listens for a tag's signal and responds accordingly. Both modes are inside the file arduino/localino/localino.ino. All localino's are by default in anchor mode. Once they recieve an instruction over serial from the localino_node to measure another localino, they switch to tag mode and contact the other localino.

Special Launching Notes

You can run a localino_node on the same computer as the traffic director if desired. In the rare case that one would want to run more than one localino on the same computer, go to src/localino_node.py and uncomment/comment the lines as instructed in the file.