YWasp
(c) 2011-2012 Stefan Wendler
sw@kaltpost.de
http://gpio.kaltpost.de/

Nordic nRF24l01+ Serial-2-Air Gateway
=====================================


Introduction
------------

YWasp is a firmware for "airifaying" a serial line over an Nordic nRF24l01+ module. To use YWasp, beside the RF module a MUC (currently the ARM-Cortex-M3 based STM32F100 and STM32F103 and the MSP430G2553 are supported) is needed. Depending on what you connect to the serial "side" of the YWasp, you may also need an USB to TTL serial converter (FTDI etc.). 

YWasp currently only supports point-to-point connections. A client and a server YWasp instance could be coupled, and everythin that is written to the serial line of one YWasp is transmitted to the YWasp pear. On the pear, it is written back on the serial interface again. 

Communication is bidirectional, and from a users point of view, there is no difference between the client and the server. The fact, that one YWasp has to be configured as client, and the other one as server is due to the fact, that the Nordic modules operate either in PTX (primary TX) or PRX (primary RX) mode. To avoid switching each device continuously between PTX and PRX mode, the RF modules are configured into ESB (Enhanced Shock Burst) with ACK payload. Thus, the server continuously sends a package to the client (with data or a NOP package), and the client replays with a ACK pckage (with data or a NOP package).   

A scenario with two YWasp devices connecting the serial ports of two PCs is shown below:

               +--------+                            +--------+
               |  YWasp | --- TX (data | NOP) RX --> |  YWasp |
< RX/TX UART > | SERVER |                            | CLIENT | < RX/TX UART > 
               |   PTX  | <-- RX (data | NOP) TX --- |   PRX  |
               +--------+                            +--------+

Since YWasp is based on "libnrf24l01" from "libemb", one could easly embed a YWasp client based on "libnrf24l01" into an existing MCU project to allow remote access from a PC through a YWasp server instance. E.g. one could offer a remote shell to an robot: 

               +--------+                            +--------+
               |  YWasp | --- TX (data | NOP) RX --> |  ROBOT |
< RX/TX UART > | SERVER |                            | YWasp  | 
               |   PTX  | <-- RX (data | NOP) TX --- | CLIENT |
               +--------+                            +--------+

YWasp is not intended (yet) for collecting data of e.g. multible sensors etc. It does no meshing or other fancy stuff. If you need this, you may consider using XBee or similar. 

Usage
-----

For detailed usage examples etc. visit the project homepage at http://gpio.kaltpost.de/?page_id=748


Hardware
-----------------

For how to setup a YWasp hardware which could be used as server or client, see the schematics under "doc/schematic". There you will find an example based on the STM32VL Discovery board and the TI Launchpad with an MSP430G2553. The IFLAT-32 board from ITead comes with a socket ready to plug in the nRF24l01. YWasp is compatible with IFLAT-32 and will work out of of the box with this board (you have to add the LEDs and jumpers for signaling and configuration).
 

* BOM STM32 *

For each YWasp instance the following parts are needed:

Qty.    Part
--------------------------------------
1       STM32 (e.g. STM32VL Discovery)
1       Nordic nRF24l01+
5       LEDs (D1..5)
5       Resistors (R1..R5)
4       1x2 male headers (J1..3, VDD)
4       Jumper bridges (J1..3, VDD)
1       1x7 female headers (JTAG)
1       1x4 male headers (UART)
1		(optional) Serial to USB converter

* BOM TI Launchpad *

For each YWasp instance the following parts are needed:

Qty.    Part
--------------------------------------
1      	TI Launchpad + MSP430G2553 
1       Nordic nRF24l01+
5       LEDs (D1..3)
5       Resistors (R1..R3)
3       1x2 male headers (J1..3)
3       Jumper bridges (J1..3)
 

* Configuration *

Configruation is done through three jumpers which are read in by the firmware on startup:

Selecting client or server mode:

J1              Function
--------------------------------------------
open            client mode	
closed          server mode	

Selecting the address: 

Each YWasp could be configured to use one of four predefined adresses through jumpers J2 and J3.

J2          J3          Function
--------------------------------------------
open        open        select address 0
open        closed      select address 1
closed      open        select address 2
closed      closed      select address 3

Note: the same address on the client and server has to be selected for a successfull point-to-point connection.

The sample schematic additionaly has a jumper VDD which, if closed, connects the 3.3V power supply form a USB to serial converter to the MCU.


* Status LEDs STM32 *

For status information, the YWasp drives 5 LEDs:

LED         On indicates
--------------------------------------------
D1          Client connected (server only)
D2          TX activity			
D3          RX activity
D4          Client mode			
D5          Server mode


* Status LEDs MSP430 *

For status information, the YWasp drives 5 LEDs:

LED         On indicates
--------------------------------------------
D1          Client connected (server only)
D2          RX/TXTX activity			
D3          Server mode

Note: The jumpers and the signaling LEDs are optional. If you leave them out, the YWasp will configure itself in client mode with address 0.
 

* UART STM32 *

YWasp uses a 3 line UART (RX, TX, GND) with an optional 4th line for 3.3v power supply (if jumper VDD is connected). 

* UART MSP430 *

When using the Launchpad, the build in serial to USB converter could be used. The UART then could be accesd through inteface "/dev/ttyACM0" on Linux. Be aware of the fact, that you have to cross RX/TX lines on the Launchpads jumper bridge for the MSP430G2553!

* Mini JTAGi STM32 *

The sample schematic also includes a mini JTAG interface which is compatible with the IFLAT-32 board (and the X-Link JTAG). If you use something else then JTAG for flashing, you will not need the JTAG connector.


Supported Targets
-----------------

Currently the following ARM-Cortex-M3 targets are supported:

* STM32F100 (tested on the STM32VL Discovery)
* STM32F103 (tested on the IFLAT-32)

And the following MSP430 targets are supported:

* MSP430G2553 (tested on TI Launchpad)

MCU/hardware specific stuff is clearly seperated from the rest, so porting to a different target (or base library) should not be a big deal.


Compilation
------------

"YWasp" depends on "libemb".  The compilation steps described here assume, that you installed "libemb" for your target platform.  

For STM32, it is further assumed you installed the "summon-arm-toolchain", located in its default location "~/sat". 

For MSP430, it is assumed you have installed a working msp430-gcc along with ths mspdebug tool (newer Ubuntu distributions provide packages for both).

To compile YWasp, change to the toplevel directory "ywasp" and issue:

for the STM32F100 as target:

TARCH=STM32_100 make

or for the STM32F103 as target:

TARCH=STM32_103 make

or for the MSP430 as target:

TARCH=MSP430 make

This will produce the firmware binary in various formats in the "bin" subdirectory.


Installation
------------

To instal the "ywasp.h" header (to use the constants in embedded clients) to the default location which is "$HOME/sat/arm-none-eabi/inlucde" for STM32 and "$HOME/msp430/include" for the MSP430, type the following:

for the STM32F100 as target:

TARCH=STM32_100 make install

for the STM32F103 as target:

TARCH=STM32_103 make install

for the MSP430 as target:

TARCH=MSP430 make install

If yout don't like that location specify a different one by setting "INSTDIR":

INSTDIR=[your-location] TARCH=[your target] make install


Flashing
------------

This highly depends on the programmer you use. For an OpenOCD supported programmer, the variable "OOCD_IF" could be set to the OOC interface configuration of your programmer.  E.g. if you use the "flyswatter", flashing could be done by issuing the following command: 

OOCD_IF=interface/flyswatter.cfg make flash-target

For the MSP430 target on a Launchpad, the "mspdebug" tool is used for flashing. 

Doxygen Docs
------------

If you installed doxygen on your system, you could generate the HTML-based API documentation by calling:

make gen-docs

This will create the API documentation under "doc/gen/html".


Tailor to a Different Environment
---------------------------------

If you use a different compiler etc., you could change the settings in the "common.mk" file which is located in the top-level directory of "ywasp".

To adjust YWasp or nNRF24l01 settings, have a look intor "src/include/ywasp.h".