RadioHead
Classes | Public Types | Public Member Functions | Protected Types | Protected Member Functions | List of all members
RH_E32 Class Reference

Driver to send and receive unaddressed, unreliable datagrams via a EBYTE E32-TTL-1W and similar serial radio transceiver. More...

#include <RH_E32.h>

Inheritance diagram for RH_E32:
RHGenericDriver

Classes

struct  Parameters
 Structure for reading and writing radio control parameters. More...
 

Public Types

enum  DataRate {
  DataRate1kbps = RH_E32_PARAM_SPED_DATARATE_1KBPS, DataRate2kbps = RH_E32_PARAM_SPED_DATARATE_2KBPS, DataRate5kbps = RH_E32_PARAM_SPED_DATARATE_5KBPS, DataRate8kbps = RH_E32_PARAM_SPED_DATARATE_8KBPS,
  DataRate10kbps = RH_E32_PARAM_SPED_DATARATE_10KBPS, DataRate15kbps = RH_E32_PARAM_SPED_DATARATE_15KBPS, DataRate20kbps = RH_E32_PARAM_SPED_DATARATE_20KBPS, DataRate25kbps = RH_E32_PARAM_SPED_DATARATE_25KBPS
}
 Values to be passed to setDataRate() to control the on-air data rate. More...
 
enum  PowerLevel { Power30dBm = RH_E32_PARAM_OPTION_POWER_30DBM, Power27dBm = RH_E32_PARAM_OPTION_POWER_27DBM, Power24dBm = RH_E32_PARAM_OPTION_POWER_24DBM, Power21dBm = RH_E32_PARAM_OPTION_POWER_21DBM }
 Values to be passed to setPower() to control the transmitter power.
 
enum  BaudRate {
  BaudRate1200 = RH_E32_PARAM_SPED_UART_BAUD_1200, BaudRate2400 = RH_E32_PARAM_SPED_UART_BAUD_2400, BaudRate4800 = RH_E32_PARAM_SPED_UART_BAUD_4800, BaudRate9600 = RH_E32_PARAM_SPED_UART_BAUD_9600,
  BaudRate19200 = RH_E32_PARAM_SPED_UART_BAUD_19200, BaudRate38400 = RH_E32_PARAM_SPED_UART_BAUD_38400, BaudRate57600 = RH_E32_PARAM_SPED_UART_BAUD_57600, BaudRate115200 = RH_E32_PARAM_SPED_UART_BAUD_115200
}
 Values to be passed to setBaudRate() to control the radio serial connection baud rate. More...
 
enum  Parity { Parity8N1 = RH_E32_PARAM_SPED_UART_MODE_8N1, Parity8O1 = RH_E32_PARAM_SPED_UART_MODE_8O1, Parity8E1 = RH_E32_PARAM_SPED_UART_MODE_8E1 }
 Values to be passed to setBaudRate() to control the parity of the serial connection to the radio.
 
- Public Types inherited from RHGenericDriver
enum  RHMode {
  RHModeInitialising = 0, RHModeSleep, RHModeIdle, RHModeTx,
  RHModeRx, RHModeCad
}
 Defines different operating modes for the transport hardware. More...
 

Public Member Functions

 RH_E32 (Stream *s=&Serial, uint8_t m0_pin=4, uint8_t m1_pin=5, uint8_t aux_pin=8)
 
bool init ()
 
bool available ()
 
bool recv (uint8_t *buf, uint8_t *len)
 
bool send (const uint8_t *data, uint8_t len)
 
uint8_t maxMessageLength ()
 
bool waitPacketSent ()
 
bool setDataRate (DataRate rate)
 
bool setPower (PowerLevel level)
 
bool setBaudRate (BaudRate rate=BaudRate9600, Parity parity=Parity8N1)
 
bool setFrequency (uint16_t frequency)
 
- Public Member Functions inherited from RHGenericDriver
 RHGenericDriver ()
 Constructor.
 
virtual void waitAvailable ()
 
virtual bool waitPacketSent (uint16_t timeout)
 
virtual bool waitAvailableTimeout (uint16_t timeout)
 
virtual bool waitCAD ()
 
void setCADTimeout (unsigned long cad_timeout)
 
virtual bool isChannelActive ()
 
virtual void setThisAddress (uint8_t thisAddress)
 
virtual void setHeaderTo (uint8_t to)
 
virtual void setHeaderFrom (uint8_t from)
 
virtual void setHeaderId (uint8_t id)
 
virtual void setHeaderFlags (uint8_t set, uint8_t clear=RH_FLAGS_APPLICATION_SPECIFIC)
 
virtual void setPromiscuous (bool promiscuous)
 
virtual uint8_t headerTo ()
 
virtual uint8_t headerFrom ()
 
virtual uint8_t headerId ()
 
virtual uint8_t headerFlags ()
 
int16_t lastRssi ()
 
RHMode mode ()
 
void setMode (RHMode mode)
 Sets the operating mode of the transport.
 
virtual bool sleep ()
 
virtual uint16_t rxBad ()
 
virtual uint16_t rxGood ()
 
virtual uint16_t txGood ()
 

Protected Types

enum  OperatingMode { ModeNormal = 0, ModeWakeUp, ModePowerSaving, ModeSleep }
 Defines values to be passed to setOperatinMode. More...
 

Protected Member Functions

void setOperatingMode (OperatingMode mode)
 
bool getVersion ()
 
void waitAuxHigh ()
 
void waitAuxLow ()
 
bool reset ()
 
bool readParameters (Parameters &params)
 
bool writeParameters (Parameters &params, bool save=false)
 
void validateRxBuf ()
 
void clearRxBuf ()
 

Additional Inherited Members

- Static Public Member Functions inherited from RHGenericDriver
static void printBuffer (const char *prompt, const uint8_t *buf, uint8_t len)
 
- Protected Attributes inherited from RHGenericDriver
volatile RHMode _mode
 The current transport operating mode.
 
uint8_t _thisAddress
 This node id.
 
bool _promiscuous
 Whether the transport is in promiscuous mode.
 
volatile uint8_t _rxHeaderTo
 TO header in the last received mesasge.
 
volatile uint8_t _rxHeaderFrom
 FROM header in the last received mesasge.
 
volatile uint8_t _rxHeaderId
 ID header in the last received mesasge.
 
volatile uint8_t _rxHeaderFlags
 FLAGS header in the last received mesasge.
 
uint8_t _txHeaderTo
 TO header to send in all messages.
 
uint8_t _txHeaderFrom
 FROM header to send in all messages.
 
uint8_t _txHeaderId
 ID header to send in all messages.
 
uint8_t _txHeaderFlags
 FLAGS header to send in all messages.
 
volatile int16_t _lastRssi
 The value of the last received RSSI value, in some transport specific units.
 
volatile uint16_t _rxBad
 Count of the number of bad messages (eg bad checksum etc) received.
 
volatile uint16_t _rxGood
 Count of the number of successfully transmitted messaged.
 
volatile uint16_t _txGood
 Count of the number of bad messages (correct checksum etc) received.
 
volatile bool _cad
 Channel activity detected.
 
unsigned int _cad_timeout
 Channel activity timeout in ms.
 

Detailed Description

Driver to send and receive unaddressed, unreliable datagrams via a EBYTE E32-TTL-1W and similar serial radio transceiver.

Works with E32-TTL-1W

Note: it should also be possible to use the E32-TTL-1W with the RadioHead RH_Serial module, which will also you to send longer packets, but will require you to use the EBYTE Wireless Module Setting program to configure teh radio first. In this arrangement the E32 would act as a transparent serial connection. This has not been tested by us.

Overview

This class provides basic functions for sending and receiving unaddressed, unreliable datagrams of arbitrary length to 53 octets per packet.

Manager classes may use this class to implement reliable, addressed datagrams and streams, mesh routers, repeaters, translators etc.

Naturally, for any 2 radios to communicate that must be configured to use the same frequency and modulation scheme.

This Driver provides an object-oriented interface for sending and receiving data messages with EBYTE RFM95/96/97/98(W), Semtech SX1276/77/78/7E32-TTL-1W9 and compatible radio modules. These modules implement long range LORA transcivers with a transparent serial interface. With 1W power output the manufacturer claims up to 6km range.

This Driver provides functions for sending and receiving messages of up to 53 octets on any frequency supported by the radio, in a range of data rates and power outputs. Frequency can be set with 1MHz precision to any frequency from 410 to 441MHz.

You can use either a hardware or software serial connection.

Tested with Arduino Uno and software serial.

Packet Format

All messages sent and received by this Driver conform to this packet format:

Connecting E32-TTL-1W to Arduino

We tested with Arduino Uno. We used SoftwareSerial on pins 6 and 7) to connect to the E32 module, so we could continue to use the only hardware serial port for debugging

Arduino RFM95/96/97/98
GND----------GND (ground in)
5V-----------VCC (5V in)
pin D4-----------M0 (mode control pin input to radio)
pin D5-----------M1 (mode control pin input to radio)
pin D6-----------RXD (serial data input from Arduino to radio)
pin D7-----------TXD (serial data output from radio to Arduino)
pin D8-----------AUX (Aux pin output from radio to Arduino)

With this conneciton, you can initialise the serail port and RH_E32 like this:

SoftwareSerial mySerial(7, 6);
RH_E32 driver(&mySerial, 4, 5, 8);

Other connection schems are possible provided the approporiate constructors are used for SoftwareSerial and RH_E32

Memory

The RH_RF95 driver requires non-trivial amounts of memory. The sample programs all compile to about 8kbytes each, which will fit in the flash proram memory of most Arduinos. However, the RAM requirements are more critical. Therefore, you should be vary sparing with RAM use in programs that use the RH_E32 driver.

It is often hard to accurately identify when you are hitting RAM limits on Arduino. The symptoms can include:

Performance

This radio supports a range of different data rates and powers. The lowest speeds are the most reliable, however you should note that at 1kbps and with an 13 octet payload, the transmission time for one packet approaches 5 seconds. Therefore you should be cautios about trying to send too many or too long messages per unit of time, lest you monopolise the airwaves. Be a good neighbour and use the lowest power and fastest speed that you can.

Forward Error Correction (FEC) is always enabled in these radios by RH_E32.

Range

When running with a power output of 1W and at the slowest speed of 1kbps, this module has an impressive range. We tested with: E32-TTL-1W (1 W power, 1kbps data rate) Single wire antenna with a small meta ground plane at about 1m above ground level Arduino Uno RadioHead RH_E32 module with e32_client and e32_server sketches Packet length 13 octets (total payload 18 octets) (and yes, we have an appropriate radio license for that power output)

We were able to get reliable reception over 7km (6 km over ocean and 1 km through low rise residential area)

You can expect less range with lower power outputs and faster speeds. You can expect less range in highrise cities. You can expect more range with directional antennas. You can expect more range with shorter messages.

Transmitter Power
TBA

Caution: the maximum power output of this radio (1W = 30dbM) is almost certainly more than the permitted power level for unlicensed users in the ISM bands in most countries. Be sure you comply with your local regulations. Be a good neighbour and use the lowest power and fastest speed that you can.

Member Enumeration Documentation

◆ BaudRate

Values to be passed to setBaudRate() to control the radio serial connection baud rate.

This is NOT to be used to control the on-air data rate the radio transmits and receives at

◆ DataRate

Values to be passed to setDataRate() to control the on-air data rate.

This is NOT to be used to control the baud rate of the serial connection to the radio

◆ OperatingMode

enum RH_E32::OperatingMode
protected

Defines values to be passed to setOperatinMode.

For internal driver user only

Enumerator
ModeNormal 

Normal mode for sending and receiving messages.

ModeWakeUp 

Adds a long preamble to transmission to allow destination receivers to wake up.

ModePowerSaving 

Receiver sleeps until a message is received.

ModeSleep 

Use during parameter setting.

Constructor & Destructor Documentation

◆ RH_E32()

RH_E32::RH_E32 ( Stream *  s = &Serial,
uint8_t  m0_pin = 4,
uint8_t  m1_pin = 5,
uint8_t  aux_pin = 8 
)

Contructor. You can have multiple instances, but each instance must have its own serial connection, M0 M1 and AUX connections. Initialises the mode of the referenced pins Does NOT set the baud rate of the serial connection to the radio.

Parameters
[in]sReference to the SoftwareSerial or HardwareSerial port used to connect to the radio
[in]m0_pinPin number of the Arduino pin that connects to the radio M0 input
[in]m1_pinPin number of the Arduino pin that connects to the radio M1 input
[in]aux_pinPin number of the Arduino pin that connects to the radio AUX output

Member Function Documentation

◆ available()

bool RH_E32::available ( )
virtual

Tests whether a new message is available from the Driver. This can and should be called multiple times in a timeout loop. You should call this as frequently as possible whenever a message might be received

Returns
true if a new, complete, error-free uncollected message is available to be retreived by recv().

Implements RHGenericDriver.

References RHGenericDriver::_mode, RHGenericDriver::_rxBad, clearRxBuf(), RHGenericDriver::RHModeTx, and validateRxBuf().

Referenced by recv().

◆ clearRxBuf()

void RH_E32::clearRxBuf ( )
protected

Clear our local receive buffer For internal use only

Referenced by available(), init(), and recv().

◆ getVersion()

bool RH_E32::getVersion ( )
protected

Retrieves the version number for the radio and checks that it is valid

Returns
true if the version could be retrieved and is radio model number is correct

References ModeNormal, ModeSleep, and setOperatingMode().

Referenced by init().

◆ init()

bool RH_E32::init ( )
virtual

Initialise the Driver transport hardware and software. Make sure the Driver is properly, including setting the serial port baud rate and parity to that configured in the radio (typically 9600 baud, 8N1) before calling init(). Sets the module to 443MHz, 21dBm power and 5kbps data rate (you can change these after initialisation with the various set* functions). This function may not return if the AUX pin is not connected. Initialisation failure can be caused by: Electrical connections to the radio incorrect or incomplete Radio configured to use a different baud rate to the one configured to the Ardiono serial port Incorrect radio module connected tot he serial port. Other serial communicaitons problems between the Arduino and the radio

Returns
true if initialisation succeeded.

Reimplemented from RHGenericDriver.

References clearRxBuf(), getVersion(), RHGenericDriver::RHModeRx, setDataRate(), setFrequency(), RHGenericDriver::setMode(), setPower(), and waitAuxHigh().

◆ maxMessageLength()

uint8_t RH_E32::maxMessageLength ( )
virtual

Returns the maximum message length available in this Driver.

Returns
The maximum legal message length

Implements RHGenericDriver.

◆ readParameters()

bool RH_E32::readParameters ( Parameters params)
protected

Read the radio configuration parameters into local memory

Parameters
[in]paramsReference to a Parameter structure which will be filled if successful
Returns
true if successful

References ModeNormal, ModeSleep, and setOperatingMode().

Referenced by setBaudRate(), setDataRate(), setFrequency(), and setPower().

◆ recv()

bool RH_E32::recv ( uint8_t *  buf,
uint8_t *  len 
)
virtual

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
[in]bufLocation to copy the received message
[in,out]lenPointer to available space in buf. Set to the actual number of octets copied.
Returns
true if a valid message was copied to buf

Implements RHGenericDriver.

References available(), and clearRxBuf().

◆ reset()

bool RH_E32::reset ( )
protected

Issues a reset command to the radio WARNING: this seems to break reception. Why?

Returns
true if successful

References ModeNormal, ModeSleep, and setOperatingMode().

◆ send()

bool RH_E32::send ( const uint8_t *  data,
uint8_t  len 
)
virtual

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 permitted.

Parameters
[in]dataArray of data to be sent
[in]lenNumber of bytes of data to send
Returns
true if the message length was valid and it was correctly queued for transmit. Return false if CAD was requested and the CAD timeout timed out before clear channel was detected.

Implements RHGenericDriver.

References RHGenericDriver::_txGood, RHGenericDriver::_txHeaderFlags, RHGenericDriver::_txHeaderFrom, RHGenericDriver::_txHeaderId, RHGenericDriver::_txHeaderTo, RHGenericDriver::RHModeTx, RHGenericDriver::setMode(), and waitPacketSent().

◆ setBaudRate()

bool RH_E32::setBaudRate ( BaudRate  rate = BaudRate9600,
Parity  parity = Parity8N1 
)

Sets the radio serial port baud rate and parity (not the on-air data rate) Does not set the Aruino rate or parity: you wil nned to do this afterwards

Parameters
[in]rateA valid baud rate from the BaudRate enum
[in]parityA valid parity from the PArity enum
Returns
true if successful

References readParameters(), RH_E32::Parameters::sped, and writeParameters().

◆ setDataRate()

bool RH_E32::setDataRate ( DataRate  rate)

Sets the on-air data rate to be used by the transmitter and receiver

Parameters
[in]rateA valid data rate from the DataRate enum
Returns
true if successful

References readParameters(), RH_E32::Parameters::sped, and writeParameters().

Referenced by init().

◆ setFrequency()

bool RH_E32::setFrequency ( uint16_t  frequency)

Sets the tarnsmitter and receiver frequency.

Parameters
[in]frequencyDesired frequency in MHx from 410 to 441 MHz inclusive
Returns
true if successful

References RH_E32::Parameters::chan, readParameters(), and writeParameters().

Referenced by init().

◆ setOperatingMode()

void RH_E32::setOperatingMode ( OperatingMode  mode)
protected

Sets the operating mode of the radio. For internal use only

References ModeNormal, ModePowerSaving, ModeSleep, ModeWakeUp, and waitAuxHigh().

Referenced by getVersion(), readParameters(), reset(), and writeParameters().

◆ setPower()

bool RH_E32::setPower ( PowerLevel  level)

Sets the transmitter power output

Parameters
[in]levelA valid power setting from the Power enum
Returns
true if successful

References RH_E32::Parameters::option, readParameters(), and writeParameters().

Referenced by init().

◆ validateRxBuf()

void RH_E32::validateRxBuf ( )
protected

Examine the receive buffer to determine whether the message is for this node For internal use only

References RHGenericDriver::_promiscuous, RHGenericDriver::_rxGood, RHGenericDriver::_rxHeaderFlags, RHGenericDriver::_rxHeaderFrom, RHGenericDriver::_rxHeaderId, RHGenericDriver::_rxHeaderTo, and RHGenericDriver::_thisAddress.

Referenced by available().

◆ waitAuxHigh()

void RH_E32::waitAuxHigh ( )
protected

Waits for the AUX pin to go high For internal use only

Referenced by init(), setOperatingMode(), and waitPacketSent().

◆ waitAuxLow()

void RH_E32::waitAuxLow ( )
protected

Waits for the AUX pin to go low For internal use only

◆ waitPacketSent()

bool RH_E32::waitPacketSent ( )
virtual

Waits for any currently transmitting packet to be completely sent Returns true if successful

Reimplemented from RHGenericDriver.

References RHGenericDriver::_mode, RHGenericDriver::RHModeRx, RHGenericDriver::RHModeTx, RHGenericDriver::setMode(), and waitAuxHigh().

Referenced by send().

◆ writeParameters()

bool RH_E32::writeParameters ( Parameters params,
bool  save = false 
)
protected

Write radio configuration parameters from local memory to the radio. You can choose whether the parameter will be saved across power down or not

Parameters
[in]paramsReference to a Parameter structure containing the radio configuration parameters to be written to the radio.
[in]saveIf true, the parameters will be saved across power down in the radio
Returns
true if successful

References RH_E32::Parameters::head, ModeNormal, ModeSleep, and setOperatingMode().

Referenced by setBaudRate(), setDataRate(), setFrequency(), and setPower().


The documentation for this class was generated from the following files: