rn2xx3.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2017 Inria
3  *
4  * This file is subject to the terms and conditions of the GNU Lesser
5  * General Public License v2.1. See the file LICENSE in the top level
6  * directory for more details.
7  */
8 
21 #ifndef RN2XX3_H
22 #define RN2XX3_H
23 
24 #include <stdint.h>
25 
26 #include "xtimer.h"
27 #include "periph/uart.h"
28 #include "periph/gpio.h"
29 #include "net/netdev.h"
30 
31 #include "net/loramac.h"
32 
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36 
40 #define RN2XX3_MAX_BUF (40U)
41 
47 #define RN2XX3_RX_MAX_BUF (250U)
48 
52 #define RN2XX3_REPLY_DELAY_TIMEOUT (60U)
53 
57 #define RN2XX3_SLEEP_MIN (100U)
58 
62 #ifndef RN2XX3_DEFAULT_SLEEP
63 #define RN2XX3_DEFAULT_SLEEP (5000U)
64 #endif
65 
66 #if defined(MODULE_RN2903)
67 #define RN2XX3_FREQ_BAND (915U)
68 #elif defined(MODULE_RN2483)
69 #define RN2XX3_FREQ_BAND (868U)
70 #else
71 #error "Unsupported module type, use either RN2483 or RN2903"
72 #endif
73 
77 enum {
81  /* all other error codes */
93  /* all other reply codes */
102 };
103 
107 enum {
116 };
117 
121 typedef struct {
122  uint32_t rx2_freq;
124  uint8_t tx_port;
126  uint8_t rx_port;
128 
132 typedef struct {
134  uint32_t baudrate;
135  gpio_t pin_reset;
138 
142 typedef struct {
144  /* device driver specific fields */
148  /* values for the UART TX state machine */
149  char cmd_buf[RN2XX3_MAX_BUF];
152  uint8_t int_state;
154  /* buffer and synchronization for command responses */
157  char resp_buf[RN2XX3_MAX_BUF];
158  uint16_t resp_size;
159  uint8_t resp_done;
161  /* buffer for RX messages */
162  char rx_tmp_buf[2];
165  uint8_t rx_buf[RN2XX3_RX_MAX_BUF];
166  uint16_t rx_size;
168  /* timers */
170  uint32_t sleep;
171 } rn2xx3_t;
172 
179 void rn2xx3_setup(rn2xx3_t *dev, const rn2xx3_params_t *params);
180 
190 int rn2xx3_init(rn2xx3_t *dev);
191 
203 int rn2xx3_sys_reset(rn2xx3_t *dev);
204 
220 
229  int rn2xx3_sys_sleep(rn2xx3_t *dev);
230 
239 int rn2xx3_mac_init(rn2xx3_t *dev);
240 
260 int rn2xx3_write_cmd(rn2xx3_t *dev);
261 
273 
291 
307 int rn2xx3_wait_reply(rn2xx3_t *dev, uint8_t timeout);
308 
326 int rn2xx3_mac_tx(rn2xx3_t *dev, uint8_t *payload, uint8_t payload_len);
327 
343 
356 int rn2xx3_mac_save(rn2xx3_t *dev);
357 
358 /* Get/Set functions definitions */
359 
368 void rn2xx3_mac_get_deveui(rn2xx3_t *dev, uint8_t *eui);
369 
378 void rn2xx3_mac_set_deveui(rn2xx3_t *dev, const uint8_t *eui);
379 
388 void rn2xx3_mac_get_appeui(rn2xx3_t *dev, uint8_t *eui);
389 
398 void rn2xx3_mac_set_appeui(rn2xx3_t *dev, const uint8_t *eui);
399 
408 void rn2xx3_mac_set_appkey(rn2xx3_t *dev, const uint8_t *key);
409 
418 void rn2xx3_mac_set_appskey(rn2xx3_t *dev, const uint8_t *key);
419 
428 void rn2xx3_mac_set_nwkskey(rn2xx3_t *dev, const uint8_t *key);
429 
438 void rn2xx3_mac_get_devaddr(rn2xx3_t *dev, uint8_t *addr);
439 
448 void rn2xx3_mac_set_devaddr(rn2xx3_t *dev, const uint8_t *addr);
449 
458 
466 
475 
483 
491  uint16_t rn2xx3_mac_get_band(rn2xx3_t *dev);
492 
501 bool rn2xx3_mac_get_adr(rn2xx3_t *dev);
502 
509 void rn2xx3_mac_set_adr(rn2xx3_t *dev, bool adr);
510 
522 void rn2xx3_mac_set_battery(rn2xx3_t *dev, uint8_t battery);
523 
531 uint8_t rn2xx3_mac_get_retx(rn2xx3_t *dev);
532 
539 void rn2xx3_mac_set_retx(rn2xx3_t *dev, uint8_t retx);
540 
547 void rn2xx3_mac_set_linkchk_interval(rn2xx3_t *dev, uint16_t linkchk);
548 
556 uint16_t rn2xx3_mac_get_rx1_delay(rn2xx3_t *dev);
557 
564 void rn2xx3_mac_set_rx1_delay(rn2xx3_t *dev, uint16_t rx1);
565 
573 uint16_t rn2xx3_mac_get_rx2_delay(rn2xx3_t *dev);
574 
582 bool rn2xx3_mac_get_ar(rn2xx3_t *dev);
583 
590 void rn2xx3_mac_set_ar(rn2xx3_t *dev, bool ar);
591 
600 
608 
616 uint32_t rn2xx3_mac_get_rx2_freq(rn2xx3_t *dev);
617 
624 void rn2xx3_mac_set_rx2_freq(rn2xx3_t *dev, uint32_t freq);
625 
633 uint8_t rn2xx3_mac_get_tx_port(rn2xx3_t *dev);
634 
641 void rn2xx3_mac_set_tx_port(rn2xx3_t *dev, uint8_t port);
642 
651 
659 
667 uint8_t rn2xx3_mac_get_rx_port(rn2xx3_t *dev);
668 
675 void rn2xx3_sys_set_sleep_duration(rn2xx3_t *dev, uint32_t sleep);
676 
677 #ifdef __cplusplus
678 }
679 #endif
680 
681 #endif /* RN2XX3_H */
682 
waiting for mac rx port
Definition: rn2xx3.h:114
uint8_t rx_port
RX port (between 1 and 223)
Definition: rn2xx3.h:126
uint16_t rn2xx3_mac_get_rx1_delay(rn2xx3_t *dev)
Gets the rn2xx3 LoRaMAC interval delay before the first reception window (in ms)
uint8_t rn2xx3_mac_get_rx_port(rn2xx3_t *dev)
Parses the response buffer to get the LoRaWAN RX port.
Unknown reply.
Definition: rn2xx3.h:101
int rn2xx3_write_cmd_no_wait(rn2xx3_t *dev)
Writes a command to the RN2XX3 device but don&#39;t wait for timeout or response.
Low-level UART peripheral driver interface definition.
#define RN2XX3_RX_MAX_BUF
Maximum length of an RX message.
Definition: rn2xx3.h:47
uint8_t rn2xx3_mac_get_retx(rn2xx3_t *dev)
Gets the rn2xx3 LoRaMAC uplink retransmission retries number.
void rn2xx3_mac_set_tx_mode(rn2xx3_t *dev, loramac_tx_mode_t mode)
Sets the rn2xx3 LoRaMAC TX mode.
void rn2xx3_mac_set_tx_power(rn2xx3_t *dev, loramac_tx_pwr_idx_t power)
Sets the rn2xx3 LoRaMAC transmission power index.
void rn2xx3_mac_set_rx1_delay(rn2xx3_t *dev, uint16_t rx1)
Sets the rn2xx3 LoRaMAC interval delay before the first reception window (in ms)
void rn2xx3_mac_set_appeui(rn2xx3_t *dev, const uint8_t *eui)
Sets the rn2xx3 LoRaMAC application EUI.
Frame counter rolled over.
Definition: rn2xx3.h:87
MAC transmission successful.
Definition: rn2xx3.h:94
MAC was paused.
Definition: rn2xx3.h:89
RN2483/RN2903 device descriptor.
Definition: rn2xx3.h:142
int rn2xx3_sys_factory_reset(rn2xx3_t *dev)
Performs a factory reset of the module.
void rn2xx3_setup(rn2xx3_t *dev, const rn2xx3_params_t *params)
Prepares the given RN2XX3 device.
bool rn2xx3_mac_get_adr(rn2xx3_t *dev)
Checks if the rn2xx3 LoRaMAC adaptive datarate is enabled/disabled.
mutex_t cmd_lock
mutex to allow only one command at a time
Definition: rn2xx3.h:150
Keys not configured ("mac join" command)
Definition: rn2xx3.h:91
Low-level GPIO peripheral driver interface definitions.
unsigned int uart_t
Define default UART type identifier.
Definition: uart.h:78
xtimer_t sleep_timer
Timer used to count module sleep time.
Definition: rn2xx3.h:169
void rn2xx3_mac_set_nwkskey(rn2xx3_t *dev, const uint8_t *key)
Sets the rn2xx3 LoRaMAC network session key.
netdev_t netdev
Netdev parent struct.
Definition: rn2xx3.h:143
Configuration parameters for RN2483/RN2903 devices.
Definition: rn2xx3.h:132
loramac_dr_idx_t rn2xx3_mac_get_rx2_dr(rn2xx3_t *dev)
Gets the rn2xx3 LoRaMAC datarate used for second receive window.
Join procedure failed.
Definition: rn2xx3.h:99
Definitions low-level network driver interface.
void rn2xx3_mac_get_deveui(rn2xx3_t *dev, uint8_t *eui)
Gets the rn2xx3 LoRaMAC device EUI.
void rn2xx3_mac_set_devaddr(rn2xx3_t *dev, const uint8_t *addr)
Sets the rn2xx3 LoRaMAC device address.
Command returned data.
Definition: rn2xx3.h:79
MAC is not in Idle state.
Definition: rn2xx3.h:88
waiting for incoming commands
Definition: rn2xx3.h:110
uint32_t sleep
module sleep duration
Definition: rn2xx3.h:170
void rn2xx3_mac_set_battery(rn2xx3_t *dev, uint8_t battery)
Sets the rn2xx3 battery level measured by the end device.
void rn2xx3_mac_set_dr(rn2xx3_t *dev, loramac_dr_idx_t dr)
Sets the rn2xx3 LoRaMAC datarate.
Command timeout.
Definition: rn2xx3.h:80
uart_t uart
UART interfaced the device is connected to.
Definition: rn2xx3.h:133
uint16_t rx_size
counter for received char in RX
Definition: rn2xx3.h:166
Device mac initialization failed.
Definition: rn2xx3.h:82
waiting for mac tx reply
Definition: rn2xx3.h:113
uint32_t rn2xx3_mac_get_rx2_freq(rn2xx3_t *dev)
Gets the rn2xx3 LoRaMAC frequency used during second receive window (in Hz)
#define RN2XX3_MAX_BUF
Maximum length of an exchanged messages with commands.
Definition: rn2xx3.h:40
loramac_tx_mode_t tx_mode
TX mode, either confirmable of unconfirmable.
Definition: rn2xx3.h:125
int rn2xx3_sys_sleep(rn2xx3_t *dev)
Puts the RN2XX2 device in sleep mode.
loramac_tx_pwr_idx_t rn2xx3_mac_get_tx_power(rn2xx3_t *dev)
Gets the rn2xx3 LoRaMAC TX radio power index.
uint16_t rn2xx3_mac_get_rx2_delay(rn2xx3_t *dev)
Gets the rn2xx3 LoRaMAC interval delay before the second reception window (in ms) ...
uint8_t tx_port
Application TX port (between 1 and 223)
Definition: rn2xx3.h:124
void rn2xx3_mac_set_linkchk_interval(rn2xx3_t *dev, uint16_t linkchk)
Sets the rn2xx3 LoRaMAC link check interval (in seconds)
uint16_t rn2xx3_mac_get_band(rn2xx3_t *dev)
Gets the rn2xx3 LoRaMAC frequency band in operation.
int rn2xx3_mac_join_network(rn2xx3_t *dev, loramac_join_mode_t mode)
Starts network activation procedure.
int rn2xx3_wait_response(rn2xx3_t *dev)
Waits for a response to a command from the device.
waiting for mac rx message
Definition: rn2xx3.h:115
Join procedure successful.
Definition: rn2xx3.h:98
Command is valid.
Definition: rn2xx3.h:78
All channels are busy.
Definition: rn2xx3.h:85
Data received from server.
Definition: rn2xx3.h:97
loramac_settings_t loramac
loramac communication settings
Definition: rn2xx3.h:146
void rn2xx3_sys_set_sleep_duration(rn2xx3_t *dev, uint32_t sleep)
Sets the rn2xx3 sleep mode duration (in ms)
int rn2xx3_init(rn2xx3_t *dev)
Initializes the RN2XX3 device.
Structure to hold driver state.
Definition: netdev.h:283
void rn2xx3_mac_set_rx2_dr(rn2xx3_t *dev, loramac_dr_idx_t dr)
Sets the rn2xx3 LoRaMAC datarate used for second receive window.
void rn2xx3_mac_set_appkey(rn2xx3_t *dev, const uint8_t *key)
Sets the rn2xx3 LoRaMAC application key.
int rn2xx3_write_cmd(rn2xx3_t *dev)
Writes a command to the RN2XX3 device.
xtimer interface definitions
void rn2xx3_mac_set_retx(rn2xx3_t *dev, uint8_t retx)
Sets the rn2xx3 LoRaMAC uplink retransmission retries number.
void rn2xx3_mac_set_appskey(rn2xx3_t *dev, const uint8_t *key)
Sets the rn2xx3 LoRaMAC application session key.
the device is being reset or initialized
Definition: rn2xx3.h:108
uint8_t rn2xx3_mac_get_tx_port(rn2xx3_t *dev)
Gets the rn2xx3 LoRaMAC TX port.
LoRaMAC header definitions.
loramac_tx_mode_t rn2xx3_mac_get_tx_mode(rn2xx3_t *dev)
Gets the rn2xx3 LoRaMAC TX mode.
loramac_tx_pwr_idx_t
LoRaMAC transmission power indexes.
Definition: loramac.h:558
int rn2xx3_mac_tx(rn2xx3_t *dev, uint8_t *payload, uint8_t payload_len)
Sends data to LoRaWAN server.
Application payload too large.
Definition: rn2xx3.h:96
Wrong command given.
Definition: rn2xx3.h:83
Device is in Silent Immediately state.
Definition: rn2xx3.h:86
loramac_tx_mode_t
LoRaMAC transmission mode.
Definition: loramac.h:360
void rn2xx3_mac_get_appeui(rn2xx3_t *dev, uint8_t *eui)
Gets the rn2xx3 LoRaMAC application EUI.
Wrong payload given.
Definition: rn2xx3.h:90
No MAC reply received from server.
Definition: rn2xx3.h:100
void rn2xx3_mac_set_ar(rn2xx3_t *dev, bool ar)
Enables/disables LoRaMAC rn2xx3 MAC automatic reply state.
LoRaMAC communication settings.
Definition: rn2xx3.h:121
uint32_t baudrate
baudrate to use
Definition: rn2xx3.h:134
void rn2xx3_mac_set_adr(rn2xx3_t *dev, bool adr)
Enables/disables the rn2xx3 LoRaMAC adaptive datarate.
int rn2xx3_mac_init(rn2xx3_t *dev)
Initializes the RN2XX3 device MAC layer.
bool rn2xx3_mac_get_ar(rn2xx3_t *dev)
Checks the rn2xx3 LoRaMAC automatic reply state.
waiting command response
Definition: rn2xx3.h:109
void rn2xx3_mac_set_tx_port(rn2xx3_t *dev, uint8_t port)
Sets the rn2xx3 LoRaMAC TX port.
loramac_join_mode_t
LoRaMAC network join procedure type.
Definition: loramac.h:352
loramac_dr_idx_t rx2_dr
Datarate used for second receive window.
Definition: rn2xx3.h:123
uint8_t int_state
current state of the device
Definition: rn2xx3.h:152
loramac_dr_idx_t rn2xx3_mac_get_dr(rn2xx3_t *dev)
Gets the rn2xx3 LoRaMAC datarate.
int rn2xx3_sys_reset(rn2xx3_t *dev)
Restarts the RN2XX2 device.
loramac_dr_idx_t
LoRaMAC datarate indexes.
Definition: loramac.h:371
MAC transmission failed.
Definition: rn2xx3.h:95
xtimer timer structure
Definition: xtimer.h:80
Mutex structure.
Definition: mutex.h:37
void rn2xx3_mac_set_rx2_freq(rn2xx3_t *dev, uint32_t freq)
Sets the rn2xx3 LoRaMAC frequency used during second receive window (in Hz)
rn2xx3_params_t p
configuration parameters
Definition: rn2xx3.h:145
uint16_t resp_size
counter for received char in response
Definition: rn2xx3.h:158
sleep mode
Definition: rn2xx3.h:111
mutex_t resp_lock
mutex for waiting for command response
Definition: rn2xx3.h:155
Failure because device is in sleep mode.
Definition: rn2xx3.h:92
uint8_t resp_done
check if response has completed
Definition: rn2xx3.h:159
Network is not joined.
Definition: rn2xx3.h:84
void rn2xx3_mac_set_deveui(rn2xx3_t *dev, const uint8_t *eui)
Sets the rn2xx3 LoRaMAC device EUI.
void rn2xx3_mac_get_devaddr(rn2xx3_t *dev, uint8_t *addr)
Gets the rn2xx3 LoRaMAC device address.
gpio_t pin_reset
GPIO pin that is connected to the STATUS pin set to GPIO_UNDEF if not used.
Definition: rn2xx3.h:135
int rn2xx3_mac_save(rn2xx3_t *dev)
Saves current LoRaMAC configuration to internal EEPROM.
uint32_t rx2_freq
Center frequency used for second receive window.
Definition: rn2xx3.h:122
int rn2xx3_wait_reply(rn2xx3_t *dev, uint8_t timeout)
Waits for a reply from the LoRaWAN network.
waiting for mac join procedure reply
Definition: rn2xx3.h:112