rn2903.h File Reference

Include dependency graph for rn2903.h:

Go to the source code of this file.

Data Structures
struct	_rn2903_context

Functions
rn2903_context	rn2903_init (unsigned int uart, unsigned int baudrate)
rn2903_context	rn2903_init_tty (const char *uart_tty, unsigned int baudrate)
void	rn2903_close (rn2903_context dev)
void	rn2903_set_response_wait_time (const rn2903_context dev, unsigned int wait_ms)
void	rn2903_set_response2_wait_time (const rn2903_context dev, unsigned int wait_ms)
bool	rn2903_data_available (const rn2903_context dev, unsigned int millis)
void	rn2903_drain (const rn2903_context dev)
RN2903_RESPONSE_T	rn2903_command (const rn2903_context dev, const char *cmd)
RN2903_RESPONSE_T	rn2903_command_with_arg (const rn2903_context dev, const char *cmd, const char *arg)
RN2903_RESPONSE_T	rn2903_waitfor_response (const rn2903_context dev, int wait_ms)
const char *	rn2903_get_response (const rn2903_context dev)
size_t	rn2903_get_response_len (const rn2903_context dev)
upm_result_t	rn2903_set_device_eui (const rn2903_context dev, const char *str)
upm_result_t	rn2903_get_device_eui (const rn2903_context dev)
upm_result_t	rn2903_set_application_eui (const rn2903_context dev, const char *str)
upm_result_t	rn2903_get_application_eui (const rn2903_context dev)
upm_result_t	rn2903_set_application_key (const rn2903_context dev, const char *str)
upm_result_t	rn2903_get_application_key (const rn2903_context dev)
upm_result_t	rn2903_set_device_addr (const rn2903_context dev, const char *str)
upm_result_t	rn2903_get_device_addr (const rn2903_context dev)
upm_result_t	rn2903_set_network_session_key (const rn2903_context dev, const char *str)
upm_result_t	rn2903_set_application_session_key (const rn2903_context dev, const char *str)
const char *	rn2903_to_hex (const rn2903_context dev, const char *src, int len)
const char *	rn2903_from_hex (const rn2903_context dev, const char *src)
RN2903_JOIN_STATUS_T	rn2903_join (const rn2903_context dev, RN2903_JOIN_TYPE_T type)
RN2903_MAC_TX_STATUS_T	rn2903_mac_tx (const rn2903_context dev, RN2903_MAC_MSG_TYPE_T type, int port, const char *payload)
RN2903_RESPONSE_T	rn2903_radio_tx (const rn2903_context dev, const char *payload)
RN2903_RESPONSE_T	rn2903_radio_rx (const rn2903_context dev, int window_size)
const char *	rn2903_get_hardware_eui (const rn2903_context dev)
upm_result_t	rn2903_update_mac_status (const rn2903_context dev)
uint16_t	rn2903_get_mac_status_word (const rn2903_context dev)
RN2903_MAC_STATUS_T	rn2903_get_mac_status (const rn2903_context dev)
upm_result_t	rn2903_mac_save (const rn2903_context dev)
upm_result_t	rn2903_mac_pause (const rn2903_context dev)
upm_result_t	rn2903_mac_resume (const rn2903_context dev)
upm_result_t	rn2903_reset (const rn2903_context dev)
upm_result_t	rn2903_mac_set_battery (const rn2903_context dev, int level)
void	rn2903_set_debug (const rn2903_context dev, bool enable)
int	rn2903_read (const rn2903_context dev, char *buffer, size_t len)
int	rn2903_write (const rn2903_context dev, const char *buffer, size_t len)
upm_result_t	rn2903_set_baudrate (const rn2903_context dev, unsigned int baudrate)
upm_result_t	rn2903_set_flow_control (const rn2903_context dev, RN2903_FLOW_CONTROL_T fc)
bool	rn2903_find (const rn2903_context dev, const char *str)
const char *	rn2903_get_radio_rx_payload (const rn2903_context dev)
bool	rn2903_autobaud (const rn2903_context dev, int retries)

Typedefs
typedef struct _rn2903_context *	rn2903_context

Function Documentation

rn2903_context rn2903_init	(	unsigned int	uart,
		unsigned int	baudrate
	)

RN2903 Initializer for UART operation using a UART index

Parameters

uart	Specify which uart to use
baudrate	Specify the baudrate to use. 57600 is the default baudrate of this device.

Returns

an initialized device context on success, NULL on error

Here is the call graph for this function:

rn2903_context rn2903_init_tty	(	const char *	uart_tty,
		unsigned int	baudrate
	)

RN2903 Initializer for UART operation using a filesystem tty path (eg. /dev/ttyUSB0)

Parameters

uart_tty	character string representing a filesystem path to a serial tty device
baudrate	Specify the baudrate to use. 57600 is the default baudrate of this device.

Returns

an initialized device context on success, NULL on error

Here is the call graph for this function:

Here is the caller graph for this function:

void rn2903_close

(

rn2903_context

dev

)

RN2903 sensor close function

Parameters

dev	Device context

Here is the caller graph for this function:

void rn2903_set_response_wait_time	(	const rn2903_context	dev,
		unsigned int	wait_ms
	)

Set the default time, in milliseconds, to wait for a response after sending a command. All commands return at least one response immediately after issuing the command. This delay sets the maximum amount of time to wait for it.

Parameters

dev	Device context
wait_ms	The response delay to set, in milliseconds.

Here is the caller graph for this function:

void rn2903_set_response2_wait_time	(	const rn2903_context	dev,
		unsigned int	wait_ms
	)

Set the default time, in milliseconds, to wait for the second response data to arrive. Some commands will have a second response emitted after the first response. This delay sets the maximum amount of time to wait for it.

Parameters

dev	Device context
wait_ms	The response delay to set, in milliseconds.

Here is the caller graph for this function:

bool rn2903_data_available	(	const rn2903_context	dev,
		unsigned int	millis
	)

Determine whether there is data available to be read. This function will wait up to "millis" milliseconds for data to become available.

Parameters

dev	Device context
millis	The number of milliseconds to wait for data to become available

Returns

true if data is available to be read, false otherwise

Here is the caller graph for this function:

void rn2903_drain

(

const rn2903_context

dev

)

Read and throw away any data currently available to be read. This is useful to avoid reading data that might have been the result of a previous command interfering with data you currently want to read.

Parameters

dev	Device context

Here is the call graph for this function:

Here is the caller graph for this function:

RN2903_RESPONSE_T rn2903_command	(	const rn2903_context	dev,
		const char *	cmd
	)

Send a command, wait for a response using rn2903_waitfor_response(), and return the status. The response itself will be stored internally, and can be retrieved using rm2903_get_response() and rn2903_get_response_len(). Every command will return at least one response, and this function will always wait for it and store it after sending the command.

Parameters

dev	Device context
cmd	A character string containing the command to send

Returns

One of the RN2903_RESPONSE_T values

Here is the call graph for this function:

Here is the caller graph for this function:

RN2903_RESPONSE_T rn2903_command_with_arg	(	const rn2903_context	dev,
		const char *	cmd,
		const char *	arg
	)

Build a command string with the supplied command and string argument. Then call rn2903_command() with the result, and return the result. This is just a convenience function.

Parameters

dev	Device context
cmd	A character string containing the command to send
arg	A string argument for the command

Returns

One of the RN2903_RESPONSE_T values

Here is the call graph for this function:

Here is the caller graph for this function:

RN2903_RESPONSE_T rn2903_waitfor_response	(	const rn2903_context	dev,
		int	wait_ms
	)

Wait up to wait_ms milliseconds for a response.

In the case of errors ("invalid_param" received, timeout occurred, or other UPM specific error), this will be indicated by the return value.

Otherwise, an "ok" or other data value will not be considered an error and will return RN2903_RESPONSE_OK. The response itself will be stored internally, and can be retrieved using rm2903_get_response() and rn2903_get_response_len().

NOTE: the response buffer is overwritten whenever this function is called, so if there is data in there that you need to save, copy it somewhere else before calling any other functions in this driver to be safe.

Parameters

dev	Device context
wait_ms	The maximum number of milliseconds to wait for a response.

Returns

One of the RN2903_RESPONSE_T values

Here is the call graph for this function:

Here is the caller graph for this function:

const char* rn2903_get_response

(

const rn2903_context

dev

)

Return a pointer to a string containing the last response. If you wish to save the response for later, you will need to copy it somewhere before calling rn2903_command(), rn2903_command_with_arg() or rn2903_waitfor_response(), as these functions will overwrite the internally stored response buffer each time they are called.

Parameters

dev	Device context

Returns

A const pointer to a string containing the last response.

Here is the caller graph for this function:

size_t rn2903_get_response_len

(

const rn2903_context

dev

)

Return the length in bytes of the string containing the last response. If you wish to save the response length for later, you will need to copy it somewhere before calling rn2903_command() or rn2903_waitfor_respnse(), as these functions will overwrite the internally stored response length each time they are called.

Parameters

dev	Device context

Returns

The length of the last response in bytes

Here is the caller graph for this function:

upm_result_t rn2903_set_device_eui	(	const rn2903_context	dev,
		const char *	str
	)

Set the MAC device EUI for LoRaWAN communications. The device EUI must be a hex encoded string of 16 bytes. This value must be set for LoRaWAN OTAA joining.

Parameters

dev	Device context
str	The 16-byte hex encoded device EUI

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_get_device_eui

(

const rn2903_context

dev

)

Retrieve the device EUI from the device. If this function succeeds, you can then use rn2903_get_response() to get the value.

Parameters

dev	Device context

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_set_application_eui	(	const rn2903_context	dev,
		const char *	str
	)

Set the MAC application EUI for LoRaWAN communications. The application EUI must be a hex encoded string of 16 bytes. This value must be set for LoRaWAN OTAA joining.

Parameters

dev	Device context
str	The 16-byte hex encoded application EUI

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_get_application_eui

(

const rn2903_context

dev

)

Retrieve the application EUI from the device. If this function succeeds, you can then use rn2903_get_response() to get the value.

Parameters

dev	Device context

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_set_application_key	(	const rn2903_context	dev,
		const char *	str
	)

Set the MAC application key for LoRaWAN communications. The application key must be a hex encoded string of 32 bytes. This value must be set for LoRaWAN OTAA joining.

Parameters

dev	Device context
str	The 32-byte hex encoded application key

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_get_application_key

(

const rn2903_context

dev

)

Retrieve the application key from the device. If this function succeeds, you can then use rn2903_get_response() to get the value.

Parameters

dev	Device context

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_set_device_addr	(	const rn2903_context	dev,
		const char *	str
	)

Set the MAC device address for LoRaWAN communications. The device address must be a hex encoded string of 8 bytes. This value must be set for LoRaWAN ABP joining.

For OTAA joining, this value will be overwritten once the join has completed, and therefore must not be set if performing an OTAA join.

Parameters

dev	Device context
str	The 8-byte hex encoded device address

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_get_device_addr

(

const rn2903_context

dev

)

Retrieve the device address from the device. If this function succeeds, you can then use rn2903_get_response() to get the value.

Parameters

dev	Device context

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_set_network_session_key	(	const rn2903_context	dev,
		const char *	str
	)

Set the MAC network session key for LoRaWAN communications. The network session key must be a hex encoded string of 32 bytes. This value must be set for LoRaWAN ABP joining. It it not possible to retrieve this key.

For OTAA joining, this value will be overwritten once the join has completed, and therefore must not be set if performing an OTAA join.

Parameters

dev	Device context
str	The 32-byte hex encoded network session key

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_set_application_session_key	(	const rn2903_context	dev,
		const char *	str
	)

Set the MAC application session key for LoRaWAN communications. The application session key must be a hex encoded string of 32 bytes. This value must be set for LoRaWAN ABP joining. It it not possible to retrieve this key.

For OTAA joining, this value will be overwritten once the join has completed, and therefore must not be set if performing an OTAA join.

Parameters

dev	Device context
str	The 32-byte hex encoded application session key

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

const char* rn2903_to_hex	(	const rn2903_context	dev,
		const char *	src,
		int	len
	)

Convert src into a hex byte string. All non-command related data such as keys, and payload sent to the device must be hex encoded. The buffers used for this conversion are managed internally, so do not call free() on the returned pointer. If you need to keep a copy of the resulting hex string, copy it somewhere before calling this function again.

Parameters

dev	Device context
src	A char pointer pointing to the byte array to encode
len	The length in bytes of the data to encode

Returns

A const pointer to the resulting hex string, or NULL if there was an error.

Here is the caller graph for this function:

const char* rn2903_from_hex	(	const rn2903_context	dev,
		const char *	src
	)

Convert a hex byte string into an array of bytes. The hex string must have a length (not including the 0 terminator) that is a multiple of two, and all characters in the string must be valid hex characters. The buffers used for this conversion are managed internally, so do not call free() on the returned pointer. If you need to keep a copy of the resulting data byte array, copy it somewhere before calling this function again. The length of the returned data will be the length of the hex source string divided by 2, with a 0 byte terminator at the end in case a text string is being decoded.

Parameters

dev	Device context

Returns

A const pointer to the resulting data string, or NULL if there was an error

Here is the caller graph for this function:

RN2903_JOIN_STATUS_T rn2903_join	(	const rn2903_context	dev,
		RN2903_JOIN_TYPE_T	type
	)

Join a LoRaWAN network. There are two types of joins possible

• Over The Air Activation (OTAA) and Activation by Personalization (ABP). Each join method requires that certain items have been configured first.

For OTAA activation, the Device Extended Unique Identifier (EUI), the Application EUI, and Application Key must be set.

For ABP activation, The Device Address, Network Session Key, and the Application Session Key must be set.

Parameters

dev	Device context
type	The LoRaWAN activation type, one of the RN2903_JOIN_TYPE_T values

Returns

The status of the join, one of the RN2903_JOIN_STATUS_T values

Here is the call graph for this function:

Here is the caller graph for this function:

RN2903_MAC_TX_STATUS_T rn2903_mac_tx	(	const rn2903_context	dev,
		RN2903_MAC_MSG_TYPE_T	type,
		int	port,
		const char *	payload
	)

Transmit a packet in a LoRaWAN network. You must already be joined to a LoRaWAN network for this command to succeed, and the MAC stack must be in the idle (RN2903_MAC_STAT_IDLE) state.

The packet payload must be a valid 0-terminated hex encoded string.

There is the possibility of receiving a downlink message after transmitting a packet. If this occurs, this function will return RN2903_MAC_TX_STATUS_RX_RECEIVED, and the returned data will be stored in the response buffer. NOTE: calling pretty much any function that issues commands to the device will overwrite the response buffer, so save a copy of it if you need it before calling other functions.

Parameters

dev	Device context
type	The type of message to send - confirmed or unconfirmed. One of the RN2903_MAC_MSG_TYPE_T values.
port	An integer in the range 1-223
payload	A 0-terminated, hex encoded string that makes up the payload of the message

Returns

The status of the transmit request, one of the RN2903_MAC_TX_STATUS_T values

Here is the call graph for this function:

Here is the caller graph for this function:

RN2903_RESPONSE_T rn2903_radio_tx	(	const rn2903_context	dev,
		const char *	payload
	)

Transmit a packet. This method uses the radio directly without the LoRaWAN stack running. For this reason, you must call rn2903_mac_pause() before trying to transmit using this function. You should also configure any parameters (frequency, etc), before calling this function.

Parameters

dev	Device context
payload	A 0-terminated, hex encoded string that makes up the payload of the message

Returns

The status of the transmit request, one of the RN2903_RESPONSE_T values

Here is the call graph for this function:

Here is the caller graph for this function:

RN2903_RESPONSE_T rn2903_radio_rx	(	const rn2903_context	dev,
		int	window_size
	)

Receive a packet. This method uses the radio directly without the LoRaWAN stack running. For this reason, you must call rn2903_mac_pause() before trying to receive using this function. You should also configure any parameters (frequency, etc) to match the transmitter before calling this function.

Parameters

dev	Device context
window_size	An integer that represents the number of symbols to wait for (lora) or the maximum number of milliseconds to wait (fsk). This parameter is passed to the "radio rx" command. Passing 0 causes the radio to enter continuous receive mode which will return when either a packet is received, or the radio watchdog timer expires. See the RN2903 Command Reference for details.

Returns

The status of the transmit request, one of the RN2903_RESPONSE_T values

Here is the call graph for this function:

Here is the caller graph for this function:

const char* rn2903_get_hardware_eui

(

const rn2903_context

dev

)

Return the Hardware Extended Unique Identifier. The is a 16 byte hex encoded string representing the 64b hardware EUI. This value cannot be changed, and is globally unique to each device. It is obtained from the device at initialization time.

Parameters

dev	Device context

Returns

A const string pointer to the hex encoded Hardware EUI

Here is the caller graph for this function:

upm_result_t rn2903_update_mac_status

(

const rn2903_context

dev

)

Retrieve the device MAC status, decode it, and store it internally. This function must be called prior to calling rn2903_get_mac_status_word() or rn2903_get_mac_status().

Parameters

dev	Device context

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

uint16_t rn2903_get_mac_status_word

(

const rn2903_context

dev

)

Retrieve the MAC status word. rn2903_update_mac_status() must have been called prior to calling this function.

Parameters

dev	Device context

Returns

The MAC status word. This is a bitmask of RN2903_MAC_STATUS_BITS_T bits.

Here is the caller graph for this function:

RN2903_MAC_STATUS_T rn2903_get_mac_status

(

const rn2903_context

dev

)

Retrieve the MAC status. rn2903_update_mac_status() must have been called prior to calling this function. The MAC status is a bitfield embedded in the mac_status_word. It provides information on the status of the internal MAC state machine.

Parameters

dev	Device context

Returns

The MAC status, one of the RN2903_MAC_STATUS_T values.

Here is the caller graph for this function:

upm_result_t rn2903_mac_save

(

const rn2903_context

dev

)

Save the configurable device values to EEPROM. These values will be reloaded automatically on a reset or power up.

The data that can be saved are: deveui, appeui, appkey, nwkskey (Network Session Key), appskey, devaddr, channels, upctr (Uplink Counter), dnctr (Downlink Counter), adr (automatic data-rate) state, and rx2 (the RX2 receive window parameters).

Parameters

dev	Device context

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_mac_pause

(

const rn2903_context

dev

)

Pause the MAC LoRaWAN stack. This device can operate in one of two modes.

The most common mode is used to join and participate in a LoRaWAN network as a Class A End Device. This is handled by the MAC LoRaWAN stack on the device dealing with the details of LoRaWAN participation automatically.

The other mode disables MAC LoRaWAN stack functionality and allows you to issue commands directly to the radio to set frequencies, data rates, modulation and many other parameters.

Calling this function disables the MAC LoRaWAN stack and allows you to issue radio commands that are otherwise handled automatically.

When pausing, the maximum allowable pause time in milliseconds will be returned in the response buffer. You can grab this value by calling rn2903_get_response() after this function completes successfully.

When the MAC is idle (rn2903_get_mac_status()), you can pause indefinitely.

Parameters

dev	Device context

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_mac_resume

(

const rn2903_context

dev

)

Resume the MAC LoRaWAN stack. Call this to resume MAC LoRaWAN operation after having called rn2903_mac_pause(), to resume participation in a LoRaWAN network.

Parameters

dev	Device context

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_reset

(

const rn2903_context

dev

)

Reset the device. Any configuration is lost, as well as the current join status. This method also calls rn2903_set_baudrate() after the reset to re-establish communications with the device in the event you are not using the default baudrate (which the device will revert to after a reset).

Parameters

dev	Device context

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_mac_set_battery	(	const rn2903_context	dev,
		int	level
	)

LoRaWAN communications allows for the reporting of current battery charge remaining to the LoRaWAN gateway/network server. This function allows you to specify the value that should be reported.

The valid values are from 0 to 255. 0 = using external power 1(low) to 254(high) = battery power 255 = unable to measure battery level

Parameters

dev	Device context
level	The battery level value from 0-255

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

void rn2903_set_debug	(	const rn2903_context	dev,
		bool	enable
	)

Enable debugging. If enabled, commands will be printed out before being sent to the device. Any responses will be printed out after retrieval. Other miscellaneous debug output will also be printed.

Parameters

dev	Device context
enable	true to enable debugging, false otherwise

Here is the caller graph for this function:

int rn2903_read	(	const rn2903_context	dev,
		char *	buffer,
		size_t	len
	)

Read character data from the device

Parameters

dev	Device context
buffer	The character buffer to read data into
len	The maximum size of the buffer

Returns

The number of bytes successfully read, or -1 on error

Here is the caller graph for this function:

int rn2903_write	(	const rn2903_context	dev,
		const char *	buffer,
		size_t	len
	)

Write character data to the device

Parameters

dev	Device context
buffer	The character buffer containing data to write
len	The number of bytes to write

Returns

The number of bytes successfully written, or -1 on error

Here is the caller graph for this function:

upm_result_t rn2903_set_baudrate	(	const rn2903_context	dev,
		unsigned int	baudrate
	)

Set the baudrate of the device. Auto-bauding is currently only supported on Linux (due to the need to send a break signal) and only on a recent MRAA which supports it (> 1.6.1). If on a non-linux OS, you should not try to change the baudrate to anything other than the default 57600 or you will lose control of the device.

Parameters

dev	Device context
baudrate	The baud rate to set for the device

Returns

UPM result

Here is the call graph for this function:

Here is the caller graph for this function:

upm_result_t rn2903_set_flow_control	(	const rn2903_context	dev,
		RN2903_FLOW_CONTROL_T	fc
	)

Set a flow control method for the UART. By default, during initialization, flow control is disabled. The device MAY support hardware flow control, but MRAA does not (at least for UART numbers), so we can't either. We leave the option here though so that if you are using a TTY (as opposed to a UART instance) it might work if the device is also configured to use hardware flow control.

Parameters

dev	Device context
fc	One of the RN2903_FLOW_CONTROL_T values

Returns

the UPM result

Here is the caller graph for this function:

bool rn2903_find	(	const rn2903_context	dev,
		const char *	str
	)

This is a utility function that can be used to indicate if a given string is present at the beginning of the response buffer. The search is case sensitive.

Parameters

dev	Device context
str	The 0 teminated string to search for

Returns

true if the string was found at the beginning of the response buffer, false otherwise

Here is the caller graph for this function:

const char* rn2903_get_radio_rx_payload

(

const rn2903_context

dev

)

This is a utility function that can be used to return a pointer to the location in the response buffer where the hex encoded payload starts for radio_rx messages received.

Parameters

dev	Device context

Returns

A pointer to the start of the hex payload in the response buffer, or NULL if the response buffer does not contain a radio_rx sentence.

Here is the call graph for this function:

Here is the caller graph for this function:

bool rn2903_autobaud	(	const rn2903_context	dev,
		int	retries
	)

This function attempts to sync the device to the current baudrate. It tries retries times, to send an autobaud sequence to the device and run a test command.

Parameters

dev	Device context
retries	The number of times to retry autobaud detection

Returns

true if the test command succeeded, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

Typedef Documentation

typedef struct _rn2903_context * rn2903_context

Device context