The 15dot4-radiotool project provides some generic "radio" tools. This tool has the following features:
- Send 802.15.4 Frames
- Receive 802.15.4 Frames to a log-file (but not wireshark)
- Play back received 802.15.4 frames, including a specific frame
- Connect two USB dongles over the internet
Supported Operating Systems
1. Programming HardwareSee Sam7sProgramming to program the SAM7S USB Stick. The firmware file is available from the sourceforge project if required, it should have the name 15dot4-radiotool-Y.Y-sam7s24.bin for the 2.4 GHz model. The Y.Y is the version of the firmware.
2. Computer SetupYou will need to install the following:
1) Install Python 2.6, should work with latest (2.6.5 right now) from http://www.python.org/download/releases/2.6/
2) Install pySerial http://sourceforge.net/projects/pyserial/files/
- When plugging the USB stick in, you can point Windows to the 6119.inf driver file if required, available from Sourceforge.
- Assuming you installed python correctly and file permissions are set, you should be able to run the radiotool.py by just typing at the command-line
But you may need to specifically specify the python binary location, in which case it would be something like:
- As a good first check, run radiotool.py with the serial port your USB stick came up as. Assuming we were on Windows and the device manager shows this stick as COM22, you could use:
Which should output:
INFO:root:type Ctrl-C / BREAK to quit
INFO:root:Connected to radio on port com22
Auto mode enabled
Current Radio Settings (input files may change these):
Channel : 24
PANID : 0xffff
Default short: 0x0000
Default long : 0xf8f7f6f5f4f3f2f1
Radio Mode : Auto
And all the LEDs on the USB stick should light up for 1/2 second. To exit the program hit Ctrl-C
3.1 Quick Example UsageEnter sniffer mode on channel 24, printing frames to the air:
radiotool.py com22 -D -C 24 -N
Enter sniffer mode on channel 24, recording frames to output.txt
radiotool.py com22 -C 24 -N -o output.txt
Send a frame defined in sendframe.txt:
radiotool.py com22 -i sendframe.txt
Run an example inputfile script, save incomming frames to logfile.txt, print frames to screen
radiotool.py com22 -D -i example_inputfile.txt -l logfile.txt
3.2 Playing back recorded framesFrames are recorded in the output file in this format:
#Received 802.15.4 Frame: RX PHY 0x61 0xc8 0x01 0xcd 0xab 0xff 0xff 0x55 0x44 0x33 0xfe 0xff 0x22 0x11 0x02 0x7b 0x49 0x3a 0x02 0x01 0xff 0x33 0x44 0x55 0x87 0x00 0xd2 0x05 0x00 0x00 0x00 0x00 0xfe 0x80 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x11 0x22 0xff 0xfe 0x33 0x44 0x55 0xa3 0x0b #Received 802.15.4 Frame: RX PHY 0x61 0xc8 0x01 0xcd 0xab 0xff 0xff 0x55 0x44 0x33 0xfe 0xff 0x22 0x11 0x02 0x7b 0x49 0x3a 0x02 0x01 0xff 0x33 0x44 0x55 0x87 0x00 0xd2 0x05 0x00 0x00 0x00 0x00 0xfe 0x80 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x11 0x22 0xff 0xfe 0x33 0x44 0x55 0xa3 0x0b
The last two bytes are the FCS. If you want to transmit the frame, you can just change the "RX" to a "TX" and input that file with the -i option. For example to play back exactly those two frames, you could use:
set channel 24 set mode auto #Received 802.15.4 Frame: TX PHY 0x61 0xc8 0x01 0xcd 0xab 0xff 0xff 0x55 0x44 0x33 0xfe 0xff 0x22 0x11 0x02 0x7b 0x49 0x3a 0x02 0x01 0xff 0x33 0x44 0x55 0x87 0x00 0xd2 0x05 0x00 0x00 0x00 0x00 0xfe 0x80 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x11 0x22 0xff 0xfe 0x33 0x44 0x55 0xa3 0x0b #Received 802.15.4 Frame: TX PHY 0x61 0xc8 0x01 0xcd 0xab 0xff 0xff 0x55 0x44 0x33 0xfe 0xff 0x22 0x11 0x02 0x7b 0x49 0x3a 0x02 0x01 0xff 0x33 0x44 0x55 0x87 0x00 0xd2 0x05 0x00 0x00 0x00 0x00 0xfe 0x80 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x11 0x22 0xff 0xfe 0x33 0x44 0x55 0xa3 0x0b
Then run radiotool.py:
radiotool.py COM22 -i inputfile.txt
Note in addition to changing the RX to a TX, the channel is set to the channel we are using, and AUTO mode is specified. Auto mode will wait for the ACK response before sending the next line of the file.
The FCS will always be recalculated when sending. Thus you can modify the frame if you wish (to change addresses, etc) and when sent over the air the FCS will be valid.
3.3 Input File Format/DescriptionThe following is an example of a valid input file, and includes comments to describe some of the options.
#This is a comment # So is this # So is this! # Comments can come at the end of the line too #Print confirmation of executing commands is done by default, you can switch it off with echo off #And turn it back on later with echo on # Set to channel 24 set channel 24 #End of line comment # Commands are not sensitive to capitals, the following would work # SeT CHaNNel 24 # Can set channel in hexadecimal too #set channel 0x15 # Set short address to 1234 set shortaddr 1234 # You can also use hex set shortaddr 0xABCD # NOTE: Starting with an extra '0' will infer octal representation! #set shortaddr 0012 # Set long address set longaddr 0x11223344bbccddee # Set PANID set panid 0xBAAD # Set AUTO mode. In AUTO the radio is acknowledging packets destined to it, and will # only receive packets destined to it. It will also resend transmitted frames, and # wait for ACKs. This is the mode generally required for testing, and is the # default mode set mode auto # Set MANUAL Mode. In MANUAL the radio is not acknowledging packets and will receive anything # as no automatic filtering is performed. Does not wait for an ACK on transmitted frames set mode manual # Print a message to the log-file log Anything here gets printed as a comment #But this part won't get printed to the log-file, it's a comment # Send a message, note FCS replaces last two bytes automatically, you do not # need a valid FCS here, in this example the last two bytes are 0x00 0x00, but # get replaced with the FCS. The entire TX PHY needs to be put on one line. TX PHY 0x41 0xc8 0xa8 0xcd 0xab 0xff 0xff 0x55 0x44 0x33 0xfe 0xff 0x22 0x11 0x02 0x7b 0x49 0x3a 0x00 0x00
3.3 Remote Terminal Mode
Remote terminal mode allows using the USB sticks over the internet together. Consider the following setup:
Assume you had the following configuration files matched with the above setup. Note how the "side a" sets it's USB sticks to the node which with we want to connect to on side B. This is done as when Alice's node sends to short address 0x0000, Alice's USB stick actually receives it. Thus Alice's USB stick will ACK this packet, and forward it onward to Bob. Bob's USB stick actually sends it onward to Bob's node.
set channel 13 #Set our address to same as remote addresses (Side B) set shortaddr 0x0000 set longaddr 0x0011223344556677 set panid 0xbaad set mode auto
set channel 26 #Set our address to same as remote addresses (Side A) set shortaddr 0x0001 set longaddr 0x0022334455667788 set panid 0xbaad set mode auto
Alice would set up her end as the server with:
radiotool.py com22 -s -i sidea.txt
And bob would connect once Alice's server was running with:
radiotool.py com22 -r 192.168.1.67 -i sideb.txt
Where 192.168.1.67 is Alice's IP address. You can use this to connect two different channels together even on your own local PC.
You can also use this without auto mode (-N option) if you don't want/need ACKs generated locally.
Due to the requirement to generate ACKs locally, this only works as a link between TWO nodes. You cannot link a node on one side to multiple nodes on the other side.