UPM

The UPM API is a high level sensor library for IoT devices using MRAA. See examples here. Back to index page.
SparkFun sensor images provided under CC BY-NC-SA-3.0.

RF22 Class

Module: rf22

This base class provides basic functions for sending and receiving unaddressable, unreliable datagrams of arbitrary length to 255 octets per packet.
Subclasses may use this class to implement reliable, addressed datagrams and streams, mesh routers, repeaters, translators etc.
On transmission, the TO and FROM addresses default to 0x00, unless changed by a subclass. On reception the TO addressed is checked against the node address (defaults to 0x00) or the broadcast address (which is 0xff). The ID and FLAGS are set to 0, and not checked by this class. This permits use of the this base RF22 class as an unaddressable, unreliable datagram service. Subclasses are expected to change this behavior to add node address, ids, retransmission etc.
Naturally, for any 2 radios to communicate that must be configured to use the same frequency and modulation scheme.
rf22.jpg

Methods

RF22

(
  • spiBus
  • slaveSelectPin
  • interruptPin
)
Number

Constructor. You can have multiple instances, but each instance must have its own interrupt and slave select pin. After constructing, you must call init() to initialize the interface and the radio module

Parameters:

  • spiBus Number

    Pointer to the SPI interface object to use. Default 0 or the standard Arduino hardware SPI interface

  • slaveSelectPin Number

    the Arduino pin number of the output to use to select the RF22 before accessing it. Default is 10 or the normal SS pin for Arduino

  • interruptPin Number

    The interrupt pin number to use. Default is 2

Returns:

Number:

init

() Number

Initializes this instance and the radio module connected to it. The following steps are taken:

  • Software reset the RF22 module
  • Checks the connected RF22 module is either a RF22_DEVICE_TYPE_RX_TRX or a RF22_DEVICE_TYPE_TX
  • Configures the RF22 module
  • Sets the frequency to 434.0 MHz
  • Sets the modem data rate to FSK_Rb2_4Fd36

Returns:

Number:

reset

()

Issues a software reset to the RF22 module. Blocks for 1ms to ensure the reset is complete.

spiRead

(
  • reg
)
Number

Reads a single register from the RF22

Parameters:

  • reg Number

    Register number, one of RF22_REG_*

Returns:

Number:

The value of the register

spiWrite

(
  • reg
  • val
)

Writes a single byte to the RF22

Parameters:

  • reg Number

    Register number, one of RF22_REG_*

  • val Number

    The value to write

spiBurstRead

(
  • reg
  • dest
  • len
)

Reads a number of consecutive registers from the RF22 using burst read mode

Parameters:

  • reg Number

    Register number of the first register, one of RF22_REG_*

  • dest Uint8_t *

    Array to write the register values to. Must be at least len bytes

  • len Number

    Number of bytes to read

spiBurstWrite

(
  • reg
  • src
  • len
)

Write a number of consecutive registers using burst write mode

Parameters:

  • reg Number

    Register number of the first register, one of RF22_REG_*

  • src Const uint8_t *

    Array of new register values to write. Must be at least len bytes

  • len Number

    Number of bytes to write

statusRead

() Number

Reads and returns the device status register RF22_REG_02_DEVICE_STATUS

Returns:

Number:

The value of the device status register

adcRead

(
  • adcsel
  • adcref
  • adcgain
  • adcoffs
)
Number

Reads a value from the on-chip analog-digital converter

Parameters:

  • adcsel Number

    Selects the ADC input to measure. One of RF22_ADCSEL_*. Defaults to the internal temperature sensor

  • adcref Number

    Specifies the reference voltage to use. One of RF22_ADCREF_*. Defaults to the internal bandgap voltage.

  • adcgain Number

    Amplifier gain selection.

  • adcoffs Number

    Amplifier offset (0 to 15).

Returns:

Number:

The analog value. 0 to 255.

temperatureRead

(
  • tsrange
  • tvoffs
)
Number

Reads the on-chip temperature sensor

Parameters:

  • tsrange Number

    Specifies the temperature range to use. One of RF22_TSRANGE_*

  • tvoffs Number

    Specifies the temperature value offset. This is actually signed value added to the measured temperature value

Returns:

Number:

The measured temperature.

wutRead

() Number

Reads the wakeup timer value in registers RF22_REG_17_WAKEUP_TIMER_VALUE1 and RF22_REG_18_WAKEUP_TIMER_VALUE2

Returns:

Number:

The wakeup timer value

setWutPeriod

(
  • wtm
  • wtr
  • wtd
)

Sets the wakeup timer period registers RF22_REG_14_WAKEUP_TIMER_PERIOD1, RF22_REG_15_WAKEUP_TIMER_PERIOD2 and RF22_R<EG_16_WAKEUP_TIMER_PERIOD3

Parameters:

  • wtm Number

    Wakeup timer mantissa value

  • wtr Number

    Wakeup timer exponent R value

  • wtd Number

    Wakeup timer exponent D value

setFrequency

(
  • center
  • afcPullInRange
)
Number

Sets the transmitter and receiver center frequency

Parameters:

  • center Number

    Frequency in MHz. 240.0 to 960.0. Caution, some versions of RF22 and derivatives implemented more restricted frequency ranges.

  • afcPullInRange Number

    Sets the AF Pull In Range in MHz. Defaults to 0.05MHz (50kHz). Range is 0.0 to 0.159375 for frequencies 240.0 to 480MHz, and 0.0 to 0.318750MHz for frequencies 480.0 to 960MHz,

Returns:

Number:

true if the selected frequency center + (fhch * fhs) is within range and the afcPullInRange is within range

setFHStepSize

(
  • fhs
)
Number

Sets the frequency hopping step size.

Parameters:

  • fhs Number

    Frequency Hopping step size in 10kHz increments

Returns:

Number:

true if center + (fhch * fhs) is within limits

setFHChannel

(
  • fhch
)
Number

Sets the frequency hopping channel. Adds fhch * fhs to center frequency

Parameters:

  • fhch Number

    The channel number

Returns:

Number:

true if the selected frequency center + (fhch * fhs) is within range

rssiRead

() Number

Reads and returns the current RSSI value from register RF22_REG_26_RSSI. If you want to find the RSSI of the last received message, use lastRssi() instead.

Returns:

Number:

The current RSSI value

ezmacStatusRead

() Number

Reads and returns the current EZMAC value from register RF22_REG_31_EZMAC_STATUS

Returns:

Number:

The current EZMAC value

setMode

(
  • mode
)

Sets the parameters for the RF22 Idle mode in register RF22_REG_07_OPERATING_MODE. Idle mode is the mode the RF22 will be in when not transmitting or receiving. The default idle mode is RF22_XTON i.e. READY mode.

Parameters:

  • mode Number

    Mask of mode bits, using RF22_SWRES, RF22_ENLBD, RF22_ENWT, RF22_X32KSEL, RF22_PLLON, RF22_XTON.

setModeIdle

()

If current mode is Rx or Tx changes it to Idle. If the transmitter or receiver is running, disables them.

setModeRx

()

If current mode is Tx or Idle, changes it to Rx. Starts the receiver in the RF22 .

setModeTx

()

If current mode is Rx or Idle, changes it to Rx. Starts the transmitter in the RF22 .

mode

() Number

Returns the operating mode of the library.

Returns:

Number:

the current mode, one of RF22_MODE_*

setTxPower

(
  • power
)

Sets the transmitter power output level in register RF22_REG_6D_TX_POWER. Be a good neighbor and set the lowest power level you need. After init() , the power will be set to RF22_TXPOW_8DBM. Caution: In some countries you may only select RF22_TXPOW_17DBM if you are also using frequency hopping.

Parameters:

  • power Number

    Transmitter power level, one of RF22_TXPOW_*

setModemRegisters

(
  • config
)

Sets all the registered required to configure the data modem in the RF22 , including the data rate, bandwidths etc. You can use this to configure the modem with custom configurations if none of the canned configurations in ModemConfigChoice suit you.

Parameters:

  • config Const ModemConfig *

    A ModemConfig structure containing values for the modem configuration registers.

setModemConfig

(
  • index
)
Number

Select one of the predefined modem configurations. If you need a modem configuration not provided here, use setModemRegisters() with your own ModemConfig .

Parameters:

  • index ModemConfigChoice

    The configuration choice.

Returns:

Number:

true if index is a valid choice.

available

() Number

Starts the receiver and checks whether a received message is available. This can be called multiple times in a timeout loop

Returns:

Number:

true if a complete, valid message has been received and is able to be retrieved by recv()

waitAvailable

()

Starts the receiver and blocks until a valid received message is available.

waitAvailableTimeout

(
  • timeout
)
Boolean

Starts the receiver and blocks until a received message is available or a timeout

Parameters:

  • timeout Number

    Maximum time to wait in milliseconds.

Returns:

Boolean:

true if a message is available

recv

(
  • buf
  • len
)
Number

Turns the receiver on if it not already on. If there is a valid message available, copy it to buf and return true else return false. If a message is copied, *len is set to the length (Caution, 0 length messages are permitted). You should be sure to call this function frequently enough to not miss any messages It is recommended that you call it in your main loop.

Parameters:

  • buf Uint8_t *

    Location to copy the received message

  • len Uint8_t *

    Pointer to available space in buf. Set to the actual number of octets copied.

Returns:

Number:

true if a valid message was copied to buf

send

(
  • data
  • len
)
Number

Waits until any previous transmit packet is finished being transmitted with waitPacketSent() . Then loads a message into the transmitter and starts the transmitter. Note that a message length of 0 is NOT permitted.

Parameters:

  • data Const uint8_t *

    Array of data to be sent

  • len Number

    Number of bytes of data to send (> 0)

Returns:

Number:

true if the message length was valid and it was correctly queued for transmit

waitPacketSent

()

Blocks until the RF22 is not in mode RF22_MODE_TX (i.e. until the RF22 is not transmitting). This effectively waits until any previous transmit packet is finished being transmitted.

setPromiscuous

(
  • promiscuous
)

Tells the receiver to accept messages with any TO address, not just messages addressed to this node or the broadcast address

Parameters:

  • promiscuous Number

    true if you wish to receive messages with any TO address

headerTo

() Number

Returns the TO header of the last received message

Returns:

Number:

The TO header

headerFrom

() Number

Returns the FROM header of the last received message

Returns:

Number:

The FROM header

headerId

() Number

Returns the ID header of the last received message

Returns:

Number:

The ID header

headerFlags

() Number

Returns the FLAGS header of the last received message

Returns:

Number:

The FLAGS header

lastRssi

() Number

Returns the RSSI (Receiver Signal Strength Indicator) of the last received message. This measurement is taken when the preamble has been received. It is a (non-linear) measure of the received signal strength.

Returns:

Number:

The RSSI

setPreambleLength

(
  • nibbles
)

Sets the length of the preamble in 4-bit nibbles. Caution: this should be set to the same value on all nodes in your network. Default is 8. Sets the message preamble length in RF22_REG_34_PREAMBLE_LENGTH

Parameters:

  • nibbles Number

    Preamble length in nibbles of 4 bits each.

setSyncWords

(
  • syncWords
  • len
)

Sets the sync words for transmit and receive in registers RF22_REG_36_SYNC_WORD3 to RF22_REG_39_SYNC_WORD0 Caution: this should be set to the same value on all nodes in your network. Default is { 0x2d, 0xd4 }

Parameters:

  • syncWords Const uint8_t *

    Array of sync words

  • len Number

    Number of sync words to set

Properties

UnmodulatedCarrier

Enum ModemConfigChoice

FSK_PN9_Rb2Fd5

Enum ModemConfigChoice

FSK_Rb2Fd5

Enum ModemConfigChoice

FSK_Rb2_4Fd36

Enum ModemConfigChoice

FSK_Rb4_8Fd45

Enum ModemConfigChoice

FSK_Rb9_6Fd45

Enum ModemConfigChoice

FSK_Rb19_2Fd9_6

Enum ModemConfigChoice

FSK_Rb38_4Fd19_6

Enum ModemConfigChoice

FSK_Rb57_6Fd28_8

Enum ModemConfigChoice

FSK_Rb125Fd125

Enum ModemConfigChoice

GFSK_Rb2Fd5

Enum ModemConfigChoice

GFSK_Rb2_4Fd36

Enum ModemConfigChoice

GFSK_Rb4_8Fd45

Enum ModemConfigChoice

GFSK_Rb9_6Fd45

Enum ModemConfigChoice

GFSK_Rb19_2Fd9_6

Enum ModemConfigChoice

GFSK_Rb38_4Fd19_6

Enum ModemConfigChoice

GFSK_Rb57_6Fd28_8

Enum ModemConfigChoice

GFSK_Rb125Fd125

Enum ModemConfigChoice

OOK_Rb1_2Bw75

Enum ModemConfigChoice

OOK_Rb2_4Bw335

Enum ModemConfigChoice

OOK_Rb4_8Bw335

Enum ModemConfigChoice

OOK_Rb9_6Bw335

Enum ModemConfigChoice

OOK_Rb19_2Bw335

Enum ModemConfigChoice

OOK_Rb38_4Bw335

Enum ModemConfigChoice

OOK_Rb40Bw335

Enum ModemConfigChoice