Read Me

########################### Simple Wireless #############################

Simple Wireless (SW) is a simple Arduino library that implements 
some useful data-link layer functions for simple wireless communications 
using the VirtualWire library and some inexpensive transmitter/receiver
or transceiver modules. The main functions provided are node addressing 
and service multiplexing/demultiplexing.

Copyright (C) 2010  Alessandro Paganelli (alessandro_paganelli@libero.it)

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.


1 - INTRODUCTION

Simple wireless is an Arduino library that aims to extending the capabilities
provided by the VirtualWire library with (currently): 

- node addressing 
- service multiplexing

Simple Wireless can be considered as a data-link protocol which uses VirtualWire
as the physical layer.


2 - INSTALLATION

Simple Wireless can be installed by moving this directory inside the "libraries"
subdirectory under the Arduino's IDE root.
It requires the inclusion of the VirtualWire library, by Mike McCauley 
inside your sketch.
VirtualWire can be found at: www.open.com.au/mikem/arduino/ .


3 - FRAME STRUCTURE

The current frame structure (v. 0.1) is:

------------------------------------------------------------------------------
| Protocol id | Dest. Address | Src. Address | Service id | Length | Payload |
------------------------------------------------------------------------------

The frame's fields are:

- Protocol id (1 byte): this identifier, defined as the _PROTOCOL_ID macro in 
	simple_wireless.h is used to identify the starting byte of the frame.
- Destination address (1 byte): the destination node's address.
- Source address (1 byte): the source node's address.
- Service id (1 byte): the identification of the service, in order to mux/demux
	different services on a single Arduino node.
- Length (1 byte): the length of the payload (in byte). The macros _MIN_PAYLOAD_LENGTH
	and _MAX_PAYLOAD_LENGTH, defined in simple_wireless.h, are used to define
	the minimum and the maximum length of the payload. Note that the packet 
	generated will always have a fixed length, regardless the actual length
	of the data passed through the Simple Wireless' interface; if data length
	is less than _MAX_PAYLOAD_LENGTH bytes, then the remaining bytes to 
	_MAX_PAYLOAD_LENGTH will be padded with the byte defined as _PADDING_BYTE
	inside simple_wireless.h.
- Payload (max _MAX_PAYLOAD_LENGTH byte): the service's data.


4 - SIMPLE WIRELESS DATA TYPES

Simple wireless introduces the sw_dataUnit data type to simplify the use of 
the library. The sw_dataUnit is a data structure used to encapsulate 
together with the payload other transmission related information.
The sw_dataUnit is, thus, the basic structure used for transmission and reception.
It contains the following attributes:

- byte address: the destination node's address;
- byte service: the service used for the transmission;
- byte length: the payload's length;
- byte data[_MAX_PAYLOAD_LENGTH]: the byte array of the service's data.

During the transmission phase, the sw_dataUnit needs to be defined and filled
before the actual transmission, while in the receiving phase, the sw_dataUnit
is filled by the receiving routine (see the next sections for an explanation of
the methods used in the transmission and/or in the reception phases).


5 - SIMPLE WIRELESS CLASSES

The Simple Wireless library provides four classes:

- sw_node, which is the father of the sw_transmitter and the sw_receiver
	classes.
- sw_transmitter, which can be used to implement a simple transmitter (one-way 
	transmission, no receiving functions).
- sw_receiver, which can be used to implement a simple receiver (one-way, no 
	transmission functions).
- sw_transceiver, which can be used to implement a two-way transceiver.


5.1 - SW_NODE CLASS

The sw_node class has a protected attribute, localAddress, which is the address of the node.
Moreover it has the following two public methods:

- bool sw_node::setSpeed(uint16_t speed), which is used to set the transmission speed in bit-per-second.
- bool sw_node::setLocalAddress(byte localAddress), which is used to set the node's address.

Both return true.


5.2 - SW_TRANSMSMITTER CLASS

The sw_transmitter class inherits all the methods and attributes of the sw_node class.
It also adds the following public methods:

- bool sw_transmitter::setTxPin(byte txPin), which is used to set the transmission pin on the Arduino.
- bool sw_transmitter::transmit(sw_dataUnit &dataUnit), which is used to transmit the dataUnit. 
	Note that dataUnit needs to be defined before the the invocation of the transmit
	method.

Both return true.


5.3 - SW_RECEIVER CLASS

The sw_receiver class inherits all the methods and attributes of the sw_node class.
It also adds the following public methods:

- bool sw_receiver::setRxPin(byte rxPin), which is used to set the receiving pin on the Arduino. It
	returns true.
- bool sw_receiver::receive(sw_dataUnit &dataUnit), which is a blocking function used to put the Arduino
	in receiving mode. When a frame will be received, the function will return and the dataUnit parameter
	will contain all the data extracted from the frame. It returns true if a frame has been received.
- bool sw_receiver::receive(sw_dataUnit &dataUnit, unsigned long timeout), which is a blocking function similar
	to the previous one, except from the additional parameter "timeout", which is used to specify the 
	maximum timeout for the receiving phase. In this way, the receving function takes no longer than
	timeout milliseconds. If the timeout has been reached without receiving a frame, the function
	returns false; otherwise it returns true.


5.4 - SW_TRANSCEIVER CLASS

The sw_transceiver class inherits all the methods and attributes of both the sw_transmitter and sw_receiver
classes and can be used with transceiver modules.


6 - EXAMPLES OF USAGE

These examples can be found in the examples/ subdirectory. 

6.1 - Simple Transmitter

/*
A simple sketch that implements a transmitter, using Simple Wireless and 
VirtualWire libraries, which transmits a given message every 2 seconds.
*/

#include <simple_wireless.h>
#include <VirtualWire.h>
#include <string.h>

/* declaration of the a transmitter object */
sw_transmitter tx;

/* declaration of the data unit to be used for communications */
sw_dataUnit aDataUnit;

char message[] = "AAAAA"; // 5 chars, less than the max payload length!

void setup(){
  Serial.begin(9600);
  Serial.println("Entering Setup function");

  pinMode(2, INPUT);
  tx.setSpeed(2000);
  tx.setLocalAddress(0x01);
  tx.setTxPin(12);

  Serial.println("Quitting Setup function");
}

void loop(){

  /* Filling the data unit with the correct parameters*/
  aDataUnit.address = 0x02;
  aDataUnit.service = 0x01;
  aDataUnit.length = strlen(message);

  /* Filling the data unit with the payload */
  memcpy((byte*) aDataUnit.data, (byte*) message, aDataUnit.length);

  tx.transmit(aDataUnit);
  delay(2000);
}


6.2 - Simple Receiver

/* 
A simple sketch that implements a blocking receiver, using Simple Wireless and 
VirtualWire libraries. When a frame is available, the program prints over the
serial port the data extracted from it.
*/

#include <simple_wireless.h>
#include <VirtualWire.h>
#include <string.h>

/* declaration of the receiver object */
sw_receiver rx;

/* declaration of the data unit to be used for communications */
sw_dataUnit aDataUnit;

void setup(){
  Serial.begin(9600);
  Serial.println("Entering Setup function");
  
  rx.setSpeed(2000);
  rx.setLocalAddress(0x02);
  rx.setRxPin(11);
  
  Serial.println("Quitting Setup function");
}

void loop(){
  rx.receive(aDataUnit);
    
  /* print over the serial port the data extracted from the received
     frame.
  */
  Serial.print("Foreign Address: ");
  Serial.println(aDataUnit.address, DEC);

  Serial.print("Service: ");
  Serial.println(aDataUnit.service, DEC);

  Serial.print("Length: ");
  Serial.println(aDataUnit.length, DEC);

  Serial.print("Data: ");
  
  for(int i=0; i< aDataUnit.length; i++){
    Serial.print(aDataUnit.data[i], DEC);
    Serial.print(" ");
  }
  Serial.println("");

}