giomba/nes-proj
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #82 from simonduq/pr/doxygen-morework

Browse Source 
More work on Doxygen
This commit is contained in:
Simon Duquennoy 2017-10-07 08:19:16 +02:00 committed by GitHub
commit f59c488a32
25 changed files with 24 additions and 2730 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

489
arch/platform/cc2538dk/README.md
View File

@ -1,489 +0,0 @@
Getting Started with Contiki for TI CC2538DK
============================================
This guide's aim is to help you start using Contiki for TI's CC2538 Development Kit. By
CC2538DK we mean a TI CC2538 Evaluation Module (EM), either standalone and powered by USB or attached to a SmartRF06 Evaluation Board (EB) or Battery Board (BB). The general usage scenario assumes that the EM is attached to a SmartRF06EB and is powered by it.
This guide assumes that you have basic understanding of how to use the command line and perform basic admin tasks on UNIX family OSs.
Port Features
=============
The platform has the following key features:
* Deep Sleep support with RAM retention for ultra-low energy consumption.
* Native USB support (CDC-ACM). SLIP over UART for border routers is no longer a bottleneck.
* DMA transfers for increased performance (RAM to/from RF, RAM to/from USB).
In terms of hardware support, the following drivers have been implemented:
* CC2538 System-on-Chip:
* Standard Cortex M3 peripherals (NVIC, SCB, SysTick)
* Sleep Timer (underpins rtimers)
* SysTick (underpins the platform clock and Contiki's timers infrastructure)
* RF
* UART
* Watchdog (in watchdog mode)
* USB (in CDC-ACM)
* uDMA Controller (RAM to/from USB and RAM to/from RF)
* Random number generator
* Low Power Modes
* General-Purpose Timers. NB: GPT0 is in use by the platform code, the remaining GPTs are available for application development.
* ADC
* PWM
* Cryptoprocessor (AES-ECB/CBC/CTR/CBC-MAC/GCM/CCM-128/192/256, SHA-256)
* Public Key Accelerator (ECDH, ECDSA)
* Flash-based port of Coffee
* SmartRF06 EB and BB peripherals
* LEDs
* Buttons
* ADC sensors (on-chip VDD / 3 and temperature, ambient light sensor)
* UART connectivity over the XDS100v3 backchannel (EB only)
Requirements
============
To start using Contiki, you will need the following:
* A toolchain to compile Contiki for the CC2538.
* Drivers so that your OS can communicate with your hardware.
* Software to upload images to the CC2538.
Different tasks can be performed under different operating systems. The table below summarises what task can be performed on which OS:
Windows Linux OS-X
Building Contiki Y Y Y
Node Programming Y Y Y
Console output
(UART) Y Y Y
(USB CDC-ACM) Y Y Y
Border Routers
(UART) N Y Y
(USB CDC-ACM) N Y Y
Sniffer
(UART) N Y Y
(USB CDC-ACM) N Y Y
The platform has been developed and tested under Windows XP, Mac OS X 10.9.1 and Ubuntu 12.04 and 12.10. The matrix above has been populated based on information for those OSs.
Install a Toolchain
-------------------
The toolchain used to build contiki is arm-gcc, also used by other arm-based Contiki ports. If you are using Instant Contiki, you may have a version pre-installed in your system.
The platform is currently being used/tested with "GNU Tools for ARM Embedded Processors" (<https://launchpad.net/gcc-arm-embedded>). The current recommended version and the one being used by Contiki's regression tests on Travis is shown below.
$ arm-none-eabi-gcc --version
arm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 5.2.1 20151202 (release) [ARM/embedded-5-branch revision 231848]
Copyright (C) 2015 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Drivers
-------
You will need to install drivers so that your Operating System can communicate with the hardware
### For the SmartRF06 EB (UART)
The SmartRF communicates with the PC with a piece of hardware called the TI XDS100v3 Emulator (from now on simply XDS). This is a combined JTAG/UART interface and is used to program the EM, for debugging and for UART character I/O.
You will need to install XDS drivers if you want to do anything useful with the CC2538 UART.
* **For Windows**: Installing [SmartRF Studio][smart-rf-studio] will install the drivers (A beta version is needed, not the one currently distributed on the TI site). Read the [SmartRF User Guide][smart-rf-ug] for more detailed instructions. After driver installation, the XDS will appear as a COM port.
* **For Linux**: The XDS is based on an FTDI chip and new Linux kernels provide very good support for FTDI chips. If the kernel module does not kick in automatically, perform the following steps:
* Connect the SmartRF to the linux box. Find the device's VID and PID (0403:a6d1 in the output below):
$ lsusb
...
Bus 001 Device 002: ID 0403:a6d1 Future Technology Devices International, Ltd
...
* As root or with `sudo`, run the command below (if necessary, replace the `vendor` and `product` arguments with the values you got from `lsusb`):
modprobe ftdi_sio vendor=0x403 product=0xa6d1
* From Kernel 3.12 run the command below:
modprobe ftdi_sio
echo 0403 a6d1 > /sys/bus/usb-serial/drivers/ftdi_sio/new_id
* You may have have to remove package `brltty`, if it's installed.
* The board should have enumerated as `/dev/ttyUSB{0,1}`. `ttyUSB1` will be the UART backchannel.
* **For OS X**: We need to hack the kernel extension (kext) a little bit:
* First, install the FTDI VCP driver from <http://www.ftdichip.com/Drivers/VCP.htm>
* Edit `/System/Library/Extensions/FTDIUSBSerialDriver.kext/Contents/Info.plist` with a text editor.
* Add the following block somewhere under `IOKitPersonalities`.
<key>TI_XDS100v3</key>
<dict>
<key>CFBundleIdentifier</key>
<string>com.FTDI.driver.FTDIUSBSerialDriver</string>
<key>IOClass</key>
<string>FTDIUSBSerialDriver</string>
<key>IOProviderClass</key>
<string>IOUSBInterface</string>
<key>bConfigurationValue</key>
<integer>1</integer>
<key>bInterfaceNumber</key>
<integer>1</integer>
<key>idProduct</key>
<integer>42705</integer>
<key>idVendor</key>
<integer>1027</integer>
</dict>
* If the kext is loaded at the time you perform this change, you will have to either reload it or reboot the Mac. At the time of writing this guide, reloading the kext would fail with errors so rebooting appears to be the only solution.
* After you have rebooted, plug in the SmartRF, turn it on and then load the kext manually:
sudo kextload /System/Library/Extensions/FTDIUSBSerialDriver.kext
If everything worked, the XDS will have enumerated as `/dev/tty.usbserial-<serial-number>`
### For the CC2538EM (USB CDC-ACM)
The CC2538 EM's USB Vendor and Product IDs are the following:
* VID 0x0451
* PID 0x16C8
The implementation in Contiki is pure CDC-ACM: The Linux and OS X kernels know exactly what to do and drivers are not required.
On windows, you will need to provide a driver. You have two options:
* Use the signed or unsigned driver provided by TI in [CC2538 Foundation Firmware](http://www.ti.com/tool/cc2538-sw). You will find them both under the `drivers` directory.
* Download a generic Virtual Serial Port driver and modify it so it works for the CC2538.
For the latter option:
* Download this [LUFA CDC-ACM driver](https://raw.githubusercontent.com/abcminiuser/lufa/master/Demos/Device/LowLevel/VirtualSerial/LUFA%20VirtualSerial.inf).
* Adjust the VID and PID near the end with the values at the start of this section.
* Next time you get prompted for the driver, include the directory containing the .inf file in the search path and the driver will be installed.
### Improve Stability on Linux
There are some issues under recent Ubuntu versions (e.g. 12.10). The problem manifests itself as frequent connects/disconnects for the first approximately 30 seconds after the device has been connected to the host (Both UART and USB). The reason for this is that, as soon as the device is connected, the modem manager kicks in and starts probing it. To prevent this, we can tell the modem manager to leave this device alone:
* edit `/lib/udev/rules.d/77-mm-usb-device-blacklist.rules`
* Add the following line somewhere:
ATTRS{idVendor}=="0451", ATTRS{idProduct}=="16c8", ENV{ID_MM_DEVICE_IGNORE}="1"
* This line will instruct modem-manager to ignore the EM's USB port. To achieve the same for the SmartRF's XDS port, add a similar line but replace `idVendor` and `idProduct` with the XDS' VID/PID: 0403/a6d1.
* restart the modem-manager process:
sudo service modemmanager restart
This will tell modem manager to suppress probing for these VID/PID combinations. Keep in mind that the `blacklist.rules` file may get overwritten by future modem-manager updates and you may have to re-apply the fix in the future.
### Jumper Settings
Be careful with jumper settings on the CC2538 EM. The EM can be powered from the SmartRF or it can be powered from its own USB port.
* Locate the pair of adjacent jumpers on the EM.
* To power the EM from the SmartRF, place the jumper on the inner two pins (the ones closest to the SoC).
* To power the EM from its USB, place the jumper on the two pins nearest to the USB port.
The USB functionality will work on both situations, the jumper only controlls power supply.
### Device Enumerations
For the UART, serial line settings are 115200 8N1, no flow control.
Once all drivers have been installed correctly:
On windows, devices will appear as a virtual COM port (applies to both the UART/XDS as well as USB CDC-ACM).
On Linux and OS X, devices will appear under `/dev/`.
On OS X:
* XDS backchannel: `tty.usbserial-<serial number>`
* EM in CDC-ACM: `tty.usbmodemf<X><ABC>` (X a letter, ABC a number e.g. `tty.usbmodemfd121`)
On Linux:
* XDS backchannel: `ttyUSB1`
* EM in CDC-ACM: `ttyACMn` (n=0, 1, ....)
Software to Program the Nodes
-----------------------------
The CC2538 can be programmed via the jtag interface or via the serial boot loader on the chip.
* On Windows:
* Nodes can be programmed with TI's ArmProgConsole or the [SmartRF Flash Programmer 2][smart-rf-flashprog]. The README should be self-explanatory. With ArmProgConsole, upload the file with a `.bin` extension. (jtag + serial)
* Nodes can also be programmed via the serial boot loader in the cc2538. In `tools/cc2538-bsl/` you can find `cc2538-bsl.py` this is a python script that can download firmware to your node via a serial connection. If you use this option you just need to make sure you have a working version of python installed. You can read the README in the same directory for more info. (serial)
* On Linux:
* Nodes can be programmed with TI's [UniFlash] tool. With UniFlash, use the file with `.elf` extension. (jtag + serial)
* Nodes can also be programmed via the serial boot loader in the cc2538. No extra software needs to be installed. (serial)
* On OSX:
* The `cc2538-bsl.py` script in `tools/cc2538-bsl/` is the only option. No extra software needs to be installed. (serial)
The file with a `.cc2538dk` extension is a copy of the `.elf` file.
Use the Port
============
The following examples are intended to work off-the-shelf:
* Examples under `examples/cc2538dk`
* Border router: `examples/ipv6/rpl-border-router`
* Webserver: `examples/webserver-ipv6`
We can also use the CoAP example from `examples/er-rest-example/`. However, the example's `Makefile` is slightly problematic at the time of writing this guide. As a workaround, open it and delete this entire block:
ifneq ($(TARGET), minimal-net)
ifneq ($(TARGET), native)
ifneq ($(TARGET), econotag)
ifneq ($(findstring avr,$(TARGET)), avr)
PROJECT_SOURCEFILES += static-routing.c
endif
endif
endif
endif
The key is to prevent compilation of `static-routing.c`. If you're curious about more info, see the discussion here:
<http://thread.gmane.org/gmane.os.contiki.devel/16543>
and the related bug report here:
<https://github.com/contiki-os/contiki/issues/87>
Build your First Examples
-------------------------
It is recommended to start with the `cc2538-demo` and `timer-test` examples under `examples/cc2538dk/`. These are very simple examples which will help you get familiar with the hardware and the environment.
Strictly speaking, to build them you need to run `make TARGET=cc2538dk`. However, the example directories contain a `Makefile.target` which is automatically included and specifies the correct `TARGET=` argument. Thus, for examples under the `cc2538dk` directory, you can simply run `make`.
If you want to upload the compiled firmware to a node via the serial boot loader you need to manually enable the boot loader and then use `make cc2538-demo.upload`. On the SmartRF06 board you enable the boot loader by resetting the board (EM RESET button) while holding the `select` button. (The boot loader backdoor needs to be enabled on the chip for this to work, see README in the `tools/cc2538-bsl` directory for more info)
For the `cc2538-demo`, the comments at the top of `cc2538-demo.c` describe in detail what the example does.
To generate an assembly listing of the compiled firmware, run `make cc2538-demo.lst`. This may be useful for debugging or optimizing your application code. To intersperse the C source code within the assembly listing, you must instruct the compiler to include debugging information by adding `CFLAGS += -g` to the project Makefile and rebuild by running `make clean cc2538-demo.lst`.
Node IEEE/RIME/IPv6 Addresses
-----------------------------
Nodes will generally autoconfigure their IPv6 address based on their IEEE address. The IEEE address can be read directly from the CC2538 Info Page, or it can be hard-coded. Additionally, the user may specify a 2-byte value at build time, which will be used as the IEEE address' 2 LSBs.
To configure the IEEE address source location (Info Page or hard-coded), use the `IEEE_ADDR_CONF_HARDCODED` define in contiki-conf.h:
* 0: Info Page
* 1: Hard-coded
If `IEEE_ADDR_CONF_HARDCODED` is defined as 1, the IEEE address will take its value from the `IEEE_ADDR_CONF_ADDRESS` define. If `IEEE_ADDR_CONF_HARDCODED` is defined as 0, the IEEE address can come from either the primary or secondary location in the Info Page. To use the secondary address, define `IEEE_ADDR_CONF_USE_SECONDARY_LOCATION` as 1.
Additionally, you can override the IEEE's 2 LSBs, by using the `NODEID` make variable. The value of `NODEID` will become the value of the `IEEE_ADDR_NODE_ID` pre-processor define. If `NODEID` is not defined, `IEEE_ADDR_NODE_ID` will not get defined either. For example:
make NODEID=0x79ab
This will result in the 2 last bytes of the IEEE address getting set to 0x79 0xAB
Note: Some early production devices do not have am IEEE address written on the Info Page. For those devices, using value 0 above will result in a Rime address of all 0xFFs. If your device is in this category, define `IEEE_ADDR_CONF_HARDCODED` to 1 and specify `NODEID` to differentiate between devices.
### Scripted multi-image builds
You can build multiple nodes with different `NODEID`s sequentially. The only platform file relying on the value of `NODEID` (or more accurately `IEEE_ADDR_NODE_ID`) is `ieee-addr.c`, which will get recompiled at each build invocation. As a result, the build system can be scripted to build multiple firmware images, each one with a different MAC address. Bear in mind that, if you choose to do such scripting, you will need to make a copy of each firmware before invoking the next build, since each new image will overwrite the previous one. Thus, for example, you could do something like this:
for image in 1 2 3 4; do make cc2538-demo NODEID=$image && \
cp cc2538-demo.cc2538dk cc2538-demo-$image.cc2538dk; done
Which would build `cc2538-demo-1.cc2538dk`, `cc2538-demo-2.cc2538dk` etc
As discussed above, only `ieee-addr.c` will get recompiled for every build. Thus, if you start relying on the value of `IEEE_ADDR_NODE_ID` in other code modules, this trick will not work off-the-shelf. In a scenario like that, you would have to modify your script to touch those code modules between every build. For instance, if you are using an imaginary `foo.c` which needs to see changes to `NODEID`, the script above could be modified like so:
for image in 1 2 3 4; do make cc2538-demo NODEID=$image && \
cp cc2538-demo.cc2538dk cc2538-demo-$image.cc2538dk && \
touch foo.c; done
Build a 6LoWPAN Testbed
-----------------------
Once you are familiar with the basics, get a mini 6LoWPAN testbed.
Start by building a border router from `examples/ipv6/rpl-border-router`
* Turn on debugging output by changing `#define DEBUG DEBUG_NONE` to `#define DEBUG DEBUG_PRINT` in `border-router.c`.
* The border router's configuration (`project-conf.h`), sets the maximum size of the uIP buffer (`UIP_CONF_BUFFER_SIZE`). This is a bit restrictive for this platform: we can afford to allocate more memory of we want to. It's not necessary, but feel free to remove the lines below from `project-conf.h`, allowing the platform to use its own default value.
#ifndef UIP_CONF_BUFFER_SIZE
#define UIP_CONF_BUFFER_SIZE 140
#endif
* `make TARGET=cc2538dk`
* Flash your device with `border-router.cc2538dk` or `border-router.bin`.
* Connect device to Linux or OS X over its XDS port.
* `cd $(CONTIKI)/tools`
* `make tunslip6`
* `sudo $(CONTIKI)/tools/tunslip6 -s /dev/<device> fd00::1/64`
* The router will print its own IPv6 address. Use it below.
Got configuration message of type P
Setting prefix fd00::
created a new RPL dag
Server IPv6 addresses:
fd00::212:4b00:89ab:cdef
fe80::212:4b00:89ab:cdef
* `ping6 <address>`
* `curl -g "http://[<address-inside-the-brackets>]"` and the border router will serve you a web-page. Try from a browser too.
Afterwards, build RPL nodes in `examples/cc2538dk/udp-ipv6-echo-server`
* If you are not reading node MAC addresses from the Info Page, make sure you assign a new MAC address for each node by passing `NODEID=xyz` to the make command line, as discussed in an earlier section.
* `make` (or `make NODEID=xyz`). You don't need to specify `TARGET=` as this is saved in `Makefile.target`
* Flash device with `udp-echo-server.cc2538dk` or `.bin`.
* If you want to see console output, connect the device to a PC over its XDS port. You don't need to do that though, this example will work on 'headless' nodes. This may be a good chance to try out your BB, if you have one.
* Repeat for more nodes, each one with a new `NODEID` if necessary.
More things to play around with
* Feel free to throw some webservers in the mix. In `examples/webserver-ipv6`, run `make TARGET=cc2538dk NODEID=<value>`
* `ping6` and `netcat` the RPL nodes (the echo server listens on UDP 3000): `nc -6u <address> 3000`
* Retrieve a webpage from a node. Use `curl` as above, or you can `wget` or you can fire up a browser and navigate to the websever's address.
Build a Sniffer - Live Traffic Capture with Wireshark
-----------------------------------------------------
There is a sniffer example in `examples/sensniff/`
Diverging from platform defaults, this example configures the UART to use a baud rate of 460800. The reason is that sniffers operating at 115200 are liable to corrupt frames. This is almost certain to occur when sniffing a ContikiMAC-based deployment. See more details on how to configure UART baud rates in the "Advanced Topics" section.
Once you have built it and flashed your device, download and run `sensniff` on your PC (Linux or OS X). Get it from:
<https://github.com/g-oikonomou/sensniff>
Instructions on what to do with `sensniff` are in its README. Make sure to set the `-b` command line parameter correctly to match the sniffer's UART baud rate. Lastly, bear in mind that Host-to-Peripheral commands will not work with the CC2538 at this stage.
Mix & Match with CC2530s
------------------------
Every aspect of the CC2538 port is interoprable with the existing CC2530 port. Same 6LoWPAN prefix, same .15.4 channel and PAN ID etc. Thus, you can throw in CC2530s at will, for as long as you are using NullRDC. For instance, you can have a CC2531 border router with SmartRF06 + CC2538 EMs as RPL nodes. Or you can have a CC2538 border router with SmartRF05 + CC2530EM RPL nodes etc.
If you want to add CC2530s to the network, make sure you have followed the CC2530 how-to on the main contiki wiki:
<https://github.com/contiki-os/contiki/wiki/8051-Based-Platforms>
Advanced Topics
===============
The platform's functionality can be customised by tweaking the various configuration directives in `platform/cc2538dk/contiki-conf.h`. Bear in mind that defines specified in `contiki-conf.h` can be over-written by defines specified in `project-conf.h`, which is a file commonly encountered in example directories.
Thus, if you want to modify the platform's default behaviour, change values in `contiki-conf.h`. If you want to configure custom behaviour for a specific example, modify this example's `project-conf.h`.
N.B. Some defines in `contiki-conf.h` are not meant to be modified.
Switching between UART and USB (CDC-ACM)
----------------------------------------
By default, everything is configured to use the UART (stdio, border router's SLIP, sniffer's output stream). If you want to change this, these are the relevant lines in contiki-conf.h (0: UART, 1: USB):
#define SLIP_ARCH_CONF_USB 0 /** SLIP over UART by default */
#define DBG_CONF_USB 0 /** All debugging over UART by default */
You can multiplex things (for instance, SLIP as well as debugging over USB or SLIP over USB but debugging over UART and other combinations).
Selecting UART0 and/or UART1
----------------------------
By default, everything is configured to use the UART0 (stdio, border router's SLIP, sniffer's output stream). If you want to change this, these are the relevant lines in contiki-conf.h (0: UART0, 1: UART1):
#define SERIAL_LINE_CONF_UART 0
#define SLIP_ARCH_CONF_UART 0
#define DBG_CONF_UART 0
#define UART1_CONF_UART 0
A single UART is available on CC2538DK, so all the configuration values above should be the same (i.e. either all 0 or all 1), but 0 and 1 could be mixed for other CC2538-based platforms supporting 2 UARTs.
The chosen UARTs must have their ports and pins defined in board.h:
#define UART0_RX_PORT GPIO_A_NUM
#define UART0_RX_PIN 0
#define UART0_TX_PORT GPIO_A_NUM
#define UART0_TX_PIN 1
Only the UART ports and pins implemented on the board can be defined.
UART Baud Rate
--------------
By default, the CC2538 UART is configured with a baud rate of 115200. It is easy to increase this to 230400 by changing the value of `UART0_CONF_BAUD_RATE` or `UART1_CONF_BAUD_RATE` in `contiki-conf.h` or `project-conf.h`, according to the UART instance used.
#define UART0_CONF_BAUD_RATE 230400
#define UART1_CONF_BAUD_RATE 230400
RF and USB DMA
--------------
Transfers between RAM and the RF and USB will be conducted with DMA. If for whatever reason you wish to disable this, here are the relevant configuration lines.
#define USB_ARCH_CONF_DMA 1
#define CC2538_RF_CONF_TX_USE_DMA 1
#define CC2538_RF_CONF_RX_USE_DMA 1
Low-Power Modes
---------------
The CC2538 port supports power modes for low energy consumption. The SoC will enter a low power mode as part of the main loop when there are no more events to service.
LPM support can be disabled in its entirety by setting `LPM_CONF_ENABLE` to 0 in `contiki-conf.h` or `project-conf.h`.
NOTE: If you are using PG2 version of the Evaluation Module, the SoC will refuse to enter Power Modes 1+ if the debugger is connected and will always enter PM0 regardless of configuration. In order to get real low power mode functionality, make sure the debugger is disconnected. The Battery Board is ideal to test this.
The Low-Power module uses a simple heuristic to determine the best power mode, depending on anticipated Deep Sleep duration and the state of various peripherals.
In a nutshell, the algorithm first answers the following questions:
* Is the RF off?
* Are all registered peripherals permitting PM1+?
* Is the Sleep Timer scheduled to fire an interrupt?
If the answer to any of the above question is "No", the SoC will enter PM0. If the answer to all questions is "Yes", the SoC will enter one of PMs 0/1/2 depending on the expected Deep Sleep duration and subject to user configuration and application requirements.
At runtime, the application may enable/disable some Power Modes by making calls to `lpm_set_max_pm()`. For example, to avoid PM2 an application could call `lpm_set_max_pm(1)`. Subsequently, to re-enable PM2 the application would call `lpm_set_max_pm(2)`.
The LPM module can be configured with a hard maximum permitted power mode.
#define LPM_CONF_MAX_PM N
Where N corresponds to the PM number. Supported values are 0, 1, 2. PM3 is not supported. Thus, if the value of the define is 1, the SoC will only ever enter PMs 0 or 1 but never 2 and so on.
The configuration directive `LPM_CONF_MAX_PM` sets a hard upper boundary. For instance, if `LPM_CONF_MAX_PM` is defined as 1, calls to `lpm_set_max_pm()` can only enable/disable PM1. In this scenario, PM2 can not be enabled at runtime.
When setting `LPM_CONF_MAX_PM` to 0 or 1, the entire SRAM will be available. Crucially, when value 2 is used the linker will automatically stop using the SoC's SRAM non-retention area, resulting in a total available RAM of 16MB instead of 32MB.
### LPM and Duty Cycling Driver
LPM is highly related to the operations of the Radio Duty Cycling (RDC) driver of the Contiki network stack and will work correctly with ContikiMAC and NullRDC.
* With ContikiMAC, PMs 0/1/2 are supported subject to user configuration.
* When NullRDC is in use, the radio will be always on. As a result, the algorithm discussed above will always choose PM0 and will never attempt to drop to PM1/2.
Build headless nodes
--------------------
It is possible to turn off all character I/O for nodes not connected to a PC. Doing this will entirely disable the UART as well as the USB controller, preserving energy in the long term. The define used to achieve this is (1: Quiet, 0: Normal output):
#define CC2538_CONF_QUIET 0
Setting this define to 1 will automatically set the following to 0:
* `USB_SERIAL_CONF_ENABLE`
* `UART_CONF_ENABLE`
* `STARTUP_CONF_VERBOSE`
Code Size Optimisations
-----------------------
The build system currently uses optimization level `-Os`, which is controlled indirectly through the value of the `SMALL` make variable. This value can be overridden by example makefiles, or it can be changed directly in `platform/cc2538dk/Makefile.cc2538dk`.
Historically, the `-Os` flag has caused problems with some toolchains. If you are using one of the toolchains documented in this README, you should be able to use it without issues. If for whatever reason you do come across problems, try setting `SMALL=0` or replacing `-Os` with `-O2` in `cpu/cc2538/Makefile.cc2538`.
Doxygen Documentation
=====================
This port's code has been documented with doxygen. To build the documentation, navigate to `$(CONTIKI)/doc` and run `make`. This will build the entire contiki documentation and may take a while.
If you want to build this platform's documentation only and skip the remaining platforms, run this:
make basedirs="platform/cc2538dk core cpu/cc2538 examples/cc2538dk"
Once you've built the docs, open `$(CONTIKI)/doc/html/index.html` and enjoy.
Other Versions of this Guide
============================
If you prefer this guide in other formats, use the excellent [pandoc] to convert it.
* **pdf**: `pandoc -s --toc README.md -o README.pdf`
* **html**: `pandoc -s --toc README.md -o README.html`
More Reading
============
1. [SmartRF06 Evaluation Board User's Guide, (SWRU321)][smart-rf-ug]
2. [CC2538 System-on-Chip Solution for 2.4-GHz IEEE 802.15.4 and ZigBee&reg;/ZigBee IP&reg; Applications, (SWRU319B)][cc2538]
[smart-rf-studio]: http://www.ti.com/tool/smartrftm-studio "SmartRF Studio"
[smart-rf-flashprog]: http://www.ti.com/tool/flash-programmer "SmartRF Flash Programmer"
[smart-rf-ug]: http://www.ti.com/litv/pdf/swru321a "SmartRF06 Evaluation Board User's Guide"
[cc2538]: http://www.ti.com/product/cc2538 "CC2538"
[uniflash]: http://processors.wiki.ti.com/index.php/Category:CCS_UniFlash "UniFlash"
[pandoc]: http://johnmacfarlane.net/pandoc/ "Pandoc - a universal document converter"

202
arch/platform/jn516x/README.md
View File

@ -1,202 +0,0 @@
# NXP JN516x platform
## Overview
The JN516x series is a range of ultra low power, high performance wireless microcontrollers from NXP. They feature an enhanced 32-bit RISC processor (256kB/32kB/4kB Flash/RAM/EEPROM for JN5168), and also include a 2.4GHz IEEE802.15.4-compliant transceiver.
These system on chip (SoC) devices have the following main [features][jn516x-datasheet]:
* 32-bit RISC CPU (Beyond Architecture -- BA), 1 to 32MHz clock speed
* 2.4GHz IEEE802.15.4-compliant transceiver
* 128-bit AES security processor
* MAC accelerator with packet formatting, CRCs, address check, auto-acks, timers
* Transmit power 2.5dBm
* Receiver sensitivity -95dBm
* RX current 17mA, TX 15mA
* Integrated ultra low power sleep oscillator – 0.6μA
* Deep sleep current 0.12μA (Wake-up from IO)
* Time of Flight engine for ranging
* Antenna Diversity (Auto RX)
* 2.0V to 3.6V battery operation
* Supply voltage monitor with 8 programmable thresholds
* Built-in battery and temperature sensors
* Infra-red remote control transmitter
* Peripherals: I2C, SPI, 2x UART, 4-input 10-bit ADC, comparator, 5x PWM
## Maintainers and Contact
Long-term maintainers:
* Chris Gray, NXP, christopher.gray@nxp.com, github user: [NxpChrisGray](https://github.com/NxpChrisGray)
* Simon Duquennoy, SICS, simonduq@sics.se, github user: [simonduq](https://github.com/simonduq)
Other contributors:
* Beshr Al Nahas, SICS (now Chalmers University), beshr@chalmers.se, github user: [beshrns](https://github.com/beshrns)
* Atis Elsts, SICS, atis.elsts@sics.se, github user: [atiselsts](https://github.com/atiselsts)
## License
All files are under BSD license, as described by the copyright statement in every source file.
## Port Features
The following features have been implemented:
* A radio driver with two modes (polling and interrupt based)
* CCM* driver with HW accelerated AES
* UART driver (with HW and SW flow control, 1'000'000 baudrate by default)
* Contiki tickless clock
* Contiki rtimers based on either
* the 32 kHz external oscillator
* or the internal 32 MHz oscillator (which gives a 16 MHz rtimer)
* CPU low-power mdoes
* doze mode: shallow sleep, 32 MHz oscillator (source of rtimer and radio clock) keeps running
* sleep mode: deeper sleep, 32 MHz oscillator turned off, next wakeup set on 32 kHz oscillator
* Periodic DCO recalibration
* HW random number generator used as a random seed for pseudo-random generator
* Watchdog, JN516x HW exception handlers
The following hardware platforms have been tested:
* DR1174 evaluation board (with a button sensor)
* DR1175 sensor board (with humidity/temperature and light sensors)
* DR1199 sensor board (with potentiometer and button sensors)
* USB dongle
## TODO list
The following features are planned:
* Time-accurate radio primitives ("send at", "listen until")
* External storage
## Requirements
To start using JN516x with Contiki, the following are required:
* The toolchain and Software Development Kit to compile Contiki for JN516x
* Drivers so that your OS can communicate with your hardware
* Software to upload images to the JN516x
### Install a Toolchain
The toolchain used to build Contiki for JN516x is `ba-elf-gcc`.
The compiler as well as the binary libraries required to link the executables can be downloaded from NXP. To express your interest in obtaining them, go to [NXP 802.15.4 software page][NXP-802.15.4-software], select "JN-SW-4163", and contact the NXP support through the web form. The download link is then obtained via e-mail (allow 1+ working day for a reply).
The example applications in this port have been tested with compiler version `gcc-4.7.4-ba-r36379`.
Linux and Windows instructions:
* On Linux: A compiled version for linux 64-bit is available: download [this](http://simonduq.github.io/resources/ba-elf-gcc-4.7.4-part1.tar.bz2) and [this](http://simonduq.github.io/resources/ba-elf-gcc-4.7.4-part2.tar.bz2) file, extract both in `/usr/ba-elf-gcc` such and add `/usr/ba-elf-gcc/bin` to your `$PATH` environment variable. Place the JN516x SDK under `/usr/jn516x-sdk`.
* On Windows: Run the setup program and select `C:/NXP/bstudio_nxp/` as install directory. Also make sure your PATH environment variable points to the compiler binaries (by default in `C:/NXP/bstudio_nxp/sdk/Tools/ba-elf-ba2-r36379/bin`).
### Drivers
The JN516x platforms feature FTDI serial-to-USB modules. The driver is commonly found in most OS, but if required it can be downloaded from <http://www.ftdichip.com/Drivers/VCP.htm>
### Device Enumerations
For the UART, serial line settings are 1000000 8N1, no flow control.
Once all drivers have been installed correctly:
* On Windows, devices will appear as a virtual COM port.
* On Linux and OS X, devices will appear as `/dev/tty*`.
### Software to Program the Nodes
The JN516x can be programmed via the serial boot loader on the chip.
* On Linux, nodes can be programmed via the serial boot loader using the [JennicModuleProgrammer] tool. It is pre-installed under `tools/jn516x/JennicModuleProgrammer`.
* On Windows, nodes are programmed using NXP's Flash Programmer. There are two versions of it: GUI and command line. The Contiki make system is configured to use the command line version. By default it looks for the programmer in the SDK base directory under `Tools/flashprogrammer/FlashCLI.exe`. With the default SDK installation path the file should be located under `C:/NXP/bstudio_nxp/sdk/JN-SW-4163/Tools/flashprogrammer/FlashCLI.exe`. Modify `platforms/jn516x/Makefile.common` to change this default location.
## Using the Port
The following examples are intended to work off-the-shelf:
* Platform-specific examples under `examples/jn516x`
* All platform-independent Contiki application examples
### Building an example
To build the classic "hello world" example, navigate to `examples/hello-world`. It is recommended to either set the `TARGET` environmental variable or to save the `jn516x` platform as the default make target. To do that, run:
`make TARGET=jn516x savetarget`
Then run `make hello-world` to compile the application for JN516x platform.
### Uploading an example
Run the `upload` command to program the binary image on it:
`make hello-world.upload MOTE=0`
The `MOTE` argument is used to specify to which of the ports the device is connected. For example, if there is a single mote connected to `/dev/ttyUSB3` in Linux (or, alternatively, `COM3` in Windows), the right command would be:
`make hello-world.upload MOTE=3`
Note that on Windows, the FTDI drivers are able to switch the board to programming mode before uploading the image.
On Linux, the drivers are not able to do so yet. We use a modified bootloader for JN516x, where nodes wait 5s in programming mode after a reset. You simply need to reset them before using `make upload`. The modified bootloader can be downloaded [here](http://simonduq.github.io/resources/BootLoader_JN5168.ba2.bin) and installed using a JTAG programmer, or alternatively, [this image](http://simonduq.github.io/resources/BootLoaderUpdater_JN5168.bin) can be installed as a normal application using the normal Windows tools. Once the device resets, this application will run and will then install the new boot loader. It generates some status output over UART0 at 115200 baud during this process. **Warning**: use the images above at your risk; NXP does not accept responsibility for any devices that are rendered unusable as a result of using it.
### Listening to output
Run the `login` command to start the `serialdump` application.
`make login MOTE=3`
On Linux: after the application has started, press the reset button on the node.
### Platform-specific make targets
* `<application>.flash` - flash the (pre-compiled) application to a JN516x mote (specified via the `MOTE` variable)
* `<application>.flashall` - flash the (pre-compiled) application to all all connected JN516x motes
* `<application>.upload` - compile and flash the application to a JN516x mote (specified via the `MOTE` variable)
* `<application>.uploadall` - compile and flash the application to all all connected JN516x motes
* `login`, `serialview`, `serialdump` - dump serial port output from a JN516x mote (specified via the `MOTE` variable)
* `serialdumpall` - dump serial port output from all connected JN516x motes
* `motelist` - list all connected JN516x motes.
* `motelistmac` - list MAC addresses of all connected JN516x motes (Note: not implemented on Linux!)
* `motelistinfo` - list info about all connected JN516x motes (Note: very limited functionality on Linux!)
*Troubleshooting:* you need a working Python installation for these commands to work. On Windows, make sure Python executable is in your `PATH`.
### Compiling for different MCUs and boards
The platforms can selected by using `Makefile` variables.
The following MCU models are supported:
* `JN5164` - 160kB/32kB/4kB Flash/RAM/EEPROM
* `JN5168` - 256kB/32kB/4kB Flash/RAM/EEPROM (default MCU)
* `JN5169` - 512kB/32kB/4kB Flash/RAM/EEPROM
Set `CHIP` variable to change this; for example, to select JN5164 use:
`make CHIP=JN5164`
The JN5168 has four module variants available:
* `M00` - Standard power, integrated antenna (default module)
* `M03` - Standard power, uFL connector
* `M05` - Medium power, uFL connector
* `M06` - High power, uFL connector
The `M05` and `M06` need to control the internal power amplifier. Set the `MODULE` variable to select the module, for example:
`make CHIP=JN5168 MODULE=M05`
The following platform-specific configurations are supported:
* DR1174 evaluation kit; enable this with `JN516x_WITH_DR1174 = 1` in your makefile
* DR1174 with DR1175 sensor board; enable this with `JN516x_WITH_DR1175 = 1` (will set `JN516x_WITH_DR1174` automatically)
* DR1174 with DR1199 sensor board; enable this with `JN516x_WITH_DR1199 = 1` (will set `JN516x_WITH_DR1174` automatically)
* USB dongle; enable this with `JN516x_WITH_DONGLE = 1`
### Enabling specific hardware features
The JN516X Contiki platform supports sleep mode (with RAM retention and keeping the external oscillator on). To enable sleeping, configure `JN516X_SLEEP_CONF_ENABLED=1`.
Sleeping will only happen if there at least 50 ms until the next rtimer or etimer. Also, the system will wake up ~10 ms before the next timer should fire in order to reinitialize all hardware peripherals.
The JN516X Contiki platform also supports rtimers at two different speeds: 16 MHz and 32 kHz. By default, the high-speed timer is used. The two timers have similar expected accuracy (drift ppm), but the 16 MHz one has higher precision. However, the low-speed timers are also kept running during sleeping.
To enable the low-frequency timer option, set `RTIMER_USE_32KHZ=1`. An external crystal oscillator is required to achieve reasonable accuracy in this case. This oscilator is present on most platforms, and is enabled automatically if either 32kHz timers or sleeping are enabled.
### Node IEEE/RIME/IPv6 Addresses
Nodes will autoconfigure their IPv6 address based on their 64-bit IEEE/MAC address. The 64-bit MAC address is read directly from JN516x System on Chip.
The 16-bit RIME address and the Node ID are set from the last 16-bits of the 64-bit MAC address.
## Additional documentation
1. [Data Sheet: JN516x IEEE802.15.4 Wireless Microcontroller][jn516x-datasheet]
2. [JN516x web page][jn516x-web]
3. [JN5168 web page][jn5168-web]
4. [JN516x user manuals][user-manuals]
[jn516x-datasheet]: http://www.nxp.com/documents/data_sheet/JN516X.pdf
[jn516x-web]: http://www.nxp.com/products/microcontrollers/product_series/jn516x
[jn5168-web]: http://www.nxp.com/products/microcontrollers/product_series/jn516x/JN5168.html
[user-manuals]: http://www.nxp.com/technical-support-portal/#/tid=1,sid=,bt=,tab=usermanuals,p=1,rpp=,sc=,so=,jump=
[NXP-802.15.4-software]: http://www.nxp.com/techzones/wireless-connectivity/ieee802-15-4.html
[JennicModuleProgrammer]: https://github.com/WRTIOT/JennicModuleProgrammer

254
arch/platform/nrf52dk/README.md
View File

@ -1,254 +0,0 @@
Contiki for nRF52 Development Kit
=================================
This guide's aim is to help you with using Contiki for
Nordic Semiconductor's nRF52 DK.
The port depends on Nordic Semiconductor IoT SDK for nRF52.
The IoT SDK contains source code and libraries which are
required for successfull port compilation. It also contains
SoftDevice binary driver which is required for BLE operation.
See prerequisites section for details on how to set up the SDK.
For more information about SoftDevice please refer to the SDK
docummentation [nRF52 Datasheet and SDK documentation].
This port supports DK versions PCA10040 and PCA10036.
Port Features
=============
The following features have been implemented:
* Support for IPv6 over BLE using Contiki 6LoWPAN implementation
* Contiki system clock and rtimers (using 32kHz and 1MHz timers)
* UART driver
* Watchdog driver
* Hardware RNG
* Temperature sensor driver
* DK LED driver
* DK Buttons driver
* Real Time Transfer (RTT) I/O support
Note that this port supports only IPv6 network stack.
The port is organized as follows:
* nRF52832 CPU and BLE drivers are located in `cpu/nrf52832` folder
* nRF52 Development Kit drivers are located in `platform/nrf52dk` folder
* Platform examples are located in `examples/nrf52dk` folder
Prerequisites and Setup
=======================
In order to compile for the nRF52 DK platform you'll need:
* nRF5 IOT SDK
https://developer.nordicsemi.com
Download nRF5 IOT SDK, extract it to a folder of your choice,
and point `NRF52_SDK_ROOT` environmental variable to it, e.g.,:
```
wget https://developer.nordicsemi.com/nRF5_IoT_SDK/nRF5_IoT_SDK_v0.9.x/nrf5_iot_sdk_3288530.zip
unzip nrf5_iot_sdk_3288530.zip -d /path/to/sdk
export NRF52_SDK_ROOT=/path/to/sdk
```
* An ARM compatible toolchain
The port has been tested with GNU Tools for ARM Embedded Processors
version 5.2.1.
For Ubuntu you can use package version provided by your distribution:
```
sudo apt-get install gcc-arm-none-eabi
```
Alternatively, install the toolchain from PPA to get the latest version
of the compiler: https://launchpad.net/~team-gcc-arm-embedded/+archive/ubuntu/ppa
For other systems please download and install toolchain available at
https://launchpad.net/gcc-arm-embedded
* GNU make
* Segger JLink Software for Linux
https://www.segger.com/jlink-software.html
This package contains tools necessary for programming and debugging nRF52 DK.
For Ubuntu you can download and install a .deb package. Alternatively download
tar.gz archive and extract it to a folder of your choice. In this case you
need to set `NRF52_JLINK_PATH` environmental variable to point to the
JLink tools location:
```
export NRF52_JLINK_PATH=/path/to/jlink/tools
```
To keep this variable set between sessions please add the above line to your
`rc.local` file.
In order to access the DK as a regular Linux user create a `99-jlink.rules`
file in your udev rules folder (e.g., `/etc/udev/rules.d/`) and add the
following line to it:
```
ATTRS{idProduct}=="1015", ATTRS{idVendor}=="1366", MODE="0666"
```
When installing from a deb package, the `99-jlink.rules` file is added
automatically to /etc/udev/rules.d folder. However, the syntax of the file
doesn't work on newer udev versions. To fix this problem edit this file and
replace ATTR keyword with ATTRS.
To fully use the platform a BLE enabled router device is needed. Please refer
to `Preqrequisites` section in `README-BLE-6LoWPAN.md` for details.
Getting Started
===============
Once all tools are installed it is recommended to start by compiling
and flashing `examples/hello-word` application. This allows to verify
that toolchain setup is correct.
To compile the example, go to `examples/hello-world` and execute:
make TARGET=nrf52dk
If you haven't used the device with Contiki before we advise to
erase the device and flash new SoftDevice:
make TARGET=nrf52dk erase
make TARGET=nrf52dk softdevice.flash
If the compilation is completed without errors flash the board:
make TARGET=nrf52dk hello-world.flash
The device will start BLE advertising as soon as initialized. By
default the device name is set to 'Contiki nRF52 DK'. To verify
that the device is advertising properly run:
sudo hcitool lescan
And observe if the device name appears in the output. Also, observe
if LED1 is blinking what indicates that device is waiting for a connection
from BLE master.
If device is functioning as expected you can test IPv6 connection
to the device. Please refer to `README-BLE-6LoWPAN.md` on details how to do
this.
Examples
========
Examples specific for nRF52 DK can be found in `examples/nrf52dk` folder. Please
refer to README.md in respective examples for detailed description.
The DK has also been tested with the `examples/hello-world` and `examples/webserver-ipv6`
generic examples.
Compilation Options
===================
The Contiki TARGET name for this port is `nrf52dk`, so in order to compile
an application you need to invoke GNU make as follows:
make TARGET=nrf52dk
In addition to this port supports the following variables which can be
set on the compilation command line:
* `NRF52_SDK_ROOT=<SDK PATH>`
This variable allows to specify a path to the nRF52 SDK which should
be used for the build.
* `NRF52_WITHOUT_SOFTDEVICE={0|1}`
Disables SoftDevice support if set to 1. By default, SoftDevice support
is used. Note that SoftDevice must be present (flashed) in the device
before you run an application that requires it's presence.
* `NRF52_USE_RTT={0|1}`
Enables RealTime Terminal I/O. See VCOM and RTT for details. By default,
RTT is disabled and IO is done using Virtual COM port.
* `NRF52_JLINK_SN=<serial number>`
Allows to choose a particular DK by its serial number (printed on the
label). This is useful if you have more than one DK connected to your
PC and whish to flash a particular device.
* `NRF52_DK_REVISION={pca10040|pca10036}`
Allows to specify DK revision. By default, pca10040 is used.
Compilation Targets
===================
Invoking make solely with the `TARGET` variable set will build all
applications in a given folder. A particular application can be built
by invoking make with its name as a compilation target:
make TARGET=nrf52dk hello-world
In order to flash the application binary to the device use `<application>.flash`
as make target, e.g.:
make TARGET=nrf52dk hello-world.flash
In addition, the SoftDevice binary can be flashed to the DK by invoking:
make TARGET=nrf52dk softdevice.flash
To remove all build results invoke:
make TARGET=nrf52dk clean
The device memory can be erased using:
make TARGET=nrf52dk erase
Note, that once the device is erased, the SoftDevice must be programmed again.
Virtual COM and Real Time Transfer
==================================
By default, the nRF52 DK uses a Virtual COM port to output logs. Once
the DK is plugged in a `/tty/ACM<n>` or `/ttyUSB<n>` device should appear in
your filesystem. A terminal emulator, such as picocom or minicom, can be
used to connect to the device. Default serial port speed is 38400 bps.
To connect to serial port using picocom invoke:
picocom -fh -b 38400 --imap lfcrlf /dev/ttyACM0
Note, that if you have not fixed file permissions for `/dev/ttyACM0`
according to section `Segger JLink Software for Linux` you'll need to use
root or sudo to open the port with `picocom`.
In addition to Virtual COM the port supports SEGGER's Real Time Transfer
for low overhead I/O support. This allows for outputting debugging information
at much higher rate with significantly lower overhead than regular I/O.
To compile an application with RTT rather that VCOM set `NRF52_USE_RTT` to 1 on
the compilation command line:
make TARGET=nrf52dk NRF52_USE_RTT=1 hello-world
You can then connect to the device terminal using `JLinkRTTClient`. Note that
a JLlink gdb or commander must be connected to the target for the RTT to work.
More details regarding RTT can be found at https://www.segger.com/jlink-rtt.html
Docummentation
==============
This port provides doxygen source code docummentation. To build the
docummentation please run:
sudo apt-get install doxygen
cd <CONTIKI_ROOT>\doc
make
Support
=======
This port is officially supported by Nordic Semiconductor. Please send bug
reports or/and suggestions to <wojciech.bober@nordicsemi.no>.
License
=======
All files in the port are under BSD license. nRF52 SDK and SoftDevice are
licensed on a separate terms.
Resources
=========
* nRF52 Datasheet and SDK documentation (http://infocenter.nordicsemi.com)
* nRF52 SDK Downloads (https://developer.nordicsemi.com/)
* JLink Tools (https://www.segger.com/)

191
arch/platform/openmote-cc2538/README.md
View File

@ -1,191 +0,0 @@
OpenMote-CC2538 platform
========================
The OpenMote-CC2538 is based on TI's CC2538 SoC (System on Chip), featuring an ARM Cortex-M3 running at 16/32 MHz and with 32 kbytes of RAM and 256/512 kbytes of FLASH. It has the following key features:
* Standard Cortex M3 peripherals (NVIC, SCB, SysTick)
* Sleep Timer (underpins rtimers)
* SysTick (underpins the platform clock and Contiki's timers infrastructure)
* RF (2.4 GHz)
* UART
* Watchdog (in watchdog mode)
* USB (in CDC-ACM)
* uDMA Controller (RAM to/from USB and RAM to/from RF)
* Random number generator
* Low Power Modes
* General-Purpose Timers
* ADC
* Cryptoprocessor (AES-ECB/CBC/CTR/CBC-MAC/GCM/CCM-128/192/256, SHA-256)
* Public Key Accelerator (ECDH, ECDSA)
* Flash-based port of Coffee
* PWM
* Built-in core temperature and battery sensor
Requirements
============
To start using Contiki with the OpenMote-CC2538, the following is required:
* An OpenMote-CC2538 board with a OpenUSB, OpenBase or OpenBattery carrier boards.
* A toolchain to compile Contiki for the CC2538.
* Drivers so that your OS can communicate with your hardware.
* Software to upload images to the CC2538.
Install a Toolchain
-------------------
The toolchain used to build contiki is arm-gcc, also used by other arm-based Contiki ports. If you are using Instant Contiki, you may have a version pre-installed in your system.
The platform is currently being used/tested with "GNU Tools for ARM Embedded Processors" (<https://launchpad.net/gcc-arm-embedded>). The current recommended version and the one being used by Contiki's regression tests on Travis is shown below.
$ arm-none-eabi-gcc --version
arm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 5.2.1 20151202 (release) [ARM/embedded-5-branch revision 231848]
Copyright (C) 2015 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Software to Program the Nodes
-----------------------------
The OpenMote-CC2538 can be programmed via the jtag interface or via the serial boot loader on the chip.
The OpenMote-CC2538 has a mini JTAG 10-pin male header, compatible with the `SmartRF06` development board, which can be used to flash and debug the platforms. Alternatively one could use the `JLink` programmer with a 20-to-10 pin converter like the following: <https://www.olimex.com/Products/ARM/JTAG/ARM-JTAG-20-10/>.
The serial boot loader on the chip is exposed to the user via the USB interface of both the OpenUSB and the OpenBase carrier boards. The OpenUSB carrier board is capable to automatically detect the boot loader sequence and flash the CC2538 without user intervention. The OpenBase carrier board does not have such feature, so to activate the bootloader the user needs to short the ON/SLEEP pin to GND and then press the reset button.
Instructions to flash for different OS are given below.
* On Windows:
* Nodes can be programmed with TI's ArmProgConsole or the SmartRF Flash Programmer 2. The README should be self-explanatory. With ArmProgConsole, upload the file with a `.bin` extension.
* Nodes can also be programmed via the serial boot loader in the cc2538. In `tools/cc2538-bsl/` you can find `cc2538-bsl.py` python script, which can download firmware to your node via a serial connection. If you use this option you just need to make sure you have a working version of python installed. You can read the README in the same directory for more info.
* On Linux:
* Nodes can be programmed with TI's [UniFlash] tool. With UniFlash, use the file with `.elf` extension.
* Nodes can also be programmed via the serial boot loader in the cc2538. No extra software needs to be installed.
* On OSX:
* The `cc2538-bsl.py` script in `tools/cc2538-bsl/` is the only option. No extra software needs to be installed.
Use the Port
============
The following examples are intended to work off-the-shelf:
* Examples under `examples/openmote-cc2538`
* MQTT example `examples/cc2538dk/mqtt-demo`
* Border router: `examples/ipv6/rpl-border-router`
* Webserver: `examples/webserver-ipv6`
* CoAP example: `examples/er-rest-example`
Build your First Examples
-------------------------
It is recommended to start with the `openmote-demo`, it is a simple example that demonstrates the OpenMote-CC2538 features, such as the built-in sensors, LEDs, user button and radio (using RIME broadcast).
The `Makefile.target` includes the `TARGET=` argument, predefining which is the target platform to compile for, it is automatically included at compilation.
To generate or override an existing one, you can run:
`make TARGET=openmote-cc2538 savetarget`
Then you can just run `make` to compile an application, otherwise you will need to do `make TARGET=openmote-cc2538`.
If you want to upload the compiled firmware to a node via the serial boot loader you need first to either manually enable the boot loader.
Then use `make openmote-demo.upload`.
If you are compiling for the OpenMote-CC2538 Rev.A1 board (CC2538SF53, 256 KB Flash) you have to pass `BOARD_REVISION=REV_A1` in all your `make` commands to ensure that the linking stage configures the linker script with the appropriate parameters. If you are compiling for older OpenMote-CC2538 revisions (CC2538SF53, 512 KB Flash) you can skip this parameter since the default values are already correct.
The `PORT` argument could be used to specify in which port the device is connected, in case we have multiple devices connected at the same time.
To generate an assembly listing of the compiled firmware, run `make openmote-demo.lst`. This may be useful for debugging or optimizing your application code. To intersperse the C source code within the assembly listing, you must instruct the compiler to include debugging information by adding `CFLAGS += -g` to the project Makefile and rebuild by running `make clean openmote-demo.lst`.
To enable printing debug output to your console, use the `make login` to get the information over the USB programming/debugging port, or alternatively use `make serialview` to also add a timestamp in each print.
Node IEEE/RIME/IPv6 Addresses
-----------------------------
Nodes will generally autoconfigure their IPv6 address based on their IEEE address. The IEEE address can be read directly from the CC2538 Info Page, or it can be hard-coded. Additionally, the user may specify a 2-byte value at build time, which will be used as the IEEE address' 2 LSBs.
To configure the IEEE address source location (Info Page or hard-coded), use the `IEEE_ADDR_CONF_HARDCODED` define in contiki-conf.h:
* 0: Info Page
* 1: Hard-coded
If `IEEE_ADDR_CONF_HARDCODED` is defined as 1, the IEEE address will take its value from the `IEEE_ADDR_CONF_ADDRESS` define. If `IEEE_ADDR_CONF_HARDCODED` is defined as 0, the IEEE address can come from either the primary or secondary location in the Info Page. To use the secondary address, define `IEEE_ADDR_CONF_USE_SECONDARY_LOCATION` as 1.
Additionally, you can override the IEEE's 2 LSBs, by using the `NODEID` make variable. The value of `NODEID` will become the value of the `IEEE_ADDR_NODE_ID` pre-processor define. If `NODEID` is not defined, `IEEE_ADDR_NODE_ID` will not get defined either. For example:
make NODEID=0x79ab
This will result in the 2 last bytes of the IEEE address getting set to 0x79 0xAB
Note: Some early production devices do not have am IEEE address written on the Info Page. For those devices, using value 0 above will result in a Rime address of all 0xFFs. If your device is in this category, define `IEEE_ADDR_CONF_HARDCODED` to 1 and specify `NODEID` to differentiate between devices.
Low-Power Modes
---------------
The CC2538 port supports power modes for low energy consumption. The SoC will enter a low power mode as part of the main loop when there are no more events to service.
LPM support can be disabled in its entirety by setting `LPM_CONF_ENABLE` to 0 in `contiki-conf.h` or `project-conf.h`.
The Low-Power module uses a simple heuristic to determine the best power mode, depending on anticipated Deep Sleep duration and the state of various peripherals.
In a nutshell, the algorithm first answers the following questions:
* Is the RF off?
* Are all registered peripherals permitting PM1+?
* Is the Sleep Timer scheduled to fire an interrupt?
If the answer to any of the above question is "No", the SoC will enter PM0. If the answer to all questions is "Yes", the SoC will enter one of PMs 0/1/2 depending on the expected Deep Sleep duration and subject to user configuration and application requirements.
At runtime, the application may enable/disable some Power Modes by making calls to `lpm_set_max_pm()`. For example, to avoid PM2 an application could call `lpm_set_max_pm(1)`. Subsequently, to re-enable PM2 the application would call `lpm_set_max_pm(2)`.
The LPM module can be configured with a hard maximum permitted power mode.
#define LPM_CONF_MAX_PM N
Where N corresponds to the PM number. Supported values are 0, 1, 2. PM3 is not supported. Thus, if the value of the define is 1, the SoC will only ever enter PMs 0 or 1 but never 2 and so on.
The configuration directive `LPM_CONF_MAX_PM` sets a hard upper boundary. For instance, if `LPM_CONF_MAX_PM` is defined as 1, calls to `lpm_set_max_pm()` can only enable/disable PM1. In this scenario, PM2 can not be enabled at runtime.
When setting `LPM_CONF_MAX_PM` to 0 or 1, the entire SRAM will be available. Crucially, when value 2 is used the linker will automatically stop using the SoC's SRAM non-retention area, resulting in a total available RAM of 16 kbytes instead of 32 kbytes.
### LPM and Duty Cycling Driver
LPM is highly related to the operations of the Radio Duty Cycling (RDC) driver of the Contiki network stack and will work correctly with ContikiMAC and NullRDC.
* With ContikiMAC, PMs 0/1/2 are supported subject to user configuration.
* When NullRDC is in use, the radio will be always on. As a result, the algorithm discussed above will always choose PM0 and will never attempt to drop to PM1/2.
Build headless nodes
--------------------
It is possible to turn off all character I/O for nodes not connected to a PC. Doing this will entirely disable the UART as well as the USB controller, preserving energy in the long term. The define used to achieve this is (1: Quiet, 0: Normal output):
#define CC2538_CONF_QUIET 0
Setting this define to 1 will automatically set the following to 0:
* `USB_SERIAL_CONF_ENABLE`
* `UART_CONF_ENABLE`
* `STARTUP_CONF_VERBOSE`
Code Size Optimisations
-----------------------
The build system currently uses optimization level `-Os`, which is controlled indirectly through the value of the `SMALL` make variable. This value can be overridden by example makefiles, or it can be changed directly in `platform/openmote-cc2538/Makefile.openmote-cc2538`.
Historically, the `-Os` flag has caused problems with some toolchains. If you are using one of the toolchains documented in this README, you should be able to use it without issues. If for whatever reason you do come across problems, try setting `SMALL=0` or replacing `-Os` with `-O2` in `cpu/cc2538/Makefile.cc2538`.
Doxygen Documentation
=====================
This port's code has been documented with doxygen. To build the documentation, navigate to `$(CONTIKI)/doc` and run `make`. This will build the entire contiki documentation and may take a while.
If you want to build this platform's documentation only and skip the remaining platforms, run this:
make basedirs="platform/openmote-cc2538 core cpu/cc2538 examples/openmote-cc2538 examples/openmote-cc2538"
Once you've built the docs, open `$(CONTIKI)/doc/html/index.html` and enjoy.
Other Versions of this Guide
============================
If you prefer this guide in other formats, use the excellent [pandoc] to convert it.
* **pdf**: `pandoc -s --toc README.md -o README.pdf`
* **html**: `pandoc -s --toc README.md -o README.html`
Maintainers
===========
The OpenMote-CC2538 is maintained by OpenMote Technologies.
Main contributor: Pere Tuset <peretuset@openmote.com>

260
arch/platform/srf06-cc26xx/README.md
View File

@ -1,260 +0,0 @@
Getting Started with Contiki for TI CC26xx
==========================================
This guide's aim is to help you start using Contiki for TI's CC26xx. The
platform supports multiple boards:
* SmartRF 06 Evaluation Board with a CC26xx or CC13xx Evaluation Module
(relevant files and drivers are under `srf06/`)
* CC2650 SensorTag 2.0 (relevant drivers under `sensortag/cc2650`)
* CC1350 SensorTag 2.0 (relevant drivers under `sensortag/cc1350`)
* CC2650 LaunchPad (relevant drivers under `launchpad/cc2650`)
* CC1310 LaunchPad (relevant drivers under `launchpad/cc1310`)
* CC1350 LaunchPad (relevant drivers under `launchpad/cc1350`)
The CPU code, common for both platforms, can be found under `$(CONTIKI)/cpu/cc26xx-cc13xx`.
The port was developed and tested with CC2650s, but the intention is for it to
work with the CC2630 as well. Thus, bug reports are welcome for both chips.
Bear in mind that the CC2630 does not have BLE capability. Similar rules apply
in terms of CC13xx chips.
This port is only meant to work with 7x7mm chips
This guide assumes that you have basic understanding of how to use the command
line and perform basic admin tasks on UNIX family OSs.
Port Features
=============
The platform has the following key features:
* Deep Sleep support with RAM retention for ultra-low energy consumption.
* Support for CC26xx RF in IEEE as well as BLE mode (BLE support is very basic
since Contiki does not provide a BLE stack).
* Support for CC13xx prop mode: IEEE 802.15.4g-compliant sub GHz operation
In terms of hardware support, the following drivers have been implemented:
* SmartRF06 EB peripherals
* LEDs
* Buttons
* UART connectivity over the XDS100v3 backchannel
* SensorTag 2.0
* LEDs
* Buttons (One of the buttons can be used as a shutdown button)
* Reed relay
* Motion Processing Unit (MPU9250 - Accelerometer, Gyro)
* BMP280 sensor
* TMP007 sensor
* HDC1000 sensor
* OPT3001 sensor
* Buzzer
* External SPI flash
* LaunchPads
* LEDs
* Buttons
* External SPI flash
Requirements
============
To use the port you need:
* TI's CC26xxware sources. The correct version will be installed automatically
as a submodule when you clone Contiki.
* TI's CC13xxware sources. The correct version will be installed automatically
as a submodule when you clone Contiki.
* Contiki can automatically upload firmware to the nodes over serial with the
included [cc2538-bsl script](https://github.com/JelmerT/cc2538-bsl).
Note that uploading over serial doesn't work for the Sensortag, you can use
TI's SmartRF Flash Programmer in this case.
* A toolchain to build firmware: The port has been developed and tested with
GNU Tools for ARM Embedded Processors (<https://launchpad.net/gcc-arm-embedded>).
The current recommended version and the one being used by Contiki's regression
tests on Travis is shown below.
$ arm-none-eabi-gcc --version
arm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 5.2.1 20151202 (release) [ARM/embedded-5-branch revision 231848]
Copyright (C) 2015 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
* srecord (http://srecord.sourceforge.net/)
* You may also need other drivers so that the SmartRF can communicate with your
operating system and so that you can use the chip's UART for I/O. Please read
the section ["Drivers" in the CC2538DK readme](https://github.com/contiki-os/contiki/tree/master/platform/cc2538dk#drivers).
Examples
========
The port comes with three examples:
- A very basic example which demonstrates how to read sensors and how to use board peripherals. It also demonstrates how to send out BLE advertisements.
- A more advanced one (web demo) which includes a CoAP server, an MQTT client which connects and publishes to the IBM quickstart service, a net-based UART and lastly a web server that can be used to configure the rest of the example.
- An example demonstrating a very sleepy node.
More details about those three examples can be found in their respective READMEs.
Build your First Example
------------------------
It is recommended to start with the `cc26xx-demo` example under `examples/cc26xx/`. This is a very simple example which will help you get familiar with the hardware and the environment. This example can be used for the Sensortag and SmartRF06 EB.
Strictly speaking, to build it you need to run `make TARGET=srf06-cc26xx BOARD=srf06/cc26xx`. However, the example directories contain a `Makefile.target` which is automatically included and specifies the correct `TARGET=` argument. The `BOARD=` environment variable defaults to `srf06/cc26xx` (which is the SmartRF06 EB + CC26XXEM). Thus, for examples under the `cc26xx` directory, and when using the SmartRF06 EB, you can simply run `make`.
Other options for the `BOARD` make variable are:
* Srf06+CC26xxEM: Set `BOARD=srf06/cc26xx`
* Srf06+CC13xxEM: Set `BOARD=srf06/cc13xx`
* CC2650 tag: Set `BOARD=sensortag/cc2650`
* CC1350 tag: Set `BOARD=sensortag/cc1350`
* CC2650 Launchpad: Set `BOARD=launchpad/cc2650`
* CC1310 Launchpad: Set `BOARD=launchpad/cc1310`
* CC1350 Launchpad: Set `BOARD=launchpad/cc1350`
If the `BOARD` variable is unspecified, an image for the Srf06 CC26XXEM will be built.
If you want to switch between building for one platform to the other, make certain to `make clean` before building for the new one, or you will get linker
errors.
For the `cc26xx-demo`, the included readme describes in detail what the example does.
To generate an assembly listing of the compiled firmware, run `make cc26xx-demo.lst`. This may be useful for debugging or optimizing your application code. To intersperse the C source code within the assembly listing, you must instruct the compiler to include debugging information by adding `CFLAGS += -g` to the project Makefile and rebuild by running `make clean cc26xx-demo.lst`.
How to Program your Device
--------------------------
To program your device on Windows, use TI's [SmartRF Flash Programmer][smart-rf-flashprog] (FLASH-PROGRAMMER-2).
On Linux and OS X, you can program your device via the chip's serial ROM boot loader. In order for this to work, the following conditions need to be met:
* The board can support the bootloader. This is the case for SmartRF06EB with CC26xx/CC13xx EMs and it is also the case for LaunchPads. Note that uploading over serial does not (and will not) work for the Sensortag.
* The chip is not programmed with a valid image, or the image has the bootloader backdoor unlocked. To enable the bootloader backdoor in your image, define `ROM_BOOTLOADER_ENABLE` to 1 in `contiki-conf.h`.
You will then need to manually enter the boot loader and use the `.upload` make target (e.g. `make cc26xx-demo.upload` for the `cc26xx-demo`). On the SmartRF06, you enter the boot loader by resetting the EM (EM RESET button) while holding the `select` button. For the LaunchPad, you enter the bootloader by resetting the chip while holding `BTN_1`. It is possible to change the pin and its corresponding level (High/Low) that will trigger bootloader mode by changing `SET_CCFG_BL_CONFIG_BL_LEVEL` and `SET_CCFG_BL_CONFIG_BL_PIN_NUMBER` in `board.h`.
The serial uploader script will automatically pick the first available serial port. If this is not the port where your node is connected, you can force the script to use a specific port by defining the `PORT` argument eg. `make cc26xx-demo.upload PORT=/dev/tty.usbserial`.
For more information on the serial bootloader, see its README under the `tools/cc2538-bsl` directory.
CC13xx/CC26xx Border Router over UART
=====================================
The platform code can be used as a border router (SLIP over UART) by using the
example under `examples/ipv6/rpl-border-router`. This example defines the
following:
#ifndef UIP_CONF_BUFFER_SIZE
#define UIP_CONF_BUFFER_SIZE 140
#endif
#ifndef UIP_CONF_RECEIVE_WINDOW
#define UIP_CONF_RECEIVE_WINDOW 60
#endif
The CC26xx port has much higher capability than some other platforms used as
border routers. Thus, before building the example, it is recommended to delete
these two configuration directives. This will allow platform defaults to take
effect and this will improve performance and stability.
Do not forget to set the correct channel by defining `RF_CORE_CONF_CHANNEL` as
required.
CC13xx/CC26xx slip-radio with 6lbr
==================================
The platform can also operate as a slip-radio over UART, to be used with
[6lbr](http://cetic.github.io/6lbr/).
Similar to the border router configuration, you will need to remove the defines
that limit the size of the uIP buffer. Removing the two lines below from
`examples/ipv6/slip-radio/project-conf.h` should do it.
#undef UIP_CONF_BUFFER_SIZE
#define UIP_CONF_BUFFER_SIZE 140
Do not forget to set the correct channel by defining `RF_CORE_CONF_CHANNEL` as
required.
Filename conflicts between Contiki and CC26xxware
=================================================
There is a file called `timer.c` both in Contiki as well as in CC26xxware. The
way things are configured now, we don't use the latter. However, if you need to
start using it at some point, you will need to rename it:
From `cpu/cc26xx/lib/cc26xxware/driverlib/timer.c` to `driverlib-timer.c`
Sensortag UART usage (with or without the Debugger Devpack)
===========================================================
There are two ways to get debugging (printf etc) output from the Sensortag.
* Purchase a Debugger Devpack and set `BOARD_CONF_DEBUGGER_DEVPACK` to 1 in
`contiki-conf.h` or `project-conf.h`. This will work off the shelf for revision
1.2.0 of the debugger devpack.
* If you have an older (rev 1.0.0) devpack, you will need to do the above and
then to modify `board.h` in order to cross the RX and TX DIO mappings. (TX to
`IOID_28`, RX to `IOID_29`).
* If you don't have/want a debugger devpack, you can use a SmartRF and modify
the jumper configuration on P408 as discussed in
[this thread](https://e2e.ti.com/support/wireless_connectivity/f/158/p/411992/1483824#1483824)
on E2E. For this to work, you need to set `BOARD_CONF_DEBUGGER_DEVPACK` to 0.
IEEE vs Sub-GHz operation
=========================
The platform supports both modes of operation, provided the chip also has the
respective capability. If you specify nothing, the platform will default to
Sub-GHz mode for CC13xx devices, IEEE mode otherwise. To force IEEE mode, you
need to add this line to your `project-conf.h`.
#define CC13XX_CONF_PROP_MODE 0
Low Power Operation
===================
The platform takes advantage of the CC26xx's power saving features. In a
nutshell, here is how things work:
* When the RF is TXing, the CPU will enter sleep mode and will resume after TX
has completed.
* When there are no events in the Contiki event queue, the chip will enter
'some' low power mode (more below).
We do not use pre-defined power profiles (e.g. as mentioned in the TRM or as
we do for the CC2538 with LPM1, LPM2 etc). Each time we enter low power
operation, we either put the CM3 to sleep or to deep sleep. The latter case is
highly configurable: the LPM engine allows other code modules to register
themselves for notifications and to configure low power operation. With these
facilities, a module can e.g. prohibit deep sleep altogether, or it can request
that a power domain be kept powered. The LPM engine will turn off as many
CC26xx components as it can while satisfying all restrictions set by registered
modules.
To determine which power mode to use, the following logic is followed:
* The deepest available low power mode can be hard-coded by using
the `LPM_MODE_MAX_SUPPORTED` macro in the LPM driver (`lpm.[ch]`). Thus, it
is possible to prohibit deep sleep altogether.
* Code modules which are affected by low power operation can 'register'
themselves with the LPM driver.
* If the projected low-power duration is lower than `STANDBY_MIN_DURATION`,
the chip will simply sleep.
* If the projected low power duration is sufficiently long, the LPM will visit
all registered modules to query the maximum allowed power mode (maximum means
sleep vs deep sleep in this context). It will then drop to this power mode.
This is where a code module can forbid deep sleep if required.
* All registered modules will be notified when the chip is about to enter
deep sleep, as well as after wake-up.
When the chip does enter deep sleep:
* The RF Core, VIMS, SYSBUS and CPU power domains are always turned off. Due to
the way the RF driver works, the RFCORE PD should be off already.
* Peripheral clocks stop
* The Serial and Peripheral power domains are turned off, unless an LPM module
requests them to stay operational. For example, the net-uart demo keeps the
serial power domain powered on and the UART clocked under sleep and deep
sleep in order to retain UART RX functionality.
* If both SERIAL and PERIPH PDs are turned off, we also switch power source to
the uLDO for ultra low leakage under deep sleep.
The chip will come out of low power mode by one of the following events:
* Button press or, in the case of the SensorTag, a reed relay trigger
* Software clock tick (timer). The clock ticks at 128Hz, therefore the maximum
time we will ever spend in a sleep mode is 7.8125ms. In hardware terms, this
is an AON RTC Channel 2 compare interrupt.
* Rtimer triggers, as part of ContikiMAC's sleep/wake-up cycles. The rtimer
sits on the AON RTC channel 0.
[smart-rf-flashprog]: http://www.ti.com/tool/flash-programmer "SmartRF Flash Programmer"

283
arch/platform/zoul/README.md
View File

@ -1,283 +0,0 @@
Zolertia Zoul core module
============================================
![Zolertia Zoul Module][zoul]
The Zoul is a core module developed by Zolertia to target most IoT applications,
providing a flexible and affordable module solution to integrate to most
existing products and solutions, or ease the prototyping and production of new
products in a short time.
The Zoul is based on TI's CC2538 system on chip (SoC), featuring an ARM
Cortex-M3 with 512KB flash, 32Kb RAM, double RF interface, and the following
goodies:
* ISM 2.4-GHz IEEE 802.15.4 & Zigbee compliant.
* ISM 868-, 915-, 920-, 950-MHz ISM/SRD Band.
* AES-128/256, SHA2 Hardware Encryption Engine.
* ECC-128/256, RSA Hardware Acceleration Engine for Secure Key Exchange.
* Small form-factor of 16.78 x 30.89 mm.
* Prototype friendly, to fit on most prototyping boards (breadboard, etc.).
* Self-contained and EMI-protected module under a shield.
The Zoul will be CE/FCC certified (2016) to allow a fast integration and short time to market for new products and solutions.
Zoul pin-out
=============
![Zoul pin-out (front)][zoul-pinout-front]
![Zoul pin-out (back)][zoul-pinout-back]
Port Features
=============
The Zoul has the following key features:
* Deep Sleep support with RAM retention for ultra-low energy consumption.
* Native USB support (CDC-ACM). SLIP over UART for border routers is no longer a bottleneck.
* DMA transfers for increased performance (RAM to/from RF, RAM to/from USB).
In terms of hardware support, the following drivers have been implemented for the Zoul-based platforms:
* CC2538 System-on-Chip:
* Standard Cortex M3 peripherals (NVIC, SCB, SysTick)
* Sleep Timer (underpins rtimers)
* SysTick (underpins the platform clock and Contiki's timers infrastructure)
* RF (2.4GHz)
* UART
* Watchdog (in watchdog mode)
* USB (in CDC-ACM)
* uDMA Controller (RAM to/from USB and RAM to/from RF)
* Random number generator
* Low Power Modes
* General-Purpose Timers. NB: GPT0 is in use by the platform code, the remaining GPTs are available for application development.
* ADC
* Cryptoprocessor (AES-ECB/CBC/CTR/CBC-MAC/GCM/CCM-128/192/256, SHA-256)
* Public Key Accelerator (ECDH, ECDSA)
* Flash-based port of Coffee
* PWM
* LEDs
* Buttons
* Built-in core temperature and battery sensor.
* CC1200 sub-1GHz radio interface.
* Real Time Clock Calendar (on the RE-Mote platform).
* SD
There is a Zoul powering the RE-Mote and Firefly platforms, check out its specific README files for more information about on-board features.
Requirements
============
To start using Contiki, the following is required:
* A zoul-based board (RE-Mote, firefly)
* A toolchain to compile Contiki for the CC2538.
* Drivers so that your OS can communicate with your hardware.
* Software to upload images to the CC2538.
Install a Toolchain
-------------------
The toolchain used to build contiki is arm-gcc, also used by other arm-based Contiki ports. If you are using Instant Contiki, you may have a version pre-installed in your system.
The platform is currently being used/tested with "GNU Tools for ARM Embedded Processors" (<https://launchpad.net/gcc-arm-embedded>).
Always check which version [Travis currently uses for the ARM regression testing](https://github.com/contiki-os/contiki/blob/master/.travis.yml#L54)
To find out which version your system has:
$ arm-none-eabi-gcc --version
arm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 5.2.1 20151202 (release) [ARM/embedded-5-branch revision 231848]
Copyright (C) 2015 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Drivers
-------
Depending on your Zoul flavour, there are different options. As today the RE-Mote and Firefly platforms host a Zoul with a CP2104 USB-to-serial converter, governed by a low-power PIC to handle resetting and flashing the Zoul over USB, without having to press any button or use external tools.
The driver is available at <https://www.silabs.com/products/mcu/Pages/USBtoUARTBridgeVCPDrivers.aspx>
Check the board's specific README files for more information.
For windows users, if using the USB 2.0 interface (via CDC-ACM driver), there is an available driver in this folder:
`zolertia-zoul-cdc-acm`
Software to Program the Nodes
-----------------------------
The Zoul can be programmed via the jtag interface or via the serial boot loader on the chip.
Both the RE-Mote and Firefly has a mini JTAG 10-pin male header, compatible with the `SmartRF06` development board, which can be used to flash and debug the platforms. Alternatively one could use the `JLink` programmer with a 20-to-10 pin converter like the following: <https://www.olimex.com/Products/ARM/JTAG/ARM-JTAG-20-10/>.
The serial boot loader on the chip is exposed to the user via an USB interface. In the not so distant past we used to press a button sequence to unlock the boot loader, but now an on-board PIC in both RE-Motes and Fireflies handles this on its own, so it will detect the BSL sequence and flash the CC2538 without user intervention.
Instructions to flash for different OS are given below.
* On Windows:
* Nodes can be programmed with TI's ArmProgConsole or the [SmartRF Flash Programmer 2][smart-rf-flashprog]. The README should be self-explanatory. With ArmProgConsole, upload the file with a `.bin` extension. (jtag + serial)
* Nodes can also be programmed via the serial boot loader in the cc2538. In `tools/cc2538-bsl/` you can find `cc2538-bsl.py` this is a python script that can download firmware to your node via a serial connection. If you use this option you just need to make sure you have a working version of python installed. You can read the README in the same directory for more info. (serial)
* On Linux:
* Nodes can be programmed with TI's [UniFlash] tool. With UniFlash, use the file with `.elf` extension. (jtag + serial)
* Nodes can also be programmed via the serial boot loader in the cc2538. No extra software needs to be installed. (serial)
* On OSX:
* The `cc2538-bsl.py` script in `tools/cc2538-bsl/` is the only option. No extra software needs to be installed. (serial)
The file with a `.zoul` extension is a copy of the `.elf` file.
Use the Port
============
The following examples are intended to work off-the-shelf:
* Examples under `examples/zolertia/zoul`
* MQTT example `examples/cc2538dk/mqtt-demo`
* Border router: `examples/ipv6/rpl-border-router`
* Webserver: `examples/webserver-ipv6`
* CoAP example: `examples/er-rest-example/`
Build your First Examples
-------------------------
It is recommended to start with the `zoul-demo`, it is a simple example that walkthroughs the zoul features (can be compiled for both the RE-Mote and the Firefly), such as the built-in sensors, LEDs, user button operation modes (press, release, hold-press), radio (Rime broadcast).
The `Makefile.target` includes the `TARGET=` argument, predefining which is the target platform to compile for, it is automatically included at compilation. The `BOARD=` argument is using as a glue switch to pull in specific platform files, for example the specific RE-Mote core drivers. If no `BOARD` argument is given, it will default to `remote` and compile for the RE-Mote platform.
To generate or override an existing one, you can run:
`make TARGET=zoul savetarget`
Then you can just run `make` to compile an application, otherwise you will need to do `make TARGET=zoul`.
Alternatively you can export the following to your work environment:
`export BOARD=remote` or `export BOARD=firefly`
This will avoid having to type this argument at each compilation.
If you want to upload the compiled firmware to a node via the serial boot loader you need first to either manually enable the boot loader, or just let the Co-Processor detect the flash sequence and do it on your behalf, as simple as not pressing anything at all!
Then use `make zoul-demo.upload`.
The `PORT` argument could be used to specify in which port the device is connected, in case we have multiple devices connected at the same time.
To generate an assembly listing of the compiled firmware, run `make zoul-demo.lst`. This may be useful for debugging or optimizing your application code. To intersperse the C source code within the assembly listing, you must instruct the compiler to include debugging information by adding `CFLAGS += -g` to the project Makefile and rebuild by running `make clean zoul-demo.lst`.
To enable printing debug output to your console, use the `make login` to get the information over the USB programming/debugging port, or alternatively use `make serialview` to also add a timestamp in each print.
Node IEEE/RIME/IPv6 Addresses
-----------------------------
Nodes will generally autoconfigure their IPv6 address based on their IEEE address. The IEEE address can be read directly from the CC2538 Info Page, or it can be hard-coded. Additionally, the user may specify a 2-byte value at build time, which will be used as the IEEE address' 2 LSBs.
To configure the IEEE address source location (Info Page or hard-coded), use the `IEEE_ADDR_CONF_HARDCODED` define in contiki-conf.h:
* 0: Info Page
* 1: Hard-coded
If `IEEE_ADDR_CONF_HARDCODED` is defined as 1, the IEEE address will take its value from the `IEEE_ADDR_CONF_ADDRESS` define. If `IEEE_ADDR_CONF_HARDCODED` is defined as 0, the IEEE address can come from either the primary or secondary location in the Info Page. To use the secondary address, define `IEEE_ADDR_CONF_USE_SECONDARY_LOCATION` as 1.
Additionally, you can override the IEEE's 2 LSBs, by using the `NODEID` make variable. The value of `NODEID` will become the value of the `IEEE_ADDR_NODE_ID` pre-processor define. If `NODEID` is not defined, `IEEE_ADDR_NODE_ID` will not get defined either. For example:
make NODEID=0x79ab
This will result in the 2 last bytes of the IEEE address getting set to 0x79 0xAB
Note: Some early production devices do not have am IEEE address written on the Info Page. For those devices, using value 0 above will result in a Rime address of all 0xFFs. If your device is in this category, define `IEEE_ADDR_CONF_HARDCODED` to 1 and specify `NODEID` to differentiate between devices.
Low-Power Modes
---------------
The CC2538 port supports power modes for low energy consumption. The SoC will enter a low power mode as part of the main loop when there are no more events to service.
LPM support can be disabled in its entirety by setting `LPM_CONF_ENABLE` to 0 in `contiki-conf.h` or `project-conf.h`.
The Low-Power module uses a simple heuristic to determine the best power mode, depending on anticipated Deep Sleep duration and the state of various peripherals.
In a nutshell, the algorithm first answers the following questions:
* Is the RF off?
* Are all registered peripherals permitting PM1+?
* Is the Sleep Timer scheduled to fire an interrupt?
If the answer to any of the above question is "No", the SoC will enter PM0. If the answer to all questions is "Yes", the SoC will enter one of PMs 0/1/2 depending on the expected Deep Sleep duration and subject to user configuration and application requirements.
At runtime, the application may enable/disable some Power Modes by making calls to `lpm_set_max_pm()`. For example, to avoid PM2 an application could call `lpm_set_max_pm(1)`. Subsequently, to re-enable PM2 the application would call `lpm_set_max_pm(2)`.
The LPM module can be configured with a hard maximum permitted power mode.
#define LPM_CONF_MAX_PM N
Where N corresponds to the PM number. Supported values are 0, 1, 2. PM3 is not supported. Thus, if the value of the define is 1, the SoC will only ever enter PMs 0 or 1 but never 2 and so on.
The configuration directive `LPM_CONF_MAX_PM` sets a hard upper boundary. For instance, if `LPM_CONF_MAX_PM` is defined as 1, calls to `lpm_set_max_pm()` can only enable/disable PM1. In this scenario, PM2 can not be enabled at runtime.
When setting `LPM_CONF_MAX_PM` to 0 or 1, the entire SRAM will be available. Crucially, when value 2 is used the linker will automatically stop using the SoC's SRAM non-retention area, resulting in a total available RAM of 16MB instead of 32MB.
### LPM and Duty Cycling Driver
LPM is highly related to the operations of the Radio Duty Cycling (RDC) driver of the Contiki network stack and will work correctly with ContikiMAC and NullRDC.
* With ContikiMAC, PMs 0/1/2 are supported subject to user configuration.
* When NullRDC is in use, the radio will be always on. As a result, the algorithm discussed above will always choose PM0 and will never attempt to drop to PM1/2.
### Shutdown Mode
The RE-Mote has a built-in shutdown mode which effectively reduces the power consumption down to 150nA. Check its specific README file for more information.
Build headless nodes
--------------------
It is possible to turn off all character I/O for nodes not connected to a PC. Doing this will entirely disable the UART as well as the USB controller, preserving energy in the long term. The define used to achieve this is (1: Quiet, 0: Normal output):
#define CC2538_CONF_QUIET 0
Setting this define to 1 will automatically set the following to 0:
* `USB_SERIAL_CONF_ENABLE`
* `UART_CONF_ENABLE`
* `STARTUP_CONF_VERBOSE`
Code Size Optimisations
-----------------------
The build system currently uses optimization level `-Os`, which is controlled indirectly through the value of the `SMALL` make variable. This value can be overridden by example makefiles, or it can be changed directly in `platform/zoul/Makefile.zoul`.
Historically, the `-Os` flag has caused problems with some toolchains. If you are using one of the toolchains documented in this README, you should be able to use it without issues. If for whatever reason you do come across problems, try setting `SMALL=0` or replacing `-Os` with `-O2` in `cpu/cc2538/Makefile.cc2538`.
Doxygen Documentation
=====================
This port's code has been documented with doxygen. To build the documentation, navigate to `$(CONTIKI)/doc` and run `make`. This will build the entire contiki documentation and may take a while.
If you want to build this platform's documentation only and skip the remaining platforms, run this:
make basedirs="platform/zoul core cpu/cc2538 examples/zolertia/zoul examples/cc2538dk"
Once you've built the docs, open `$(CONTIKI)/doc/html/index.html` and enjoy.
Other Versions of this Guide
============================
If you prefer this guide in other formats, use the excellent [pandoc] to convert it.
* **pdf**: `pandoc -s --toc README.md -o README.pdf`
* **html**: `pandoc -s --toc README.md -o README.html`
More Reading
============
1. [Zolertia website][zolertia-site]
2. [Zolertia Wiki page][zolertia-wiki]
3. [CC2538 System-on-Chip Solution][cc2538]
4. [CC1200 sub-1GHz RF transceiver][cc1200]
5. [Zolertia Hackster channel][hackster]
6. [IoT in five days open source and online book][IoT5days]
Maintainers
===========
The Zoul and derived platforms (as well as the Z1 mote) are maintained by Zolertia.
Main contributor: Antonio Lignan <alinan@zolertia.com> <antonio.lignan@gmail.com>
[zolertia-site]: http://www.zolertia.io/products "Zolertia"
[zolertia-wiki]: https://github.com/Zolertia/Resources/wiki "Zolertia Wiki"
[cc1200]: http://www.ti.com/product/cc1200 "CC1200"
[smart-rf-studio]: http://www.ti.com/tool/smartrftm-studio "SmartRF Studio"
[smart-rf-flashprog]: http://www.ti.com/tool/flash-programmer "SmartRF Flash Programmer"
[cc2538]: http://www.ti.com/product/cc2538 "CC2538"
[uniflash]: http://processors.wiki.ti.com/index.php/Category:CCS_UniFlash "UniFlash"
[pandoc]: http://johnmacfarlane.net/pandoc/ "Pandoc - a universal document converter"
[hackster]: https://www.hackster.io/zolertia "Zolertia Hackster Channel"
[zoul]: images/zoul-front.png "Zolertia Zoul Module"
[zoul-pinout-front]: images/zoul-pinout-front.png "Zoul pin-out (front)"
[zoul-pinout-back]: images/zoul-pinout-back.png "Zoul pin-out (back)"
[IoT5days]: https://github.com/alignan/IPv6-WSN-book "IoT in Five days online book"

41
arch/platform/zoul/firefly-reva/README.md
View File

@ -1,41 +0,0 @@
Zolertia Firefly Revision A platform
============================================
![Zolertia Firefly Revision A breakout board][firefly-reva]
The Firefly is a breakout board designed to inspire.
It exposes the most basic Zoul features, sporting only the most down-to-core features to work with the Zoul, providing the following:
* ARM Cortex-M3 with 512KB flash and 32KB RAM (16KB retention), 32MHz.
* ISM 2.4-GHz IEEE 802.15.4 & Zigbee compliant.
* ISM 868-, 915-, 920-, 950-MHz ISM/SRD Band.
* On-board printed PCB sub-1GHz antenna and 2.4Ghz ceramic chip antenna.
* AES-128/256, SHA2 Hardware Encryption Engine.
* ECC-128/256, RSA Hardware Acceleration Engine for Secure Key Exchange.
* Compatible with breadboards and protoboards.
* On-board CP2104/PIC to flash over USB-A connector.
* User and reset buttons.
* RGB LED to allow more than 7 colour combinations.
* Small form factor (68.78 x 25.80mm).
The Firefly can be seen as the "small brother" of the RE-Mote, with a slick design and a lower cost.
To work out of the box, the firefly includes a PCB antenna for the Sub-1GHz interface, and a ceramic chip antenna for the 2.4GHz radio interface. Optionally 2 x u.Fl connectors for 2.4GHz and sub-1GHz external antennas can be mounted.
The firefly can be programmed and debugged over JTAG and USB. The board has a CP2104 USB to serial converter with a PIC, it allows to program the CC2538 without having to manually to put the device in bootloader mode.
The most prominent changes respect to the previous Firefly release are:
* On-board ceramic chip 2.4GHz antenna
* Pin-out changes and CC1200 GPIO2 pin is exposed
* RF matching improvements
* Printed PCB USB A connector instead of Micro-USB connector
Firefly pin-out
=============
![Firefly Revision A pin-out (front)][firefly-reva-pinout-front]
[firefly-reva-pinout-front]: ../images/firefly-reva-pinout-front.png "Firefly Revision A pin-out (front)"
[firefly-reva]: ../images/firefly-reva.jpg "Zolertia Firefly Revision A breakout board"

28
arch/platform/zoul/firefly/README.md
View File

@ -1,28 +0,0 @@
Zolertia Firefly platform
============================================
![Zolertia Firefly breakout board][firefly]
The Firefly is a breakout board designed to inspire.
It exposes the most basic Zoul features, sporting only the most down-to-core features to work with the Zoul, providing the following:
* ARM Cortex-M3 with 512KB flash and 32KB RAM (16KB retention), 32MHz.
* ISM 2.4-GHz IEEE 802.15.4 & Zigbee compliant.
* ISM 868-, 915-, 920-, 950-MHz ISM/SRD Band.
* On-board printed PCB sub-1GHz antenna, alternatively u.FL for sub-1GHz/2.4GHz external antennas.
* AES-128/256, SHA2 Hardware Encryption Engine.
* ECC-128/256, RSA Hardware Acceleration Engine for Secure Key Exchange.
* Compatible with breadboards and protoboards.
* On-board CP2104/PIC to flash over USB.
* User and reset buttons.
* RGB LED to allow more than 7 colour combinations.
* Small form factor (53x25mm).
The Firefly can be seen as the "small brother" of the RE-Mote, with a slick design and a lower cost.
To work out of the box, the firefly includes a PCB antenna for the Sub-1GHz interface, as well as 2 x u.Fl connectors for 2.4GHz and sub-1GHz external antennas.
The firefly can be programmed and debugged over JTAG and USB. The board has a CP2104 USB to serial converter with a PIC, it allows to program the CC2538 without having to manually to put the device in bootloader mode.
[firefly]: ../images/firefly.png "Zolertia RE-Firefly breakout board"

BIN
arch/platform/zoul/images/firefly-reva.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 487 KiB

44
arch/platform/zoul/orion/README.md
View File

@ -1,44 +0,0 @@
Zolertia Orion Ethernet Router
============================================
![Zolertia Orion Ethernet Router][zolertia-orion-router]
The Zolertia Orion Ethernet Router allows to create IoT applications out-of-the-box, connecting any IPv4/IPv6 service or application to 6LoWPAN wireless networks.
The Orion Router is a capable IPv4/IPv6 routing device, with an Ethernet interface and dual wireless radio, powered either via micro-USB or Power Over Ethernet (POE). The device integrates the ENC28J60 ethernet module, and an external POE module, supporting up to 48VDC.
Orion is compatible with [6lbr](https://github.com/cetic/6lbr/wiki), more information is available at our [Wiki](https://github.com/Zolertia/Resources/wiki/6lbr).
In a nutshell the Orion Router packs the following features:
* ARM Cortex-M3 with 512KB flash and 32KB RAM (16KB retention), 32MHz.
* ISM 2.4-GHz IEEE 802.15.4 & Zigbee compliant.
* ISM 868-, 915-, 920-, 950-MHz ISM/SRD Band.
* RP-SMA connector for a 2.4GHz external antenna
* SMA connector for a 868/915MHz external antenna
* RJ45 ethernet connector
* Ethernet 10BASE-T IPv4/IP64
* AES-128/256, SHA2 Hardware Encryption Engine.
* ECC-128/256, RSA Hardware Acceleration Engine for Secure Key Exchange.
* On-board CP2104/PIC to flash over its micro-USB connector
* User and reset buttons.
* Power on/off button and LED to show power state
* RGB LED to allow more than 7 colour combinations.
* Indoor enclosure
* Layout 40.29 x 73.75 mm
There are ready-to-use examples at `examples/zolertia/zoul/orion`, showing how to deploy an IP64 border router, and connect to services such as [IFTTT (If This Then That)](https://ifttt.com).
Orion Technical documentation
=============
* [Datasheet](https://github.com/Zolertia/Resources/tree/master/Orion%20Ethernet%20Router/Hardware/Revision%20A/Datasheets)
* [Schematics](https://github.com/Zolertia/Resources/tree/master/Orion%20Ethernet%20Router/Hardware/Revision%20A/Schematics)
Orion Ethernet Router pin-out
=============
![Zolertia Orion Ethernet Router pin-out][zolertia-orion-pinout]
[zolertia-orion-pinout]: ../images/orion-pinout.png "Zolertia Orion Router pin-out"
[zolertia-orion-router]: ../images/orion-router-front.png "Zolertia Orion Ethernet Router"

48
arch/platform/zoul/remote-reva/README.md
View File

@ -1,48 +0,0 @@
Zolertia RE-Mote platform (revision A)
============================================
![Zolertia RE-Mote development platform][remote-front]
The RE-Mote is a hardware development platform to build real IoT (Internet of Things) applications and products, aimed to high skilled developers as well as Makers (Do-It-Yourself enthusiasts) and early beginners, providing an industry-ready and resilient hardware solution for most Smart Cities, Home Comfort, eHealth and Industrial applications. The RE-Mote conciliates an ultra-low power consumption with a high performance design, meeting specifications of processing resources, security and resilient operation.
The RE-Mote platform was designed jointly with universities and industrial partners from different countries in the context of RERUM <https://ict-rerum.eu> European Project.
![Zolertia RE-Mote development platform][remote-back]
The RE-Mote features a Zoul as its core module and it is bundled with the following features:
* ARM Cortex-M3 with 512KB flash and 32KB RAM (16KB retention), 32MHz.
* ISM 2.4-GHz IEEE 802.15.4 & Zigbee/Thread compliant.
* ISM 868-, 915-, 920-, 950-MHz ISM/SRD Band.
* On-board RF switch to programatically select RF itnerfaces. Above RF interfaces can be used alternatively over a single RP-SMA connector for external antenna, or simultaneously by using an UFl pigtail or soldering an internal ceramic chip antenna (available on request).
* AES-128/256, SHA2 Hardware Encryption Engine.
* ECC-128/256, RSA Hardware Acceleration Engine for Secure Key Exchange.
* Power consumption down to 170nA using our shutdown mode.
* Programming over BSL without requiring to press any button to enter bootloader mode.
* Built-in battery charger (500mA), Energy Harvesting and Solar Panels to be connected to standards LiPo batteries.
* Power input with wide range 3.7-16VDC.
* On-board micro USB connector for USB 2.0 applications.
* RGB LED to allow more than 7 colour combinations.
* On-board nano-watt Real Time Clock Calendar (RTCC).
* User and Reset buttons.
* On-board Micro-SD for external storage.
* On-board external Watchdog Timer (WDT) for resilient operation.
* Small form-factor of 73x40 mm.
* Available with enclosure for indoor use
The most prominent feature of the RE-Mote is its ultra low-power implementation, allowing a flexible and time/date-aware control of the platform operation modes by introducing a real-time clock (RTCC), nanowatt external timer, ultra-low power PIC governing the battery manager, etc.
The RE-Mote features an optional custom-made enclosure to fit most scenarios, allowing to easily connect sensors, actuators and rechargeable LiPo batteries. Its on-board RP-SMA antenna eliminates the need to mechanize an external antenna, allowing to alternatively use either a sub-1GHz or 2.4GHz antenna, or a multiband one. For dual band applications it is possible to use both sub-GHz and 2.4GHz interfaces simultaneously.
The external WDT with battery monitor allows a robust and resilience operation for most critical applications.
Zoul pin-out
=============
![RE-Mote pin-out (front)][remote-pinout-front]
![RE-Mote pin-out (back)][remote-pinout-back]
[remote-front]: ../images/remote-front.png "Zolertia RE-Mote development platform"
[remote-back]: ../images/remote-back.png "Zolertia RE-Mote development platform"
[remote-pinout-front]: ../images/remote-pinout-front.png "RE-Mote pin-out (front)"
[remote-pinout-back]: ../images/remote-pinout-back.png "RE-Mote pin-out (back)"

43
arch/platform/zoul/remote-revb/README.md
View File

@ -1,43 +0,0 @@
Zolertia RE-Mote platform (revision B)
============================================
The RE-Mote is a hardware development platform to build real IoT (Internet of Things) applications and products, aimed to high skilled developers as well as Makers (Do-It-Yourself enthusiasts) and early beginners, providing an industry-ready and resilient hardware solution for most Smart Cities, Home Comfort, eHealth and Industrial applications. The RE-Mote conciliates an ultra-low power consumption with a high performance design, meeting specifications of processing resources, security and resilient operation.
The RE-Mote platform was designed jointly with universities and industrial partners from different countries in the context of RERUM <https://ict-rerum.eu> European Project.
The RE-Mote features a Zoul as its core module and it is bundled with the following features:
* ARM Cortex-M3 with 512KB flash and 32KB RAM (16KB retention), 32MHz.
* ISM 2.4-GHz IEEE 802.15.4 & Zigbee/Thread compliant.
* ISM 868-, 915-, 920-, 950-MHz ISM/SRD Band.
* On-board RF switch to programatically select RF itnerfaces. Above RF interfaces can be used alternatively over a single RP-SMA connector for external antenna, or simultaneously by using an UFl pigtail or soldering an internal ceramic chip antenna (available on request).
* AES-128/256, SHA2 Hardware Encryption Engine.
* ECC-128/256, RSA Hardware Acceleration Engine for Secure Key Exchange.
* Power consumption down to 150nA using our shutdown mode.
* Programming over BSL without requiring to press any button to enter bootloader mode.
* Built-in battery charger (500mA), Energy Harvesting and Solar Panels to be connected to standards LiPo batteries.
* Power input with wide range 3.7-16VDC.
* On-board micro USB connector for USB 2.0 applications.
* RGB LED to allow more than 7 colour combinations.
* On-board nano-watt Real Time Clock Calendar (RTCC).
* User and Reset buttons.
* On-board Micro-SD for external storage.
* On-board external Watchdog Timer (WDT) for resilient operation.
* Small form-factor of 73x40 mm.
* Available with enclosure for indoor use
The changes from Revision A to this new Revision B are summarized in the [Wiki](https://github.com/Zolertia/Resources/wiki/RE-Mote:-Enhancements-from-Rev.A-to-Rev.B)
The most prominent feature of the RE-Mote is its ultra low-power implementation, allowing a flexible and time/date-aware control of the platform operation modes by using its real-time clock (RTCC) and an ultra-low power PIC governing the battery manager.
The RE-Mote features an optional custom-made enclosure to fit most scenarios, allowing to easily connect sensors, actuators and rechargeable LiPo batteries. Its on-board RP-SMA antenna eliminates the need to mechanize an external antenna, allowing to alternatively use either a sub-1GHz or 2.4GHz antenna, or a multiband one. For dual band applications it is possible to use both sub-GHz and 2.4GHz interfaces simultaneously.
The external WDT with battery monitor allows a robust and resilience operation for most critical applications.
Zoul pin-out
=============
![RE-Mote pin-out (front)][remote-pinout-front]
![RE-Mote pin-out (back)][remote-pinout-back]

4
doc/Doxyfile
View File

@ -168,7 +168,7 @@ STRIP_FROM_INC_PATH = $(docroot)
# support long names like on DOS, Mac, or CD-ROM.
# The default value is: NO.
SHORT_NAMES = YES
SHORT_NAMES = NO
# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the
# first line (until the first dot) of a Javadoc-style comment as the brief
@ -1142,7 +1142,7 @@ HTML_TIMESTAMP = YES
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_DYNAMIC_SECTIONS = NO
HTML_DYNAMIC_SECTIONS = YES
# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries
# shown in the various tree structured indices initially; the user can expand

35
doc/Makefile
View File

@ -1,4 +1,4 @@
basedirs := os arch/cpu arch/platform
basedirs := os arch
manuals := $(shell find ./ -name "*.txt")
filetypes := -iwholename "*/doc/*.txt"
empty :=
@ -21,41 +21,16 @@ ifeq ($(HOST_OS),Windows)
endif
endif
.PHONY: clean html pdf upload
docdirs = $(sort $(foreach dir,$(basedirs),${shell find ../${dir} -type d -not -path "*/.*" -not -path "*/obj_*"}))
docsrc = $(docdirs) $(foreach dir,$(docdirs),${shell find $(dir) -type f $(filetypes)}) $(manuals)
html: init doxygen.log
.PHONY: clean html
pdf: doclatex = YES
pdf: init doxygen.log
gmake -C latex refman.pdf
init:
@echo "> Scanning files"
# This target requires and graphviz and doxygen
doxygen.log: docdirs = $(sort $(foreach dir,$(basedirs),${shell find ../${dir} -type d -not -path "*/.*" -not -path "*/obj_*"}))
doxygen.log: docsrc = $(docdirs) $(foreach dir,$(docdirs),${shell find $(dir) -type f $(filetypes)}) $(manuals)
doxygen.log:
html:
@doxygen Doxyfile
@echo "Done, errorlog follows:"
@echo ""
@touch doxygen.log
@cat "doxygen.log"
clean:
@echo "> Cleaning Documentation"
@$(RM) -r "$(docdir)/html"
@$(RM) -r "$(docdir)/rtf"
@$(RM) -r "$(docdir)/latex"
@$(RM) -r "doxygen.log"
@echo " done."
#upload: html #pdf
# scp -C latex/refman.pdf adamdunkels@shell.sourceforge.net:/home/groups/c/co/contiki/htdocs/
# tar czfv - html | ssh adamdunkels@shell.sourceforge.net "cd /home/groups/c/co/contiki/htdocs/; tar xfz -"
# (cd html; rsync -rv . r2d2.sics.se:/home/adam/public_html/contiki/docs)
test:
@echo $(docroot)
@echo $(docsrc)

95
doc/build-system.txt
View File

@ -1,95 +0,0 @@
/**
\ingroup tutorials
\defgroup buildsystem The \os build system
The \os build system is designed to make it easy to compile
\os applications for either to a hardware platform or into a
simulation platform by simply supplying different parameters to the
<tt>make</tt> command, without having to edit makefiles or modify
the application code.
The file example project in examples/hello-world/ shows how the
\os build system works. The <tt>hello-world.c</tt> application
can be built into a complete \os system by running <tt>make</tt>
in the examples/hello-world/ directory. Running <tt>make</tt> without
parameters will build a \os system using the <tt>native</tt>
target. The <tt>native</tt> target is a special \os platform that
builds an entire \os system as a program that runs on the
development system. After compiling the application for the
<tt>native</tt> target it is possible to run the \os system with
the application by running the file <tt>hello-world.native</tt>.
To compile the hello-world application into a stand-alone executable
that can be loaded into a running \os system, the command
<tt>make hello-world.ce</tt> is used. To build an executable file for
the Sky platform, <tt>make TARGET=sky hello-world.sky</tt> is run.
To avoid having to type <tt>TARGET=</tt> every time <tt>make</tt> is
run, it is possible to run <tt>make TARGET=sky savetarget</tt> to
save the selected target as the default target platform for
subsequent invocations of <tt>make</tt>. A file called
<tt>Makefile.target</tt> containing the currently saved target is
saved in the project's directory.
\section buildsystem-makefiles Makefiles used in the \os build system
The \os build system is composed of a number of Makefiles. These
are:
- <tt>Makefile</tt>: the project's makefile, located in the project directory.
- <tt>Makefile.include</tt>: the system-wide \os makefile,
located in the root of the \os source tree.
- <tt>Makefile.\$(TARGET)</tt> (where \$(TARGET) is the name of the
platform that is currently being built): rules for the specific
platform, located in the platform's subdirectory in the platform/ directory.
- <tt>Makefile.\$(CPU)</tt> (where \$(CPU) is the name of the CPU or
microcontroller architecture used on the platform for which \os
is built): rules for the CPU architecture, located in the CPU
architecture's subdirectory in the cpu/ directory.
- <tt>Makefile.\$(MODULE)</tt> (where \$(MODULE) is the name of a
module in the Contiki directory): rules for modules in the
Contiki directories. Each module might have its own optional makefile.
The Makefile in the project's directory is intentionally simple. It
specifies where the \os source code resides in the system and
includes the system-wide Makefile, <tt>Makefile.include</tt>. The
project's makefile can also define in the <tt>MODULES</tt> variable a
list of modules that should be included in the \os system.
The Makefile used in the hello-world example project looks like this:
\code
CONTIKI = ../..
all: hello-world
include $(CONTIKI)/Makefile.include
\endcode
First, the location of the \os source code tree is given by
defining the <tt>CONTIKI</tt> variable. Next, the name of the
application is defined. Finally, the system-wide
<tt>Makefile.include</tt> is included.
The <tt>Makefile.include</tt> contains definitions of the C files of
the core \os system. <tt>Makefile.include</tt> always reside in
the root of the \os source tree. When <tt>make</tt> is run,
<tt>Makefile.include</tt> includes the <tt>Makefile.\$(TARGET)</tt>
as well as all makefiles for the modules in the <tt>MODULES</tt>
list (which is specified by the project's <tt>Makefile</tt>).
<tt>Makefile.\$(TARGET)</tt>, which is located in the
platform/\$(TARGET)/ directory, contains the list of C files that the
platform adds to the \os system. This list is defined by the
<tt>CONTIKI_TARGET_SOURCEFILES</tt> variable. The
<tt>Makefile.\$(TARGET)</tt> also includes the
<tt>Makefile.\$(CPU)</tt> from the cpu/\$(CPU)/ directory.
The <tt>Makefile.\$(CPU)</tt> typically contains definitions for the
C compiler used for the particular CPU. If multiple C compilers are
used, the <tt>Makefile.\$(CPU)</tt> can either contain a conditional
expression that allows different C compilers to be defined, or it can
be completely overridden by the platform specific makefile
<tt>Makefile.\$(TARGET)</tt>.
@{
*/
/**
@}
*/

137
doc/code-style.c
View File

@ -1,137 +0,0 @@
/**
* \defgroup coding-style Coding style
*
* This is how a Doxygen module is documented - start with a \defgroup
* Doxygen keyword at the beginning of the file to define a module,
* and use the \addtogroup Doxygen keyword in all other files that
* belong to the same module. Typically, the \defgroup is placed in
* the .h file and \addtogroup in the .c file.
*
* The Contiki source code contains an Uncrustify configuration file,
* uncrustify.cfg, under tools/code-style and small helper scripts are
* provided at the same place. Note that this is not a silver bullet -
* for example, the script does not add separators between functions,
* nor does it format comments correctly. The script should be treated
* as an aid in formatting code: first run the formatter on the source
* code, then manually edit the file.
*
* @{
*/
/**
* \file
* A brief description of what this file is.
* \author
* Adam Dunkels <adam@dunkels.com>
*
* Every file that is part of a documented module has to have
* a \file block, else it will not show up in the Doxygen
* "Modules" * section.
*/
/* Single line comments look like this. */
/*
* Multi-line comments look like this. Comments should prefferably be
* full sentences, filled to look like real paragraphs.
*/
#include "contiki.h"
/*
* Make sure that non-global variables are all maked with the static
* keyword. This keeps the size of the symbol table down.
*/
static int flag;
/*
* All variables and functions that are visible outside of the file
* should have the module name prepended to them. This makes it easy
* to know where to look for function and variable definitions.
*
* Put dividers (a single-line comment consisting only of dashes)
* between functions.
*/
/*---------------------------------------------------------------------------*/
/**
* \brief Use Doxygen documentation for functions.
* \param c Briefly describe all parameters.
* \return Briefly describe the return value.
* \retval 0 Functions that return a few specified values
* \retval 1 can use the \retval keyword instead of \return.
*
* Put a longer description of what the function does
* after the preamble of Doxygen keywords.
*
* This template should always be used to document
* functions. The text following the introduction is used
* as the function's documentation.
*
* Function prototypes have the return type on one line,
* the name and arguments on one line (with no space
* between the name and the first parenthesis), followed
* by a single curly bracket on its own line.
*/
int
code_style_example_function(char c)
{
/*
* Local variables should always be declared at the start of the
* function.
*/
int i; /* Use short variable names for loop
counters. */
/*
* There should be no space between keywords and the first
* parenthesis. There should be spaces around binary operators, no
* spaces between a unary operator and its operand.
*
* Curly brackets following for(), if(), do, and switch() statements
* should follow the statement on the same line.
*/
for(i = 0; i < 10; ++i) {
/*
* Always use full blocks (curly brackets) after if(), for(), and
* while() statements, even though the statement is a single line
* of code. This makes the code easier to read and modifications
* are less error prone.
*/
if(i == c) {
return 1; /* No parentesis around return values. */
} else { /* The else keyword is placed inbetween
curly brackers, always on its own line. */
c++;
}
}
/*
* Indent "case" statement and "default" label by two spaces in "switch"
* statement.
*/
switch(c) {
case 19:
return 1;
default:
break;
}
return 0;
}
/*---------------------------------------------------------------------------*/
/*
* Static (non-global) functions do not need Doxygen comments. The
* name should not be prepended with the module name - doing so would
* create confusion.
*/
static void
an_example_function(void)
{
}
/*---------------------------------------------------------------------------*/
/* The following stuff ends the \defgroup block at the beginning of
the file: */
/** @} */

85
doc/mainpage.txt
View File

@ -2,87 +2,8 @@
\mainpage The \os Operating System
\os is an operating system for resource-constrained devices in the
Internet of Things. \os contains a low-power IPv6 communication stack,
\ref uip "uIP". uIP is a small RFC-compliant TCP/IP stack that makes
it possible for \os to communicate over the Internet. The system runs
on a variety of platforms based on energy-efficient architectures such
as the ARM Cortex-M3 and the Texas Instruments MSP430. The code
footprint is on the order of a 100 kb, and the memory usage can be
configured to be as low as 10 kb.
In 2017, \os started as a fork of the Contiki operating system with
the purpose of making a system focused on standard low-power IPv6
communication in the IoT. Another important goal is to have a regular
release cycle and enhanced documentation. Although both systems at the
beginning have many common interfaces and modules, we expect them to
diverge considerably in the future.
Most of \os is written in the standard C programming language, with
the exception of some architecture-specific code that may use compiler
extensions and assembly language. The source code is available as open
source with a 3-clause BSD license.
\section mainpage-getting-started Getting started with \os
\os is designed to run on many different \ref platform "platforms". It
is also possible to compile and build both the \os system and \os
applications on many different development platforms.
\section mainpage-building Building the \os system and its applications
The \os build system is designed to make it easy to compile
\os applications for either to a hardware platform or into a
simulation platform by simply supplying different parameters to the
<tt>make</tt> command, without having to edit makefiles or modify
the application code.
See \ref buildsystem
\section mainpage-tcpip Low-Power IPv6 Networking
One of the main features of \os is a resource-efficient IPv6 network
stack designed for lossy and low-power networks. The network stack
comprises protocols such as IPv6, TCP, UDP, DNS, RPL, CoAP, LWM2M, and
Websockets. Beneath the IPv6 stack, \os supports IEEE 802.15.4
wireless communication with Time-Slotted Channel Hopping (TSCH).
\sa \ref uip "The uIP TCP/IP stack documentation"
\sa \ref tcpip "The \os/uIP interface"
\sa \ref psock "Protosockets library"
\section mainpage-threads Application Development
Applications in \os are implemented using processes, which are based
on a programming abstraction called Protothreads. Protothreads is
essentially a lightweight stackless thread-like construct, allowing
highly efficient context switching.
A process is scheduled by an event-driven kernel after an event has
been sent to the process, either from the kernel of from another
process. Such events can be the result of a timer expiring, a sensor
value changing, or a network packet having been received. Once
scheduled, each process is responsible for yielding control back to
the scheduler without executing for too long, which is typically done
by waiting for an event. Alternatively, applications can also use the
\ref mt, which supports a more traditional thread model with one stack
per thread.
\sa \ref process "Processes"
\sa \ref pt "Protothreads"
\sa \ref etimer "Event timers"
\sa \ref ctimer "Callback timers"
\sa \ref mt "Optional multi-threading"
\section mainpage-lib Libraries
\os provides a set of convenience libraries for common programming
functionality, including memory management and data structures.
\sa \ref memb "Memory block management"
\sa \ref heapmem "Heap memory allocator"
\sa \ref list "Linked list library"
\sa \ref ringbuf "Ring buffer library"
\sa \ref trickle-timer "Trickle timer"
This is the code documentation for \os. More documentation, including
feature description, tutorials etc, can be found at
https://github.com/sics-iot/contiki/wiki.
*/

16
doc/modules.txt
View File

@ -40,6 +40,7 @@ CPU, device drivers and platform code
/**
\defgroup net IoT networking
The communication protocols
*/
/**
@ -79,6 +80,12 @@ Supports only non-storing mode, one instance and one DAG.
/**
\defgroup lib Libraries and services
A set of libraries and services used by the os and applications
*/
/**
\defgroup sys System functions
Core system components such as processes and timers
*/
/**
@ -112,12 +119,3 @@ This module contains protothreads, multithreading and processes
This module contains all different timers and clocks in \os
* \ingroup sys
*/
/**
* \defgroup tutorials Tutorials
This module contains all \os related tutorials.
*/
/**
\example code-style.c
*/

120
os/net/ipv6/multicast/README.md
View File

@ -1,120 +0,0 @@
README file for Contiki's IPv6 multicast core
Author: George Oikonomou
What does it do
===============
These files, alongside some core modifications, add support for IPv6 multicast
to contiki's uIPv6 engine.
Currently, three modes are supported:
* 'Enhanced Stateless Multicast RPL Forwarding' (ESMRF)
ESMRF is an enhanced version of the SMRF engine with the aim
of resolving the sending limitation of SMRF to allow any node
within the DODAG to send multicast traffic up and down the RPL tree.
ESMRF is documented here:
http://dl.acm.org/citation.cfm?id=2753479
* 'Stateless Multicast RPL Forwarding' (SMRF)
RPL in MOP 3 handles group management as per the RPL docs,
SMRF is a lightweight engine which handles datagram forwarding.
SMRF is documented here:
http://dx.doi.org/10.1007/s11277-013-1250-5
and here:
http://dx.doi.org/10.1109/PerComW.2012.6197494
* 'Multicast Forwarding with Trickle' according to the algorithm described
in the internet draft:
http://tools.ietf.org/html/draft-ietf-roll-trickle-mcast
The version of this draft that's currently implementated is documented
in `roll-tm.h`
More engines can (and hopefully will) be added in the future. The first
addition is most likely going to be an updated implementation of MPL
The Big Gotcha
==============
Currently we only support traffic originating and destined inside a single 6LoWPAN
To be able to send multicast traffic from the internet to 6LoWPAN nodes or the other
way round, we need border routers or other gateway devices to be able to achieve
the following:
* Add/Remove Trickle Multicast, RPL or other HBHO headers as necessary for datagrams
entering / exiting the 6LoWPAN
* Advertise multicast group membership to the internet (e.g. with MLD)
These are currently not implemented and are in the ToDo list. Contributions welcome.
Where to Start
==============
The best place in `examples/ipv6/multicast`
There is a cooja example demonstrating basic functionality
How to Use
==========
Look in `os/net/ipv6/multicast/uip-mcast6-engines.h` for a list of supported
multicast engines.
To turn on multicast support, add this line in your `project-` or `contiki-conf.h`
#define UIP_MCAST6_CONF_ENGINE xyz
where xyz is a value from `uip-mcast6-engines.h`
To disable:
#define UIP_MCAST6_CONF_ENGINE 0
You also need to make sure the multicast code gets built. Your example's
(or platform's) Makefile should include this:
MODULES += os/net/ipv6/multicast
How to extend
=============
Let's assume you want to write an engine called foo.
The multicast API defines a multicast engine driver in a fashion similar to
the various NETSTACK layer drivers. This API defines functions for basic
multicast operations (init, in, out).
In order to extend multicast with a new engine, perform the following steps:
- Open `uip-mcast6-engines.h` and assign a unique integer code to your engine
#define UIP_MCAST6_ENGINE_FOO xyz
- Include your engine's `foo.h`
- In `foo.c`, implement:
* `init()`
* `in()`
* `out()`
* Define your driver like so:
`const struct uip_mcast6_driver foo_driver = { ... }`
- If you want to maintain stats:
* Standard multicast stats are maintained in `uip_mcast6_stats`. Don't access
this struct directly, use the macros provided in `uip-mcast6-stats.h` instead
* You can add your own stats extensions. To do so, declare your own stats
struct in your engine's module, e.g `struct foo_stats`
* When you initialise the stats module with `UIP_MCAST6_STATS_INIT`, pass
a pointer to your stats variable as the macro's argument.
An example of how to extend multicast stats, look at the ROLL TM engine
- Open `uip-mcast6.h` and add a section in the `#if` spree. This aims to
configure the uIPv6 core. More specifically, you need to:
* Specify if you want to put RPL in MOP3 by defining
`RPL_WITH_MULTICAST`: 1: MOP 3, 0: non-multicast MOP
* Define your engine details
#define UIP_MCAST6 foo_driver
#define UIP_MCAST6_STATS foo_stats
typedef struct foo_stats uip_mcast6_stats_t;
* Optionally, add a configuration check block to stop builds when the
configuration is not sane.
If you need your engine to perform operations not supported by the generic
UIP_MCAST6 API, you will have to hook those in the uip core manually. As an
example, see how the core is modified so that it can deliver ICMPv6 datagrams
to the ROLL TM engine.

5
os/net/mac/llsec802154.h
View File

@ -32,7 +32,9 @@
/**
* \addtogroup link-layer
* \defgroup llsec802154 Link-Layer security common functionality
* @{
*
* \defgroup llsec802154 Link-layer security common functionality
*
* Macros related to 802.15.4 link-layer security.
*
@ -83,3 +85,4 @@
#endif /* LLSEC802154_H_ */
/** @} */
/** @} */

185
os/net/mac/tsch/README.md
View File

@ -1,185 +0,0 @@
# IEEE 802.15.4-2015 TSCH and IETF 6TiSCH
## Overview
Time Slotted Channel Hopping (TSCH) is a MAC layer of the [IEEE 802.15.4e-2012 amendment][ieee802.15.4e-2012],
currently being integrated as part of the new IEEE 802.15.4-2015.
[6TiSCH][ietf-6tisch-wg] is an IETF Working Group focused on IPv6 over TSCH.
This is a Contiki implementation of TSCH and the 6TiSCH so-called "minimal configuration",
which defines how to run a basic RPL+TSCH network.
It was developped by:
* Simon Duquennoy, SICS, simonduq@sics.se, github user: [simonduq](https://github.com/simonduq)
* Beshr Al Nahas, SICS (now Chalmers University), beshr@chalmers.se, github user: [beshrns](https://github.com/beshrns)
* Atis Elsts, Univ. Bristol, atis.elsts@bristol.ac.uk, github user: [atiselsts](https://github.com/atiselsts)
This implementation is presented in depth and evaluated in our paper: [*TSCH and 6TiSCH for Contiki: Challenges, Design and Evaluation*](http://www.simonduquennoy.net/papers/duquennoy17tsch.pdf), IEEE DCOSS'17.
The scheduler Orchestra is detailled in [*Orchestra: Robust Mesh Networks Through Autonomously Scheduled TSCH*](http://www.simonduquennoy.net/papers/duquennoy15orchestra.pdf), ACM SenSys'15.
## Features
This implementation includes:
* Standard IEEE 802.15.4e-2012 frame version 2
* Standard TSCH joining procedure with Enhanced Beacons with the following Information Elements:
* TSCH synchronization (join priority and ASN)
* TSCH slotframe and link (basic schedule)
* TSCH timeslot (timeslot timing template)
* TSCH channel hopping sequence (hopping sequence template)
* Standard TSCH link selection and slot operation (10ms slots by default)
* Standard TSCH synchronization, including with ACK/NACK time correction Information Element
* Standard TSCH queues and CSMA-CA mechanism
* Standard TSCH and 6TiSCH security
* Standard 6TiSCH TSCH-RPL interaction (6TiSCH Minimal Configuration and Minimal Schedule)
* A scheduling API to add/remove slotframes and links
* A system for logging from TSCH timeslot operation interrupt, with postponed printout
* Orchestra: an autonomous scheduler for TSCH+RPL networks
* A drift compensation mechanism
It has been tested on the following platforms:
* NXP JN516x (`jn516x`, tested on hardware)
* Tmote Sky (`sky`, tested on hardware and in cooja)
* Zolertia Z1 (`z1`, tested in cooja only)
* CC2538DK (`cc2538dk`, tested on hardware)
* Zolertia Zoul (`zoul`, tested on hardware)
* OpenMote-CC2538 (`openmote-cc2538`, tested on hardware)
* CC2650 (`srf06-cc26xx`, tested on hardware)
* Cooja mote (`cooja`, tested with cooja)
This implementation was present at the ETSI Plugtest
event in Prague in July 2015, and did successfully inter-operate with all
four implementations it was tested against.
We have designed this implementation with IPv6 and RPL in mind, but the code is fully independent
from upper layers (with the exception of the optional `tsch-rpl.[ch]`), and has been
also tested with Rime (currently only with 64-bit link-layer addresses).
## Code structure
The IEEE 802.15.4e-2012 frame format is implemented in:
* `os/net/mac/frame802154.[ch]`: handling of frame version 2
* `os/net/mac/frame802154-ie.[ch]`: handling of Information Elements
TSCH is implemented in:
* `os/net/mac/tsch/tsch.[ch]`: TSCH management (association, keep-alive), processes handling pending
outgoing and incoming packets, and interface with Contiki's upper layers as a MAC driver. TSCH does not
require a RDC (nordc is recommended).
* `tsch-slot-operation.[ch]`: TSCH low-level slot operation, fully interrupt-driven. Node wake up at every active
slot (according to the slotframes and links installed), transmit or receive frames and ACKs. Received packets are
stored in a ringbuf for latter upper-layer processing. Outgoing packets that are dequeued (because acknowledged
or dropped) are stored in another ringbuf for upper-layer processing.
* `tsch-asn.h`: TSCH macros for Absolute Slot Number (ASN) handling.
* `tsch-packet.[ch]`: TSCH Enhanced ACK (EACK) and enhanced Beacon (EB) creation and parsing.
* `tsch-queue.[ch]`: TSCH per-neighbor queue, neighbor state, and CSMA-CA.
* `tsch-schedule.[ch]`: TSCH slotframe and link handling, and API for slotframe and link installation/removal.
* `tsch-security.[ch]`: TSCH security, i.e. securing frames and ACKs from interrupt with ASN as part of the Nonce.
Implements the 6TiSCH minimal configuration K1-K2 keys pair.
* `tsch-rpl.[ch]`: used for TSCH+RPL networks, to align TSCH and RPL states (preferred parent -> time source,
rank -> join priority) as defined in the 6TiSCH minimal configuration.
* `tsch-log.[ch]`: logging system for TSCH, including delayed messages for logging from slot operation interrupt.
* `tsch-adaptive-timesync.c`: used to learn the relative drift to the node's time source and automatically compensate for it.
Orchestra is implemented in:
* `apps/orchestra`: see `apps/orchestra/README.md` for more information.
## Using TSCH
A simple TSCH+RPL example is included under `examples/ipv6/rpl-tsch`.
To use TSCH, first make sure your platform supports it.
Currently, `jn516x`, `sky`, `z1`, `cc2538dk`, `zoul`, `openmote-cc2538`, `srf06-cc26xx`, and `cooja` are the supported platforms.
To add your own, we refer the reader to the next section.
To add TSCH to your application, configure the TSCH module from your makefile with:
`MAKE_MAC = MAKE_MAC_TSCH`
If you are running with RPL, it is recommended to enable the `tsch-rpl` module with:
```
/* TSCH and RPL callbacks */
#define RPL_CALLBACK_PARENT_SWITCH tsch_rpl_callback_parent_switch
#define RPL_CALLBACK_NEW_DIO_INTERVAL tsch_rpl_callback_new_dio_interval
#define TSCH_CALLBACK_JOINING_NETWORK tsch_rpl_callback_joining_network
#define TSCH_CALLBACK_LEAVING_NETWORK tsch_rpl_callback_leaving_network
```
To configure TSCH, see the macros in `.h` files under `os/net/mac/tsch/` and redefine your own in your `project-conf.h`.
## Using TSCH with Security
To include TSCH standard-compliant security, set the following:
```
/* Enable security */
#undef LLSEC802154_CONF_ENABLED
#define LLSEC802154_CONF_ENABLED 1
/* TSCH uses explicit keys to identify k1 and k2 */
#undef LLSEC802154_CONF_USES_EXPLICIT_KEYS
#define LLSEC802154_CONF_USES_EXPLICIT_KEYS 1
/* TSCH uses the ASN rather than frame counter to construct the Nonce */
#undef LLSEC802154_CONF_USES_FRAME_COUNTER
#define LLSEC802154_CONF_USES_FRAME_COUNTER 0
```
The keys can be configured in `os/net/mac/tsch/tsch-security.h`.
Nodes handle security level and keys dynamically, i.e. as specified by the incoming frame header rather that compile-time defined.
By default, when including security, the PAN coordinator will transmit secured EBs.
Use `tsch_set_pan_secured` to explicitly ask the coordinator to secure EBs or not.
When associating, nodes with security included can join both secured or non-secured networks.
Set `TSCH_CONF_JOIN_SECURED_ONLY` to force joining secured networks only.
Likewise, set `TSCH_JOIN_MY_PANID_ONLY` to force joining networks with a specific PANID only.
## TSCH Scheduling
By default (see `TSCH_SCHEDULE_WITH_6TISCH_MINIMAL`), our implementation runs a 6TiSCH minimal schedule, which emulates an always-on link on top of TSCH.
The schedule consists in a single shared slot for all transmissions and receptions, in a slotframe of length `TSCH_SCHEDULE_DEFAULT_LENGTH`.
As an alternative, we provide Orchestra (under `os/services/orchestra`), an autonomous scheduling solution for TSCH where nodes maintain their own schedule locally, solely based on their local RPL state.
Orchestra can be simply enabled and should work out-of-the-box with its default settings as long as RPL is also enabled.
See `apps/orchestra/README.md` for more information.
Finally, one can also implement his own scheduler, centralized or distributed, based on the scheduling API provides in `os/net/mac/tsch/tsch-schedule.h`.
## Porting TSCH to a new platform
Porting TSCH to a new platform requires a few new features in the radio driver, a number of timing-related configuration paramters.
The easiest is probably to start from one of the existing port: `jn516x`, `sky`, `z1`, `cc2538dk`, `zoul`, `openmote-cc2538`, `srf06-cc26xx`.
### Radio features required for TSCH
The main new feature required for TSCH is the so-called *poll mode*, a new Rx mode for Contiki radio drivers.
In poll mode, radio interrupts are disabled, and the radio driver never calls upper layers.
Instead, TSCH will poll the driver for incoming packets, from interrupt, exactly when it expects one.
TSCH will check when initializing (in `tsch_init`) that the radio driver supports all required features, namely:
* get and set Rx mode (`RADIO_PARAM_RX_MODE`) as follows:
* disable address filtering with `RADIO_RX_MODE_ADDRESS_FILTER`
* disable auto-ack with `RADIO_RX_MODE_AUTOACK`
* enable poll mode with `RADIO_RX_MODE_POLL_MODE`
* get and set Tx mode (`RADIO_PARAM_TX_MODE`) as follows:
* disable CCA-before-sending with `RADIO_TX_MODE_SEND_ON_CCA`
* set radio channel with `RADIO_PARAM_CHANNEL`
* get last packet timestamp with `RADIO_PARAM_LAST_PACKET_TIMESTAMP`
* optionally: get last packet RSSI with `RADIO_PARAM_LAST_RSSI`
* optionally: get last packet LQI with `RADIO_PARAM_LAST_LQI`
### Timing macros required for TSCH
The following macros must be provided:
* `US_TO_RTIMERTICKS(US)`: converts micro-seconds to rtimer ticks
* `RTIMERTICKS_TO_US(T)`: converts rtimer ticks to micro-seconds
* `RADIO_DELAY_BEFORE_TX`: the delay between radio Tx request and SFD sent, in rtimer ticks
* `RADIO_DELAY_BEFORE_RX`: the delay between radio Rx request and start listening, in rtimer ticks
* optionally, `TSCH_CONF_DEFAULT_TIMESLOT_LENGTH`: the default TSCH timeslot length, useful i.e. for platforms
too slow for the default 10ms timeslots.
## Additional documentation
1. [IEEE 802.15.4e-2012 ammendment][ieee802.15.4e-2012]
2. [IETF 6TiSCH Working Group][ietf-6tisch-wg]
3. [A test procedure for Contiki timers in TSCH][tsch-sync-test]
[ieee802.15.4e-2012]: http://standards.ieee.org/getieee802/download/802.15.4e-2012.pdf
[ietf-6tisch-wg]: https://datatracker.ietf.org/wg/6tisch
[tsch-sync-test]: https://github.com/abbypjoby/Contiki-Synchronisation-Test

103
os/net/mac/tsch/sixtop/README.md
View File

@ -1,103 +0,0 @@
# [EXPERIMENTAL] 6TiSCH Operation Sublayer (6top)
## Overview
6TiSCH Operation Sublayer (6top), a logical link layer in the 6TiSCH
architecture, provides the abstraction of an IP link over a TSCH MAC layer (IEEE
802.15.4e). The functionality of 6top is to facilitate the dynamic cell
negotiation with one-hop neighbors.
This is a Contiki implementation of 6top, developed by:
- Shalu R, CDAC, shalur@cdac.in, github user: [shalurajendran](https://github.com/shalurajendran)
- Lijo Thomas, CDAC, lijo@cdac.in
- Yasuyuki Tanaka
It supports 6P (6top Protocol) of [draft-03](draft-ietf-6tisch-6top-protocol-03)
except for concurrent 6P transactions described in [Section
4.3.3](https://tools.ietf.org/html/draft-ietf-6tisch-6top-protocol-03#section-4.3.3).
## Code Structure
| File | Contents |
|-----------------|--------------------------------|
| sixtop.[ch] | 6top external APIs |
| sixp.[ch] | 6P I/O APIs |
| sixp-nbr.[ch] | 6P Neighbor Management APIs |
| sixp-pkt.[ch] | 6P Packet Manipulation APIs |
| sixp-trans.[ch] | 6P Transaction Management APIs |
| sixp-conf.h | 6P Configuration Parameters |
## Configuration Paramters
| Parameter | Meaning | Default Value |
|--------------------------------------|----------------------------------------------|---------------|
| SIXTOP_CONF_MAX_SCHEDULING_FUNCTIONS | The maximum number of SFs installed in 6top | 1 |
| SIXTOP_CONF_MAX_TRANSACTIONS | The maximum number of transactions at a time | 1 |
## Caveat
At this moment, allocated 6P neighbor states never be deleted since 6P has no
way to decide to delete them. 6P neighbor state consists of SeqNum to be used
for a next reqeust, GTX, and GRX (defined in sixp-nbr.c).
Once the number of 6P neighbor states reaches to the `SIXTOP_6P_MAX_NEIGHBORS`,
a transaction with a new neighbor may fail due to failure in allocating a 6P
neighbor state or schedule generation inconsistency.
## Example
An example using 6top is provided under `examples/ipv6/rpl-tsch-sxitop/`.
A simple Scheduling Function (SF) is implemented in `sf-simple.[ch]`. This SF
does not have bandwidth monitoring mechanism nor bandwidth adaptation
mechanism. Instead, the SF provides APIs so that a user process can add or
remove cells dynamically. A sample user process implementation using the SF is
found in `node-sixtop.c`, which is tested with `rpl-tsch-sixtop-z1.csc`.
## Test
6top or 6P related tests are implemented under `regression-tests/26-6tisch`.
## Using 6top
In order to use 6top with your system, `sixtop` module must be built together in
addition to [TSCH](../).
Enable TSCH, then set 1 to `TSCH_CONF_WITH_SIXTOP`, typically, in your
`project-conf.h`:
```C
#undef TSCH_CONF_WITH_SIXTOP
#define TSCH_CONF_WITH_SIXTOP 1
```
Next, add `sixtop` into `MODULES` in your Makefile:
```Makefile
MODULES += core/net/mac/tsch/sixtop
```
For now, the simple SF mentioned above is only one SF shipped in the code
base. You may have to implement your own SF.
## Implementing a Scheduling Function
Scheduling Function (SF) is represented with `sixtop_sf_t`, which defined in
`sixtop.h`. An SF can be added into 6top by `sixtop_add_sf()`. After the
addition, a handler defined in `sixtop_sf_t` is invoked on a correspondent
event, for example, reception of a 6P request or timeout of an ongoing
transaction.
SF can send a 6P packet by `sixp_output()`. After every Add or Delete operation,
SF needs to advance schedule generation counter associated with the peer by
`sixp_advance_generation()`, counter which is maintaeind by 6P. Otherwise, SF
will not able to perform any command request other than Clear due to schedule
generation inconsistency.
## References
1. [IETF 6TiSCH Working Group](https://datatracker.ietf.org/wg/6tisch)
2. [6top Protocol (6P)](https://tools.ietf.org/html/draft-ietf-6tisch-6top-protocol)

29
os/services/ip64/README.md
View File

@ -1,29 +0,0 @@
The `ip64` module lets an IPv6 Contiki network be connected to an IPv4
network without any additional configuration or outside software. The
`ip64` module runs on the RPL root node and translates outgoing IPv6
packets into IPv4 packets nd incoming IPv4 packets to IPv6 packets.
The `ip64` module uses stateful NAT64 (RFC6164) to do the packet
translation and DNS64 (RFC6147) to catch DNS requests for IPv6
addresses, turn them into requests for IPv4 addresses, and turn the
replies into responses for IPv6 addresses. This allows devices on the
inside IPv6 network to connect to named servers on the outside IPv4
network.
The `ip64` module hooks into the IPv6 stack via a fallback
interface. Any packet that can not be routed into the local RPL mesh
will be sent over the fallback interface, where `ip64` picks it up,
translates it into an IPv4 packet, and sends it over its outgoing
interface.
In addition to providing NAT64 and DNS64 services, the `ip64` module
also performs DHCPv4 to request IPv4 address for devices connected to
a medium such as Ethernet. The `ip64` module also performs ARP
processing to communicate over the Ethernet.
The `ip64` module uses a configuration file called `ip64-conf.h` that
specifies what device to use for the IPv4 network. This file is
intended to be placed in the platform directory. An example
configuration file called `ip64-conf-example.h` is provided in this
directory.

51
os/services/orchestra/README.md
View File

@ -1,51 +0,0 @@
# Orchestra
## Overview
Orchestra is an autonomous scheduling solution for TSCH, where nodes maintain
their own schedule solely based on their local RPL state. There is no centralized
scheduler nor negociatoin with neighbors, i.e. no traffic overhead. The default
Orchestra rules can be used out-of-box in any RPL network, reducing contention
to a low level. Orchestra is described and evaluated in
[*Orchestra: Robust Mesh Networks Through Autonomously Scheduled TSCH*](http://www.simonduquennoy.net/papers/duquennoy15orchestra.pdf), ACM SenSys'15.
## Requirements
Orchestra requires a system running TSCH and RPL.
For sender-based unicast slots (`ORCHESTRA_UNICAST_SENDER_BASED`), it requires
RPL with downwards routing enabled (relies on DAO).
## Getting Started
To use Orchestra, add a couple global definitions, e.g in your `project-conf.h` file.
Disable 6TiSCH minimal schedule:
`#define TSCH_SCHEDULE_CONF_WITH_6TISCH_MINIMAL 0`
Enable TSCH link selector (allows Orchestra to assign TSCH links to outgoing packets):
`#define TSCH_CONF_WITH_LINK_SELECTOR 1`
Set up the following callbacks:
```
#define TSCH_CALLBACK_NEW_TIME_SOURCE orchestra_callback_new_time_source
#define TSCH_CALLBACK_PACKET_READY orchestra_callback_packet_ready
#define NETSTACK_CONF_ROUTING_NEIGHBOR_ADDED_CALLBACK orchestra_callback_child_added
#define NETSTACK_CONF_ROUTING_NEIGHBOR_REMOVED_CALLBACK orchestra_callback_child_removed
```
To use Orchestra, fist add it to your makefile `APPS` with `APPS += orchestra`.
Finally:
* add Orchestra to your makefile `APPS` with `APPS += orchestra`;
* start Orchestra by calling `orchestra_init()` from your application, after
including `#include "orchestra.h"`.
## Configuration
Orchestra comes with a number of pre-installed rules, `orchestra-rule-*.c`.
You can define your own by using any of these as a template.
A default Orchestra configuration is described in `orchestra-conf.h`, define your own
`ORCHESTRA_CONF_*` macros to override modify the rule set and change rules configuration.

6
tests/00-doxygen/Makefile
View File

@ -30,14 +30,14 @@ DOCDIR=../../doc
all: summary
doxygen:
@make -C $(DOCDIR) doxygen.log 2> doxygen.runerr > doxygen.runlog
@make -C $(DOCDIR) 2> doxygen.runerr > doxygen.runlog
summary: doxygen
@( \
1> summary; \
if [ -s doxygen.runerr ] ; then \
echo "doxygen: FAIL ಠ_ಠ\nDoxygen caused some runtime warnings. Please fix these." >> summary; \
echo "Runtime warnings:" >> summary; \
echo "doxygen: FAIL ಠ_ಠ\nDoxygen caused some errors. Please fix these." >> summary; \
echo "Errors:" >> summary; \
cat doxygen.runerr >> summary; \
echo >> summary; \
fi ; \