SWAP API

The SWAP (Simple Abstract Wireless Protocol) API is implemented in a separate library located in libraries/swap/. This API provides a set of classes and methods to interface with the SWAP communication stack without having to deal with low-level communication tasks and protocol details.

Using SWAP in your application leads you to understanding what SWAP registers are and how to declare them. Registers are the core of the SWAP protocol. Every wireless packet makes reference to a specific register in the node so this API makes extensive use of registers.

This API relies on the swap object, automatically instantiated from the SWAP class. The following is a list of methods provided by this class:

• init
• enterSystemState
• goToSleep
• nvolatToFactoryDefaults
• attachInterrupt
• enableRepeater
• getRegister
• setAesPassword
• enableAntiPlayback

You will notice that the SWAP class does not provide any method to transmit or receive SWAP packets. This is in fact REGISTER class' "honor". However, if a device needs to send commands or queries to another device then SWCOMMAND and SWQUERY can be used.

---

init

void init(void)

Description

Initialize SWAP registers and communication settings

Example

#include "swap.h"

void setup()
{
  swap.init()
  ...
}

---

enterSystemState

void enterSystemState(SYSTATE state)

Description

Enter and communicate system state.

Parameters

state : system state.

Options:

• SYSTATE_RESTART : Restart node
• SYSTATE_RXON : Node with RF reception enabled (not sleeping)
• SYSTATE_RXOFF : Node with RF reception disabled (probably sleeping)
• SYSTATE_SYNC : Node momentarily in synchronization mode, with RF reception enabled
• SYSTATE_LOWBAT : Low-battery state. This mode needs to be handled from user application
• SYSTATE_UPGRADE : Node in firmware upgrade mode

Example

// Enter SYNC state and transmit SWAP status packet
swap.enterSystemState(SYSTATE_SYNC);

// During 3 seconds, listen the network for possible commands whilst the LED blinks
for(i=0 ; i<6 ; i++)
{
  digitalWrite(LED, HIGH);
  delay(100);
  digitalWrite(LED, LOW);
  delay(400);
}

// Switch to Rx OFF state and transmit SWAP status packet
swap.enterSystemState(SYSTATE_RXOFF);

---

goToSleep

void goToSleep(void)

Description

Put the module in sleep mode during swap.txInterval seconds. swap.txInterval is represented by register number 10 (register ID = 10) so this value can be changed wirelessly.

Parameters

None.

Example

void loop()
{
  swap.getRegister(REGI_SENSOR)->getData();  // Update sensor data and transmit SWAP status
  swap.goToSleep();  // Sleep for swap.txInterval seconds
}

---

nvolatToFactoryDefaults

void nvolatToFactoryDefaults(void)

Description

Write default config values in non-volatile memory (infomem flash or EEPROM).

Parameters

None

Example

void setup()
{
  swap.nvolatToFactoryDefaults();
  swap.init();
}

---

attachInterrupt

void attachInterrupt(uint8_t type, void (*funct)(SWPACKET*))

Description

Declare custom ISR, to be called whenever a SWAP status is received

Parameters

type : type of SWAP packet that triggers the call to the user function. STATUS is the only option so far.

funct : pointer to the custom callback function.

Example

/**
 * swapStatusReceived
 *
 * Function automatically called by the panStamp API whenever a SWAP status
 * packet is received
 *
 * 'status'    SWAP status packet received
 */
void swapStatusReceived(SWPACKET *status)
{
  // status->regId  Register ID
  // status->srcAddr Source address
  // status->value.length Length of data field
  // status->value.data Array of data bytes
}

/**
 * Arduino's setup function
 */
void setup() 	 
{
  // Init panStamp
  //panstamp.init(CFREQ_868);  // Not necessary unless you want a different frequency

  // Init SWAP stack
  swap.init();
  
  // Declare callback function for dispatching incoming SWAP status packets
  swap.attachInterrupt(STATUS, swapStatusReceived);
}

---

enableRepeater

void enableRepeater(uint8_t maxHop)

Description

Enable repeater mode. This mode needs the node to be continuously listening the wireless network.

Parameters

maxHop : maximum number of times that a packet can be repeated.

Example

// Enable repeater mode. Maximum hop count = 3
swap.enableRepeater(3);

---

getRegister

REGISTER * getRegister(uint8_t regId)

Description

getRegister returns the register with the ID passed as argument.

Parameters

regId : register ID

Example

void loop()
{
  // Update and transmit sensor data
  swap.getRegister(REGI_SENSOR)->getData();

  // Sleep
  swap.goToSleep();
}

---

setAesPassword

void setAesPassword(unsigned char* password)

Description

Set AES 128-bit key for the next encryptions and decryptions. Only available for the NRG platform. Once the AES key is entered, all SWAP packets are encrypted before transmission and decrypted after reception.

Parameters

password : Pointer to a 16-byte array containing the AES key

Example

  // AES-128 encryption (for NRG only)
  byte aesKey[] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F};  
  swap.setAesPassword(aesKey);

enableAntiPlayback

void enableAntiPlayback(void)

Description

Enables anti-playback security (bit 0 from the security field). With this option enabled, packets received not matching the current nonce value in the receiver are automatically discarded.

Example

  // Enable anti-playback protection
  swap.enableAntiPlayback();