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:

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	~RHGenericDriver ()
	Generic destructor to prevent warnings when objects are dynamically allocated.

virtual bool	init ()

virtual bool	available ()=0

virtual bool	recv (uint8_t buf, uint8_t len)=0

virtual bool	send (const uint8_t *data, uint8_t len)=0

virtual uint8_t	maxMessageLength ()=0

virtual void	waitAvailable (uint16_t polldelay=0)

virtual bool	waitPacketSent ()

virtual bool	waitPacketSent (uint16_t timeout)

virtual bool	waitAvailableTimeout (uint16_t timeout, uint16_t polldelay=0)

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 ()

virtual int16_t	lastRssi ()

virtual RHMode	mode ()

virtual void	setMode (RHMode mode)
	Sets the operating mode of the transport. More...

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 the 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:

5 octets HEADER: (LENGTH, TO, FROM, ID, FLAGS)
0 to 53 octets DATA

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      E32
    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 connection, you can initialise the serial port and RH_E32 like this:

SoftwareSerial mySerial(7, 6);

RH_E32 driver(&mySerial, 4, 5, 8);

RH_E32

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

Definition: RH_E32.h:224

For Adafruit M0 Feather:

    Feather      E32
    GND----------GND   (ground in)
    3V-----------VCC   (3.3V in)
pin D5-----------M0    (mode control pin input to radio)
pin D6-----------M1    (mode control pin input to radio)
pin D1/Tx--------RXD   (serial data input from M0 to radio)
pin D0/Rx--------TXD   (serial data output from radio to M0)
pin D9-----------AUX   (Aux pin output from radio to M0)

With this connection, you can initialise serial port 1 and RH_E32 like this:

RH_E32 driver(&Serial1, 5, 6, 9);

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:

Mysterious crashes and restarts
Changes in behaviour when seemingly unrelated changes are made (such as adding print() statements)
Hanging
Output from Serial.print() not appearing

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 cautious 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

enum RH_E32::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

enum RH_E32::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]	s	Reference to the SoftwareSerial or HardwareSerial port used to connect to the radio
[in]	m0_pin	Pin number of the Arduino pin that connects to the radio M0 input
[in]	m1_pin	Pin number of the Arduino pin that connects to the radio M1 input
[in]	aux_pin	Pin 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.

◆ clearRxBuf()

void RH_E32::clearRxBuf ( )

protected

Clear our local receive buffer For internal use only

◆ 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

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

◆ 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] params Reference to a Parameter structure which will be filled if successful

Returns: true if successful

◆ 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]	buf	Location to copy the received message
[in,out]	len	Pointer to the number of octets available in buf. The number be reset to the actual number of octets copied.

Returns: true if a valid message was copied to buf

Implements RHGenericDriver.

◆ reset()

bool RH_E32::reset ( )

protected

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

Returns: true if successful

◆ 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]	data	Array of data to be sent
[in]	len	Number 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.

◆ 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]	rate	A valid baud rate from the BaudRate enum
[in]	parity	A valid parity from the PArity enum

Returns: true if successful

◆ setDataRate()

bool RH_E32::setDataRate ( DataRate rate )

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

Parameters

[in] rate A valid data rate from the DataRate enum

Returns: true if successful

◆ setFrequency()

bool RH_E32::setFrequency ( uint16_t frequency )

Sets the tarnsmitter and receiver frequency.

Parameters

[in] frequency Desired frequency in MHx from 410 to 441 MHz inclusive

Returns: true if successful

◆ setOperatingMode()

void RH_E32::setOperatingMode ( OperatingMode mode )

protected

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

◆ setPower()

bool RH_E32::setPower ( PowerLevel level )

Sets the transmitter power output

Parameters

[in] level A valid power setting from the Power enum

Returns: true if successful

◆ validateRxBuf()

void RH_E32::validateRxBuf ( )

protected

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

◆ waitAuxHigh()

void RH_E32::waitAuxHigh ( )

protected

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

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

◆ 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]	params	Reference to a Parameter structure containing the radio configuration parameters to be written to the radio.
[in]	save	If true, the parameters will be saved across power down in the radio

Returns: true if successful

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

RH_E32.h

Classes

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ BaudRate

◆ DataRate

◆ OperatingMode

Constructor & Destructor Documentation

◆ RH_E32()

Member Function Documentation

◆ available()

◆ clearRxBuf()

◆ getVersion()

◆ init()

◆ maxMessageLength()

◆ readParameters()

◆ recv()

◆ reset()

◆ send()

◆ setBaudRate()

◆ setDataRate()

◆ setFrequency()

◆ setOperatingMode()

◆ setPower()

◆ validateRxBuf()

◆ waitAuxHigh()

◆ waitAuxLow()

◆ waitPacketSent()

◆ writeParameters()