Add sensniff example README

This commit is contained in:
George Oikonomou 2016-07-24 04:10:13 +01:00
parent 20dc86c039
commit 3e7177dcc8

View File

@ -0,0 +1,83 @@
sensniff Contiki Project
========================
This example can be used to create an IEEE 802.15.4 wireless sniffer firmware,
meant to be used in parallel with
[sensniff](https://github.com/g-oikonomou/sensniff).
Running
=======
* Build this example and program your device
* Connect your device to a host
* Run sensniff on your host
* Fire up wireshark and enjoy.
Make sure your device's UART baud rate matches the `-b` argument passed to
sensniff. I strongly recommend using at least 460800. This comment does not
apply if your device is using native USB.
Subsequently, make absolutely certain that your device is tuned to the same RF
channel as the network you are trying to sniff. You can change sniffing channel
through sensniff's text interface.
More details in sensniff's README.
Adding support for more platforms
=================================
Firstly, this example will try to turn off frame filtering and automatic h/w
ACKs by calling `NETSTACK_RADIO.set_value(RADIO_PARAM_RX_MODE, 0)`. If your
radio does not support this, then implementing this is your first step towards
running this example on your board.
Secondly, in order to be able to switch channels and retrieve current/min/max
RF channel supported from sensniff's text interface, your device's radio driver
must also support:
NETSTACK_RADIO.get_value(RADIO_PARAM_CHANNEL, ...)
NETSTACK_RADIO.set_value(RADIO_PARAM_CHANNEL, ...)
NETSTACK_RADIO.get_value(RADIO_CONST_CHANNEL_MIN, ...)
NETSTACK_RADIO.get_value(RADIO_CONST_CHANNEL_MAX, ...)
The following radios have been tested:
* CC13xx/CC26xx in PROP and IEEE modes
* CC2538
* CC2530/CC2531
* CC1200
One you have the radio sorted out, you also need to configure character I/O.
The firmware captures wireless frames and streams them over a serial line to
the host where your device is connected. This can be achieved over UART or over
CDC-ACM. The example makes zero assumptions about your hardware's capability,
you have to configure thnigs explicitly.
* Firstly, create a directory named the same as your platform. Crate a header
file therein called `target-conf.h`. This will get included automatically.
* Then look at the header files under `pool`, perhaps your device's CPU is
already supported. If that's the case, then within your `target-conf.h` you
simply need to add a line like this:
#define SENSNIFF_IO_DRIVER_H "pool/cc2538-io.h"
choosing the header that corresponds to your device's CPU. Just look for any of
the platforms already supported to see how you can configure things in a more
fine-grained fashion (e.g. to select UART instance, switch between UART/USB
etc).
* If your CPU is not already supported, then you need to create an additional
header file. In that header file, you will need to define the following three:
#define sensniff_io_byte_out() <driver function that prints bytes>
#define sensniff_io_flush() <for buffered I/O. Can be empty>
#define sensniff_io_set_input() <driver function that sets an input callback>
Those should map to functions implemented by your device's peripheral driver,
e.g. your UART driver. `_byte_out()` and `set_input()` are required, but
`_flush()` is optional and is only really helpful in case of drivers/hardware
that support buffered I/O (as is the case for some Contiki's USB drivers). Once
you have provided those defines, then simple go back to your `target-conf.h`
and:
#define SENSNIFF_IO_DRIVER_H "header-with-my-own-defines.h"
That should be it!