guide

Function Descriptions

Last Modified - May 9, 2017

Note: Work in Progress!!!

Intro: Below is a list of the module functions so far that I've developed.  
Most of the functions are for setting the various parameters for the radio,
2 for transmit and receive, 1 to get the last RSSI value and 1 to get the 
temperature via the radios temperature sensor.

transmit(transmitData, addressOn=False, toAddress=0,fromAddress=None,
ack=False, ackPattern=0, packetLength=64) 
– function to transmit data from the radio. Transmits a single packet of data 

- transmitData: data to be transmitted, should be in string format. Data larger 
  than the packetLength will be truncated to fit the packetLength.
- addressOn: if true an address byte will be added to the data to be sent
- toAddress:  the address byte to be sent if any address is being sent
- fromAddress: if non-zero value, adds a byte of data of the radio senders address,
  adds the byte one byte before ackPattern
- ack: if true will add the ackPattern data immediately before the data to be sent 
- ackPattern: optional acknowledge pattern to be added to packet sent
- packetLength:  length of packet radio is expecting to send, if fixed length
mode is used this should match the payload length parameter the radio is using

transmit_with_ack(txData, toAddress=0,intType = 'hw',retry=0, packetLength=64)
- function to transmit data with acknowledge back from the receiver after each
  packet sent Can transmit multiple packets. 

- txData: list of data to be sent, each list entry should either be in string or 
  bytearray format
- toAddress: the address byte to be sent if any address is being sent
- intType: interrupt type to be used, either 'hw' or 'sw' (hardware or software). 
  For hardware interrupts the radios interrupt pin has to be set and the pi GPIO 
  used has to be set using the set_dio(dio0=1) and set_interrupt_pin([PiGPIO#]) 
  functions respectively.
- retry: - max number of times to resend a packet to try to get a successful 
  acknowledge back from the receving radio
- packetLength:  length of packet radio is expecting to send, if fixed length
  mode is used this should match the payload length parameter the radio is using

Function returns 2 values, one for # of successfully sent packages (i.e. an acknowledge
received within the max retries allowed per packet) and one for failed sent packages 
(i.e. no acknowledge received within the max retries allowed per packet)


receive(timeout=999, background=False) – function to receive data sent to the radio

- timeout: length of time the radio should stay in receive mode,  a value of -1 
will leave the radio in receive mode indefinately.  To cancel the radio out of 
receive mode early set the radio objects receiveTimeout variable to 0.
- background – a value of False will leave the receive function inline with your
 program, i.e. you program won't progress past the receive function until the 
timeout length is reached. A value of True will put the receive function into 
the background via a seperate thread so your program can proceed past the receive
 function and do other stuff while the gathing receive data.

All received data is put into the radio object's receiveData[] list.

receive_hw_int() - function to receive data sent to the radio using a hardware interrupt
to monitor for incoming packets.

- for hardware interrupts the radios interrupt pin has to be set and the pi GPIO used
  has to be set using the set_dio(dio0=1) and set_interrupt_pin([PiGPIO#]) functions 
  respectively.

- the length of time the receiver is on for is set by the receive_timeout() function.
  A value of -1 will leave the radio in receive mode indefinately.  A value of 0 (zero)
  will cancel the radio out of receive mode immediately. The receive_timeout() function
  takes a value in seconds (s)

All received data is put into the radio object's receiveData[] list.

receive_sw_int() - function to receive data sent to the radio using a software interrupt
to monitor for incoming packets.

- the length of time the receiver is on for is set by the receive_timeout() function. 
  A value of -1 will leave the radio in receive mode indefinately.  A value of 0 (zero)
  will cancel the radio out of receive mode immediately. The receive_timeout() function 
  takes a value in seconds (s)

All received data is put into the radio object's receiveData[] list.

receive_timeout(time=0) – this function sets the amount of time the radio is in receive mode
- time: Value in seconds (s). A value of -1 will leave the radio in receive mode indefinately. 
  A value of 0 (zero) will cancel the radio out of receive mode immediately.
- sets self.receiveTimeout variable


last_rssi() - this function returns the last received signal strength indicator
stored in the radio's rssi register (RegRssiValue)  - this will be an integer 
value in dBm

temperature()  - this function will return the temperature obtained from the 
radio's temperature sensor – this will be an integer value.  Note: the 
temperature sensor will likely need to be calibrated against a know temperature.  
The radio object has a temperatureOffset variable that will need to be set. 
This can be done with the set_temperature_offset() function.

Radio Set up Functions

set_acks(receiveAck=0, sendAck=0) – function to set the receive and send ACK patterns used 
by the radio.  Patterns should be a single byte long.
- receiveAck: pattern send by the transmitter asking for an acknowledgement back and looked
  for by the receiver to trigger sending an acknowledgement
- sendAck: pattern sent by the receiver back to the transmitter in response to a receiveAck.
  Pattern looked for by the transmitter indicating a succesful packet sent.
- sets self.sendAck and self.receiveAck variables

set_address_filtering(mode='none')– function to set the addressing filtering mode
- mode: valid string values; none, node or both.  None means no address filtering is used, node requires 
  address matching to the node address and both requires either node address or broadcast address matching
- sets bits 1&2 of RegPacketConfig1 (0x37)

set_afc(afcLowBetaOn='Standard', afcOffset=0, dccFreq=4, rxBW=10.4, autoclearOn='off', autoOn='on')– function
to set the parameters for automatic frequency correction.
- afcLowBetaOn -valid values are 'Standard' or 'Improved' and sets bit 5 of RegAfcCtrl (0x0B)
- afcOffset – sets afc offset in low beta systems (i.e. afcLowBetaOn = Improved), pass an integer value in Hz. 
  Sets RegTestAfc (0x71)
- dccFreq – valid values are 0.125, 0.25, 0.5, 1, 2, 4, 8, 16
- rxBW – valid values are 2.6, 3.1, 3.9, 5.2, 6.3, 7.8, 10.4, 12.5, 15.6, 20.8, 25, 31.3, 41.7, 50.0, 62.5, 
  83.3, 100.0, 125.0, 166.7, 200.0, 250.0, 333.3, 400.0, 500.0. Together with dccFreq sets RegAfcBw (0x1A)
- autoclearOn – valid values are 'on' and 'off'
- autoOn – valid values are 'on' and off.  Together with autoclearOn sets bits 2 & 3 of RegAfcFei (0x1E)

set_auto_rx_restart(autoRestartOn='on', interPacketDelay=0x0) - function to enable/disable the automatic 
Rx restart (RSSI phase) feature of the radio and set the InterPacketRxDelay
- autoRestartOn – valid values are 'on' and 'off'
- interPacketDelay – pass an integer between 0 and 15
- sets bits 1 & 4-7 of RegPacketConfig2 (0x3D)

set_bitrate(bitrate) – function to set the radio transmission bitrate
- bitrate – pass an integer value in bits per seconds
- sets registers RegBitrateMsb & RegBitrateLsb (0x03 & 0x04)

set_broadcast_address(address=0x07)– function to set the broadcast address used in address filtering
- address – pass an integer between 1 and 255 in decimal or hex
- have had issues with even numbered address
- sets register RegBroadcastAdrs (0x3A)

set_checksum(crcOn='on', autoClearFifo='0n') – function to set the radio's checksum calculation function
- crcOn – value is either 'on' or 'off', if 'on' a 2 byte checksum value is added to the transmitted data 
  and the checksum calculation is performed on received data.
- autoClearFifo – value is either 'on' or 'off',  if 'on' and crcOn is 'on', if the checksum fails the 
  payload ready interrupt will not occur and the fifo will be cleared
- sets bits 3 & 4 of RegPacketConfig1 (0x37)

set_data_mode(dataMode='packet', modulationType='FSK', modShaping='none', bitSynchOn='on') – function to set
 the data mode parameters
- dataMode – valid choices are 'continuous' and 'packet'
- modulationType – valid choices are 'FSK' or 'OOK'
- modShaping – for modulationType of 'OOK',  valid values are 0, 1 , 2 with 0 meaing no shaping. For 
  modulationType of 'FSK', valid values are 0, 1, 0.5, 0.3 with 0 again meaning no shaping.
- bitSynchOn – valid values are 'on' or 'off'.  This only applies with dataMode of 'continuous' and 
  will set the dataMode with or without the bit synchronizer on.
- sets RegDataModul (0x02)

set_dc_free_encoding(encodingType='none') – function to enable/disable DC free encoding,
- encodingType – 3 choices 'none', 'manchester' or 'whitening'
- sets bits 5 & 6 of RegPacketConfig1 (0x37)

set_dio(dio0=0, dio1=0, dio2=0, dio3=0, dio4=0, dio5=0, clkOut='off') - function to map the DIO (digital I/O)
pins of the radio as well as set the clock output frequency if used
- dio0 – dio5 – pass an integer between 0 and 3 for each dio
- clkOut –  valid values are 'off', 'auto', 1, 2, 4, 8, 16 and 32
- sets RegDioMapping1 (0x25) and RegDioMapping2 (0x26)

set_encryption(aesOn='on', aesKeyList=[]) - function to enable/disable AES encryption and set the 16 AES 
encyption key registers. If aesKeyList is left empty the AES key registers will be left as is
- aesOn – valid values are 'on' and 'off'
- aesKeyList – pass a list of 16 integers (decimal or hex) with values between 1 and 255.
- sets bit 0 of RegPacketConfig2 (0x3D) and RegAesKey1 – RegAesKey16 (0x3E - 0x4D)

set_fifo_threshold(txStartCond='FifoLevel', threshold=20) - function to define the condition to start packet
transmission and set the Fifo threshold used to trigger the FifoLevel interrupt
- txStartCond – valid values are 'FifoLevel' and 'FifoNotEmpty'
- threshold – pass an integer value between 0 and 66
- sets RegFifoThresh (0x3C)

set_frequency(frequency) – function to set the tranceiver's tx/rx frequency
- frequency – pass an integer value in Hz
- sets registers RegFrfMsb, RegFrfMid & Reg FrfLsb (0x07-0x09)

set_frequency_deviation(fDev) - function to change the radio transmission frequency deviation
- fDev – pass an integer value in Hz
- sets registers RegFdevMsb & RegFdevLsb (0x05 & 0x06)

set_interrupt_pin(intPin=0) – function to tell the radio module which of the Pi's GPIO pins is being
used to receive the hardware (hw) interrupt signal from the radio
- intPin: Pi GPIO pin number
- sets self.intPin variable

set_lna(autoOn='on', gainSelect='G1', inputZ=50) - function to set the parameters for the receiver's
LNA (low noise amplifier)
- autoOn – valid values are 'on' and 'off''. Set to 'on' the LNA gain is set automatically by the 
  radio's internal AGC loop, otherwise the gain is set manually by the user.
- gainSelect – valid values are 'G1', 'G2', 'G3', 'G4', 'G5', 'G6'. This will manually set the LNA 
  gain level if autoOn is set to 'off'
- inputZ – valid values are 50 or 200 (ohms) and sets the LNA's input impedance
- sets RegLna (0x18)

set_mode_sequencer(sequencer='on') - function to enable/disable the radio's automatic sequencer
- sequencer – valid values are 'on' and 'off'
- sets bit 7 of RegOpMode (0x01)

set_node_address(address=0x05)- function to set the node address used in address filtering
- address – pass an integer between 1 and 255 in decimal or hex
- have had issues with even numbered addresses
- sets register RegNodeAdrs (0x39)

set_OCP(ocpOn='on', ocpMax=95) - function to enable/disable OCP (Over Current Protection) and set the 
max current (mA)
- ocpOn - valid values are 'on' and 'off'
- ocpMax – pass an integer value between 45 and 120 (mA)
- sets register RegOcp (0x13)

set_operating_mode(mode='standby') - function to set the radio's current mode
- mode – valid values are 'transmit', 'receive', 'sleep', 'freqSynth' and 'standby'
- sets bits 2-4 of RegOpMode (0x01)

set_packet_format(packetFormat='fixed',payloadLength=64) - function to set the packet format including 
fixed vs variable vs unlimited length and payload length
- packetFormat – valid values are 'variable', 'fixed' and 'unlimited'
- payloadLength – pass an integer between 1 and 255
- sets bit 7 of RegPacketConfig1 (0x37) and all of RegPayloadLength (0x38)
- sets self.packetFormat variable

set_power(ampSelect, powerLevel, powerRamp=40) - function to choose the power amplifier(s), transmit 
power used and power ramp time
- ampSelect – valid values are 'Pa0', 'Pa1', 'Pa2' and 'Pa2H'.  Pa2H is for high power PA setting,
  registers RegTestPa1, RegTestPa2 and RegTestAfc should also be altered accordingly.  These functions
  are not yet developed but the set_register_by_address or set_register_by_name function could be used.
- powerLevel – pass an integer value between -18 and 13 for Pa0, between -2 and 13 for Pa1, between
  2 and 17 for Pa2 and between 5 and 20 for Pa2H.
- powerRamp – valid values are (micro seconds); 10, 12, 15, 20, 25, 31, 40, 50, 62, 100, 125, 250,
  500, 1000, 2000 and 3400
- sets RegPaLevel (0x11) and RegPaRamp (0x12)

set_preamble_length(length=2) - function to set the length of the preamble (bytes)
- length – pass an integer value between 1 and 65535
- sets RegPreambleMsb (0x2C) and RegPreamble (0x2D)

set_register_by_address(registerAddr, value) - function to set a single register by passing the 
register address and the value for it to be set to. The radio object registerList is also updated
- registerAddr – register address ( i.e. 0x2C)
- value – pass the value you want to set the register to

set_register_by_name(registerName, value) - function to set a single register by passing the register
name and the value for it to be set to. The radio object registerList is also updated
- registerName – name of the register to set, the naming convention from the radio datasheets 
  are used (i.e. RegPreambleMsB)
- value – pass the value you want to set the register to

set_rssi_threshold(rssi) - funstion to change the receive signal strength indicator (rssi) threshold
(dBm) used by the receiver
- rssi – pass an float value (dBm) between 0 and 127.5
- sets RegRssiThresh (0x29)

set_rxbw(dccFreq=4, rxBW=10.4) - function to set the receiver bandwidth parameters when afc 
(automatic frequency correction) is not enabled
- dccFreq – valid values are 0.125, 0.25, 0.5, 1, 2, 4, 8, 16
- rxBW – valid values are 2.6, 3.1, 3.9, 5.2, 6.3, 7.8, 10.4, 12.5, 15.6, 20.8, 25, 31.3, 41.7,
  50.0, 62.5, 83.3, 100.0, 125.0, 166.7, 200.0, 250.0, 333.3, 400.0, 500.0
- sets RegRxBw (0x19)

set_sync(syncOn='on', syncSize=3, syncTol=2, fifoFill=0) - function to set the sync word options
- syncOn – valid values are 'on' and 'off'. Turns sync word generation and detection on or off
- syncSize – pass an integer value (bytes) between 1 and 7. Sets the size of the sync word
- syncTol -  pass an integer value (bits) between 1 and 7. Sets the number of tolerated bit errors
  in the sync word
- fifoFill – valid values are 0 and 1.
- sets RegSyncConfig (0x2E)

set_sync_word(syncValueList=[0xE2,0x4A,0x26]) - function to set the sync word. This will set the
8 RegSyncValue registers
- syncValueList – pass a list of 1 to 8 integers (decimal or hex). Each integer should be between
  1 and 255
- sets registers RegSyncValue1 to RegSyncValue8 (0x2F - 0x36)

set_temperature_offset(offset=0) - function to change the temperature offset value, used to calibrate
the radio temperature sensor reading.
- offset – pass an integer value

set_timeout_rssi_threshold(timeoutOn='off', multiplier=0x00) - function enable/disable the TimeoutRssiThresh
interrupt and to set it's level if enabled
- timeoutOn – valid values are 'on' and 'off'
- multiplier – pass an integer value between 1 and 255
- sets RegRxTimeout2 (0x2B)

set_timeout_rx_start(timeoutOn='off', multiplier=0x00) - function enable/disable the TimeoutRxStart interrupt
and to set it's level if enabled
- timeoutOn – valid values are 'on' and 'off'
- multiplier – pass an integer value between 1 and 255
- sets RegRxTimeout1 (0x2A)


Sent Packet Format

Each packet sent, is sent in the following format. The length, toAddress, fromAddress and Ack bytes are all
 optional and only included if selected via the various options.  For example the length byte is not included
 if using fixed length format packets

Length Byte, toAddress Byte, fromAddress byte, ACK byte, data/payload bytes


Functions that rely on RPi.GPIO module

The following functions rely on the RPi.GPIO module, these are for the hardware interrupts. If you want to
use only the software interrupts or a difffernt GPIO manipulating modules these are the functions that
will need to be modified or deleted.

- receive_ack()
- receive_hw_int()