Skip to content

panStamp API

Jump to bottom Edit New page
Alex edited this page Feb 27, 2020 · 66 revisions

This is the API containing all basic core and radio functions. PANSTAMP is the main class and an object of this class, called panstamp, is automatically instantiated by the IDE. We need to point out that this API, the PANSTAMP class and the panstamp object do not implement SWAP or any other wireless protocol. The following list shows the methods provided by this object:

Core functions

Radio functions

basicradio and basicbeacon are good examples showing the use of the panstamp API.

Core functions

These functions (methods) are available from the panstamp object. They are primarily related to the power management and initialization of the module.

init

void init(uint8_t freq) //deprecated in API 2.0

Description

Initialize board and peripherals. This method is automatically called by Arduino so you don't have to do it unless you want to set a center frequency different than 868 MHz. This method is deprecated as of the new API 2.0 and Carrier Frequency should only be changed in "panstamp.h" or use panstamp.radio.setCarrierFreq(CFREQ_915);

Parameters

freq : carrier frequency (CFREQ_868, CFREQ_915, CFREQ_433, CFREQ_918). Default frequency is CFREQ_868 if the value is omitted.

Example

panstamp.init(CFREQ_915);  // Init panStamp at 915 MHz as the center frequency

reset

void reset(void)

Description

Restart panStamp board

Parameters

None

Example

panstamp.reset();  // Restart module

rxOn

void rxOn(void)

Description

Enable RF reception. Reception is enabled by default. This method is rarely used since radio.sendData() and radio.receiveData() already handle this option by themselves.

Parameters

None

Example

panstamp.rxOn();  // RF reception enabled

rxOff

void rxOff(void)

Description

Disable RF reception. This will avoid the MCU being interrupted on each wireless packet received. This method is rarely used since radio.sendData() and radio.receiveData() already handle this option by themselves.

Parameters

None

Example

panstamp.rxOff();  // RF reception disabled

sleep

void sleep(void)

Description

Enter sleep mode forever. Only a pin interrupt can wake-up the module and no RF packet can wake the module. A fix should be on the way involving Wake-on-Radio state. This mode is the one with the lowest current consumption (under 1 uA). After waking-up, the program continues with the following instruction after sleep(). This instruction can be typically called from loop(). Calling this function or any sleep related functions will (re)enable all interrupts.

Parameters

None

Example

panstamp.sleep();  // Enter sleep mode

sleepSec

void sleepSec(uint16_t time)

Description

Enter sleep mode for a given period of time. This mode is the one with the lowest current consumption (under 1 uA). After this period has elapsed, the module will automatically wake-up and continue with the following instruction. This instruction can be typically called from loop().

Parameters

time : Sleep time in seconds

Example

panstamp.sleepSec(5);  // Sleep 5 seconds

wakeUp

void wakeUp(void)

Description

Wake-up from the sleep mode. This function needs to be called from the ISR (Interrupt Service Routine) having interrupted the module from its sleeping state.

Example

void myISR()
{
  panstamp.wakeUp();
}

wirelessBoot

void enableWirelessBoot(bool ena)
void goToWirelessBoot(void)

Description

Enables or Disables the Wireless Bootloader functionality when the module starts as well as going in Wireless boot mode.

Parameters

ena : true for Enable or false for Disable. Switches the Wireless Bootloader.

Example

panstamp.enableWirelessBoot(true); //Enable wireless bootloader 
panstamp.goToWirelessBoot(); //Start wireless bootloader

attachInterrupt

inline void attachInterrupt(void (*funct)(CCPACKET*))

Description

Specifies a named Interrupt Service Routine (ISR) to call when a wireless packet is received. Replaces any previous function that was attached to the interrupt. This instruction allows declaring custom callback functions where to parse incoming packets from. Interrupts can originate from RF, Timer or pins (P1.x and P2.x only). See Low power mode for additional important notes.

Parameters

funct : callback function with the following prototype: void myISR(CCPACKET *packet), where packet is the wireless packet received.

Example

void myISR(CCPACKET *packet)
{
  // Do whatever we need with packet->data[], packet->length, packet->crc, packet->rssi and packet->lqi`
}
void setup()
{
  ...
  panstamp.attachInterrupt(myISR);  // Declare custom ISR
  ...
}

setHighTxPower

void setHighTxPower(void)

Description

Configure the module to always transmit in high-power mode (~ +10dBm) by changing the PATABLE value. This mode will provide longer communication distances but will increase the current consumed during transmissions.

Parameters

None

Example

panstamp.setHighTxPower();  // Enter high Tx power mode

setLowTxPower

void setLowTxPower(void)

Description

Configure the module to always transmit in low-power mode (~ 0dBm) by changing the PATABLE value. This mode provides shorter communication distances but guarantees a low current consumed during transmissions. This is the default Tx mode.

Parameters

None

Example

panstamp.setLowTxPower();  // Enter low Tx power mode

delayClockCycles

void delayClockCycles(uint16_t n)

Description

Creates a delay based on the MCU's clock cycle for fine precision timings. The source of the clock cycle is MCLK.

Parameters

n : 2-byte clock cycles to wait (2-byte hex number/65535 decimal number)

Example

panstamp.core.delayClockCycles(0xFFFF);  // 65535 clock cycles x f_MCLK = delay in sec

getVcc

uint16_t getVcc(void)

Description

Returns the voltage supply level (AVcc-Avss)/2 in millivolts. A12 can also be used instead.

Parameters

None

Example

unsigned int volt = panstamp.getVcc();
Serial.print("Voltage supply in millis : ");
Serial.println(volt);

getTemp

int getTemp(void)

Description

Returns the MCU/Ambient temperature (temp) in ºC. It's not the most accurate/stable way to measure ambient temperature, but it's there. Be advised that the measurement is very sensitive to voltage differences and reference switches.

Parameters

None

Example

unsigned int temp = panstamp.core.getTemp();
Serial.print("Temperature in degrees Celsius: ");
Serial.println(temp);

Example (more accurate)

int DegC = ((analogRead(A10) - 673) * 423) / 1024; //Celsius
int DegF = ((analogRead(A10) - 630) * 761) / 1024; //Fahrenheit
Serial.print("Internal MCU Temperature: "); 
Serial.print(DegC); Serial.println("*C"); //Replace with desired scale

Example (chip calibrated for 2.0V ref.)

//See chip datasheet for specific addresses. You may need to add or subtract degrees to calibrate even further.
#define CAL_ADC_20T30   *((uint16_t *)0x1A1E)
#define CAL_ADC_20T85   *((uint16_t *)0x1A20)
analogReference(INTERNAL2V0);
float cal_temp_20 = (analogRead(A10) - CAL_ADC_20T30)*((85.0 - 30.0)/(CAL_ADC_20T85 - CAL_ADC_20T30)) + 30.0;
Serial.print("Internal MCU Temperature: "); 
Serial.print(cal_temp_20); Serial.println(" *C"); //Celsius. Convert accordingly.

getUID

void getUID(uint8_t *buffer)

Description

Read Die Record from Device Descriptor memory and build UID. The UID comprises of: 4B:waferID + 2B:dieYpos + 2B:dieXpos

Parameters

*buffer: pointer to a variable where the value is stored (8-byte word)

Example (Complete UID)

Serial.print("Long UID: ");
  panstamp.core.getUID(my_uid); //Pass the UID to a variable called "my_uid"
  for (int i=0; i<=7; i++) { 
    char buf[16];
    sprintf(buf, "%.2X",my_uid[i]);  //Convert the UID in a nicely readable HEX format
    Serial.print(buf); Serial.print(" ");
  }
  Serial.println("");

Example (Short UID)

Serial.print(" Short UID: ");
Serial.println(panstamp.core.getShortUID()); //Last dieXpos byte

Radio functions

These functions (methods) are available from the radio object, owned by the panstamp object (panstamp.radio). This radio API manages everything related to RF communications (radio configurations, transmissions, receptions).

setChannel

void setChannel(uint8_t chnl)

Description

Configure RF channel. Typically from 0 to 9. Default value = 0.

Parameters

chnl : channel number (0..9)

Example

panstamp.radio.setChannel(0);   // Use channel 0

setCarrierFreq

void setCarrierFreq(uint8_t freq)

Description

Configure carrier frequency. Typically from CFREQ_433, CFREQ_868, CFREQ_915 and CFREQ_918. Default value = CFREQ_868.

Parameters

freq : frequency (CFREQ_433...CFREQ_918)

Example

panstamp.radio.setCarrierFreq(CFREQ_433);   // Use 433 Mhz frequency

setSyncWord

void setSyncWord(uint8_t *sync)
void setSyncWord(uint8_t syncH, uint8_t syncL)

Description

Configure RF synchronization word. This word can also be taken as a kind of network ID. Default value = 0xB547.

Parameters

sync : 2-byte synchronization word (2-byte array)

or

syncH : synchronization word. High byte

syncL : synchronization word. Low byte

Example

panstamp.radio.setSyncWord(0x12, 0x23);  // Sync word = 0x1223

setDevAddress

void setDevAddress(uint8_t addr)

Description

Set physical 1-byte device address for RF communications. If address check is enabled in the device then only packets addressed to our device or broadcasted (destination address = 0) will be received.

Parameters

addr : 1-byte device address (1..255). Address 0 is reserved for broadcasts.

Example

panstamp.radio.setDevAddress(21); // Device address = 21

setCCregs

void setCCregs(void)

Description

Reconfigure radio front-end. Take all values configured in the above steps and set every configuration register in the radio.

Parameters

None

Example

panstamp.radio.setCCregs()

setTxPowerAmp

panstamp.radio.setTxPowerAmp(paLevel);

Description

Set the Transmission Power Amplifier at a specific level. The default is 0x60 or setLowTxPower. Refer to the MCU's datasheet for optimal settings.

Parameters

paLevel : 1-byte Tx power level (1..255). Optimal levels for 868Mhz on CC430F5137: 0x03(-30dBm), 0x25(-12dBm), 0x2D(-6dBm), 0x8D(0dBm), 0xC3(+10dBm), 0xC0(max.).

Example

panstamp.radio.setTxPowerAmp(0xC0); //for max Tx power

disableAddressCheck

void disableAddressCheck(void)

Description

Disable address check. This enabled the radio to receive any packet transmitted in the same RF channel and with the same synchronization word regardless of the destination address of the packet.

Parameters

None

Example

panstamp.radio.disableAddressCheck();  // Disable address check

enableAddressCheck

void enableAddressCheck(void)

Description

Enable address check. This disables the radio from receiving any packet not directly addressed to it or not broadcasted.

Parameters

None

Example

panstamp.radio.enableAddressCheck();  // Enable address check

enableCCA

void enableCCA(bool enable)

Description

Enables the Clear Channel Assessment (CCA) that is used to indicate if the channel you are transmitting on is busy or free. (Enabled by default through SetCCregs)

Parameters

enable: true for Enabling the functionality, false for Disabling it.

Example

panstamp.radio.enableCCA(true);  // Enable CCA functionality

sendData

bool sendData(CCPACKET packet)

Description

Transmit packet. Return true if transmission is completed. Return false otherwise.

Parameters

packet : CCPACKET to be transmitted

Example

CCPACKET packet;  // CCPACKET pbject

packet.length = 10;  // packet length = 10 bytes

// Build packet payload (00 01 02 03 04 05 06 07 08 09).
// The first byte (0x00) is the destination address
// 0x00 means that the packet will be broadcasted
for(i=0 ; i<packet.length ; i++)
  packet.data[i] = i;

// Transmit packet
panstamp.radio.sendData(packet);

receiveData

uint8_t receiveData([CCPACKET *packet)

Description

Read wireless packet (CCPACKET) from Rx FIFO. This method has to be called every time the MCU is interrupted by a packet reception. The stack already uses this function internally so, instead of calling it from your application, attach a custom function following the example below.

Parameters

packet : Pointer to the packet received

Example

/**
 * This function is called whenever a wireless packet is received
 */
void rfPacketReceived(CCPACKET *packet)
{   
  if (packet->length > 1)
  {
    // packet.data[0];   // Our source address
    // packet.data[1];   // First data byte
    // packet.data[2];   // Second data byte
    // ...
    // packet.data[60];  // Maximum data byte per packet
  }
}

/**
 * Arduino's setup function
 */
void setup()
{
  // Init RF IC
  panstamp.init(CFREQ_868);
  panstamp.radio.setChannel(RFCHANNEL);
  panstamp.radio.setSyncWord(SYNCWORD1, SYNCWORD0);
  panstamp.radio.setDevAddress(SOURCE_ADDR);
  panstamp.radio.setCCregs();

  // Let's disable address check for the current project so that our device
  // will receive packets even not addressed to it.
  panstamp.radio.disableAddressCheck();

  // Declare RF callback function
  panstamp.setPacketRxCallback(rfPacketReceived);
}

setWorState

void setWorState(uint16_t millis)

Description

Puts the CC1101 into Wake-on-radio state where the Rx polls a specified interval and wakes up the module to packets received. Particularly useful if the module is in permanent sleep state through panstamp.sleep() because the module won't wake up from sleep through packets received due to CC1101 being disabled in this scenario.

Parameters

millis: Sleeping interval in milliseconds. It must be between 12ms and 2000ms/2s.

Example

panstamp.radio.setWorState(200);

See also

panStamp - Wireless miniatures

Anti Swap

API for Anti Swap

Clone this wiki locally