XbeeMav/README.md

# XbeeMav
## Description

The "xbee_ros_node" package provides many tools (ROS nodes) to configure, test and communicate Xbee devices.
Four nodes are provided in the package:
  * xbee_config
  * xbee_mav
  * test_controller
  * test_buzz

The "test_controller" and the "test_buzz" are dummy nodes. They are used only for testing purposes. The "xbee_config" node is used to configure the Xbees. The "xbee_mav" is used to communicates between Xbee devices in different modes (e.g. SOLO and SWARM).

## Prerequisites

  * Linux OS
  * ROS
  * Serial device drivers. For FTDI, the Virtual COM port (VCP) drivers are mandatory (http://www.ftdichip.com/Drivers/VCP.htm).

## Configuration of Xbee devices

To configure an Xbee device, the "xbee_config" node is required. To build the "xbee_config" node:

  1. Build the package:

        $ cd ~/catkin_ws
        $ catkin_make

To configure an Xbee device run the "xbee_config" node. By default, the VCP and the baud rate are respectively "/dev/ttyUSB0" and "9600". Before running the “config” node, please make sure:

  1. The Xbee device is plugged.
  2. The serial adapter driver is installed.
  3. You have full access to the correspondent serial port (e.g. ttyUSB0):

            $ sudo chmod 666 /dev/ttyUSB0

Now you can run the "xbee_config" node (after running roscore):

            $ cd ~/catkin_ws
            $ rosrun xbee_ros_node xbee_config /dev/ttyUSB0 9600

If this command generates an error:

  * Error: open: No such file or directory:
    1. Make sure the Xbee device is plugged.
    2. Make sure the appropriate driver is installed correctly.
    3. Make sure the path to the VCP (e.g. /dev/ttyUSB0) is correct.
    4. Install the newest Xbee firmware with “XCTU” and Write the default config.

  * Error: open: Permission denied:

  You do not have full access to the serial port. Please execute these commands:

      $ sudo chmod 666 /dev/ttyUSB0

  * Time Out: The Xbee Module is Not Responding:

  Baud rate mismatch. Please make sure the introduced baud rate (e.g. 9600) matches the baud rate used by the Xbee (by default is 9600). If the Xbee was previously configured with the “xbee_config” node the baud rate will be 230400.

The configuration will be loaded from "Resources/Xbee_Config.xml". Most of the existing values in the config file are optimized for Digi-Mesh. Some parameters are default values. However, all parameters can be edited. Please refer to **Table.1** before editing any parameter. More details can be found in “Xbee_Manual.pdf”. The commands table is in Chapter 3 (page 28).

**Table.1:** Most relevant Xbee Parameters.

| Key |	     Name     |	Chosen Parameter  |	Justification for chosen setting |
|:---:|:-------------:|:-----------------:|:---------------------------------:|
|CM   | Channel Mask  | 7FFF              | The channels should be allowed to jump on any available channel (Unless a particular channel is very bad).|
|HP	  | Preamble ID	  | 1	                |This parameter shouldn't be left as is as new not configured radios transmit through this default preamble setting and cause interference by default. Any value from 1-7 should be fine.|
|ID	  | Network ID	    | 5FFF	            | As with HP, this parameter should be changed from its default value because it is a factory setting that will introduce new not yet configured radios to the network. Any other value lower than 7FFF should be fine.|
|MT	  | Broadcast Multi-Transmits | 3	| MAC-level re-transmits. No reason for change until thoroughly tested.|
|PL	  | TX Power Level	| 4	| Should always be Highest [4] unless very high interference is noted (unlikely in our use case). Should only be decreased for range tests.|
|RR	  | Unicast Retries	| A	| MAC-level retries. No reason for change until thoroughly tested.|
| CE	| Routing/Messaging Mode |	0	|Should be standard for DigiMesh. (Needs validating)|
|BH	  | Broadcast Hops	| 0	| When set to 0, the broadcast hops will occur until NH is attained.|
| NH	| Network Hops |	7	| The maximum number of hops throughout the network. We could potentially link this parameter to the minimum necessary data bandwitdth (more hops = less bandwitdh).|
| MR	| Mesh Unicast Retries |	1	| No reason for change until thoroughly tested.|
|NN	 | Network Delay Slots |	3	| Random delay to alleviate network congestion, especially when broadcasting. Needs to be tested in a very dense mesh.|
|DH	 | Destination Addr.High	| 0	| Should be left to default value which will broadcast a message if entering AT mode (even though we will stay in API mode).|
|DL	 | Destination Addr. Low |	FFFF |	Should be left to default value which will broadcast a message if entering AT mode (even though we will stay in API mode).|
|NI	 | Node Identifier	| ‘Node 1’ |	This string could be set to a useful identifier for us. It allows up to a 20 characters long ASCII string. Its use needs to be evaluated with the team.|
|NT	 | Network Discov. Back-off|	82 |	This value represents a timeout for network discovery, the value is multiplied by 100ms. Network discovery is basically transparent to us (the user).|
|NO	 | Network Discov. Options |	0	| Bit 2 of this bitfield adds RSSI to signal, could be useful for us.|
|CI	 | Cluster ID	| 11	| Parameter to be studied. May be useful to identify swarms or camps.|
|EE	| Encryption Enable |	0	| Enabling encryption slightly impacts the performance (2% according to data from manual) and should be activated. This option almost completely disables the existing possibilities for accidental or voluntary (hacking) interference from other radios.|
|KY	| AES Encryption Key |	empty	| 128-bit AES Key. To be generated and shared across all radios.|
|BD	| Baud Rate	| 230400 |	To take advantage of the full transmission rate (theoretically 200 kbps), the serial communication baud rate should be adjusted according to the bandwidth.|
|NB	| Parity |	0 |	Default. |
|SB	| Stop Bits	| 0	| Default. |
|RO	| Packetization Timeout	| 3	|Default.|
|FT	| Flow Control Threshold	| 13F	| Since we are using the highest baud rate, we might need to increase the flow control threshold. Testing will tell us if the integrity of the data is fine.|
|AP	| API Enable |	1	| The XBee has to be set to API Mode to receive API frames. This allows recovering useful information in the headers of the frames such as source and destination address. We shouldn't ever need to escape API mode so we chose option [1]. Otherwise, the escape bytes would have to be escaped each time they occur. |
|AO	| API Options	| 0	| Will need to change to [1] (Explicit Rx Indicator) if we wand to be able to read Cluster ID. Otherwise, not very useful. |

## Test two Xbee devices

We consider the following setup (**Fig.1**). The block (Drone + Manifold) can be replaced by any Desktop/Laptop meeting the prerequisites.

**Fig.1:** Experimental Setup:  
![fig1](Resources/Fig1.png)

One of the drones will behave as a Master while the other one will act as a Slave. The Master drone will send commands to the Slave drone.
Each drone is running a dummy flight controller node "test_controller". According to the drone type Master/Slave, the "test_controller" node will respectively send or receive and display a command. The commands in the Master drone will be introduced with the keyboard. When a command is received in the Slave drone, it will be printed on the screen. The following table (**Table.2**) depicts the keys of each command:

**Table.2:** Keys and Commands.

| Keys |	Commands |
|:----:|:---------:|
| 7	| Take Off|
| 8	| Land |
| 9	| Return To Launch |
| 21	| New Waypoint |
| 22	| Start Mission |
| 23	| Start Mission |


**Fig.2:** ROS nodes running on the drone:  
![fig2](Resources/Fig2.png)

The communication between both drones is performed with Xbees. The “xbee_mav” node (**Fig.2**) will handle all communications with other ROS nodes (test_controller(Flight Controller) or test_buzz (ROS Buzz)) and the connected Xbee device. Therefore, both Xbees must be configured for Digi-Mesh with the maximum baud rate (230400).
We recognize two modes of communications:
  * SOLO mode: The "xbee_mav" will communicate only with the "test_controller" through services. By default, one of the following services will be active according to the drone type (Master/Slave):
    * “xbee_cmd”: The drone is Master (The server is implemented in the "xbee_mav" side while the client is implemented in the "test_controller" side).
    * “mav_dji_cmd”: The drone is Slave (The server is implemented in the "test_controller" side while the client is implemented in the "xbee_mav" side).
  * SWARM mode: The "xbee_mav" will communicate only with "test_buzz" through topics. (“inMavlink” and “outMavlink”).

All topics and services names of the “xbee_mav” node can be edited in the launch file "launch/xbeemav.launch". For other nodes (test_controller and test_buzz), topics and services names are hardcoded. Thus, they need to be modified in the source code.

#### SOLO mode

The "test_controller" node is needed:
  1. Uncomment the following lines in "CMakeLists.txt":
        add_executable(test_controller src/TestController.cpp)
        target_link_libraries(test_controller ${catkin_LIBRARIES})
  2. Build the package:
        $ cd ~/catkin_ws
        $ catkin_make
  3. Run the "test controller" node in Matser/Slave (after running roscore):
        $ cd ~/catkin_ws
        $ rosrun xbee_ros_node test_controller master
  4. Run the "xbee_mav" node in SOLO mode. The drone type (Master/Slave) and the communication mode (SOLO/SWARM) need to be specified for the "xbee_mav". You can change these parameters in the launch file “launch/xbeemav.launch”:
        $ cd ~/catkin_ws
        $ roslaunch xbee_ros_node xbeemav.launch
  5. Introduce some commands to the "test_controller". If the network was configured correctly, commands sent from one side should be received and displayed in the opposite side.

#### SWARM mode

The "test_buzz" node is required:
  1. Uncomment the following lines in "CMakeLists.txt":
        add_executable(test_buzz src/TestBuzz.cpp)
        target_link_libraries(test_buzz ${catkin_LIBRARIES})
  2. Build the package
        $ cd ~/catkin_ws
        $ catkin_make
  3. Run the "ros_buzz" node. This node is independent of drone type:
        $ cd ~/catkin_ws
        $ rosrun xbee_ros_node test_buzz
  4. Run the "xbee_mav" node in SWARM mode. Run one drone as Master and the other one as Slave (Modify the launch file).
        $ cd ~/catkin_ws
        $ roslaunch xbee_ros_node xbeemav.launch

Random payloads (Mavlink messages) will be created in the Master drone and transferred through the Xbees to the Slave drone for display. Payloads are arrays with random sizes of random 64 bits integers.

## Communicate drones in a Swarm

We consider the same setup in the testing phase (**Fig.1**). The "test_controller" and the "test_buzz" dummy nodes need to be replaced with real ones (“fligh_controller” and “ros_buzz”).
You can download the real nodes by clicking on the correspondent link:
  * flight_controller : (https://git.mistlab.ca/dasto/djiros_ws)  
  * ros_buzz : (https://github.com/MISTLab/ROSBuzz.git)

To run drones in SWARM mode you need to:
  1. Build the three packages.
  2. Run a launch file that will start the flight_controller, ros_buzz and xbee_mav. The "xbee_mav" should run in SWARM mode. The drone type (Master/Slave) is not needed.

## ROS services
The node xbee_mav provides a ROS service xbee_status that will return information
about the xbee module. The information returned depends on the argument passed to
the service (example: rosservice call /xbee_status "param_id: 'ARGUMENT'"). The different arguments that can be passed are described below:
* id : Returns the xbee module short identifier.
* deque_full : returns 1 if the out messages queue is full and 0 otherwise
* rssi : Returns the average Received Signal Strength Indicator (RSSI). This RSSI value could be inaccurate since the average is obtained by getting the RSSI of the last message at a fixed frequency without any information about the sender.
* trig_rssi_api_avg : Triggers a link testing procedure to obtain the RSSI with all the known nodes in the network. Returns false if there is no other node connected to the network.
* trig_rssi_api_ID (where ID should be replaced by a number): Triggers a link testing procedure to obtain the RSSI with the corresponding ID. Returns false if the node is not present on the network.
* get_rssi_api_avg : Returns the average of the average RSSI results of the link testing procedures.
* get_rssi_api_ID (where ID should be replaced by a number): Returns the average RSSI result of the link testing procedure.
* pl_raw_avg : Returns the average of the raw packet loss value among the connected nodes. Returns false if there is no other node connected to the network.
* pl_raw_ID (where ID should be replaced by a number): Returns the raw packet loss value between this node and the node ID. Returns false if the node is not present on the network.
* pl_filter_avg : same thing as pl_raw_avg but for the filtered value.
* pl_filter_ID (where ID should be replaced by a number): same thing as pl_raw_ID but for the filtered value.