From 3e7177dcc822eca4365f5e4ed1f88265adb72e1b Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Sun, 24 Jul 2016 04:10:13 +0100 Subject: [PATCH] Add sensniff example README --- examples/sensniff/README.md | 83 +++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 examples/sensniff/README.md diff --git a/examples/sensniff/README.md b/examples/sensniff/README.md new file mode 100644 index 000000000..140db4bc9 --- /dev/null +++ b/examples/sensniff/README.md @@ -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() + #define sensniff_io_flush() + #define sensniff_io_set_input() + +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! +