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 
67 #ifndef CONFIG_RN2XX3_DEFAULT_SLEEP
68 #define CONFIG_RN2XX3_DEFAULT_SLEEP (5000U)
69 #endif
70 
72 #if defined(MODULE_RN2903)
73 #define RN2XX3_FREQ_BAND (915U)
74 #elif defined(MODULE_RN2483)
75 #define RN2XX3_FREQ_BAND (868U)
76 #else
77 #error "Unsupported module type, use either RN2483 or RN2903"
78 #endif
79 
83 enum {
87  /* all other error codes */
99  /* all other reply codes */
108 };
109 
113 enum {
122 };
123 
127 typedef struct {
128  uint32_t rx2_freq;
130  uint8_t tx_port;
132  uint8_t rx_port;
134 
138 typedef struct {
140  uint32_t baudrate;
141  gpio_t pin_reset;
144 
148 typedef struct {
150  /* device driver specific fields */
154  /* values for the UART TX state machine */
155  char cmd_buf[RN2XX3_MAX_BUF];
158  uint8_t int_state;
160  /* buffer and synchronization for command responses */
163  char resp_buf[RN2XX3_MAX_BUF];
164  uint16_t resp_size;
165  uint8_t resp_done;
167  /* buffer for RX messages */
168  char rx_tmp_buf[2];
171  uint8_t rx_buf[RN2XX3_RX_MAX_BUF];
172  uint16_t rx_size;
174  /* timers */
176  uint32_t sleep;
177 } rn2xx3_t;
178 
185 void rn2xx3_setup(rn2xx3_t *dev, const rn2xx3_params_t *params);
186 
196 int rn2xx3_init(rn2xx3_t *dev);
197 
209 int rn2xx3_sys_reset(rn2xx3_t *dev);
210 
226 
235  int rn2xx3_sys_sleep(rn2xx3_t *dev);
236 
245 int rn2xx3_mac_init(rn2xx3_t *dev);
246 
266 int rn2xx3_write_cmd(rn2xx3_t *dev);
267 
279 
297 
313 int rn2xx3_wait_reply(rn2xx3_t *dev, uint8_t timeout);
314 
332 int rn2xx3_mac_tx(rn2xx3_t *dev, uint8_t *payload, uint8_t payload_len);
333 
349 
362 int rn2xx3_mac_save(rn2xx3_t *dev);
363 
364 /* Get/Set functions definitions */
365 
374 void rn2xx3_mac_get_deveui(rn2xx3_t *dev, uint8_t *eui);
375 
384 void rn2xx3_mac_set_deveui(rn2xx3_t *dev, const uint8_t *eui);
385 
394 void rn2xx3_mac_get_appeui(rn2xx3_t *dev, uint8_t *eui);
395 
404 void rn2xx3_mac_set_appeui(rn2xx3_t *dev, const uint8_t *eui);
405 
414 void rn2xx3_mac_set_appkey(rn2xx3_t *dev, const uint8_t *key);
415 
424 void rn2xx3_mac_set_appskey(rn2xx3_t *dev, const uint8_t *key);
425 
434 void rn2xx3_mac_set_nwkskey(rn2xx3_t *dev, const uint8_t *key);
435 
444 void rn2xx3_mac_get_devaddr(rn2xx3_t *dev, uint8_t *addr);
445 
454 void rn2xx3_mac_set_devaddr(rn2xx3_t *dev, const uint8_t *addr);
455 
464 
472 
481 
489 
497  uint16_t rn2xx3_mac_get_band(rn2xx3_t *dev);
498 
507 bool rn2xx3_mac_get_adr(rn2xx3_t *dev);
508 
515 void rn2xx3_mac_set_adr(rn2xx3_t *dev, bool adr);
516 
528 void rn2xx3_mac_set_battery(rn2xx3_t *dev, uint8_t battery);
529 
537 uint8_t rn2xx3_mac_get_retx(rn2xx3_t *dev);
538 
545 void rn2xx3_mac_set_retx(rn2xx3_t *dev, uint8_t retx);
546 
553 void rn2xx3_mac_set_linkchk_interval(rn2xx3_t *dev, uint16_t linkchk);
554 
562 uint16_t rn2xx3_mac_get_rx1_delay(rn2xx3_t *dev);
563 
570 void rn2xx3_mac_set_rx1_delay(rn2xx3_t *dev, uint16_t rx1);
571 
579 uint16_t rn2xx3_mac_get_rx2_delay(rn2xx3_t *dev);
580 
588 bool rn2xx3_mac_get_ar(rn2xx3_t *dev);
589 
596 void rn2xx3_mac_set_ar(rn2xx3_t *dev, bool ar);
597 
606 
614 
622 uint32_t rn2xx3_mac_get_rx2_freq(rn2xx3_t *dev);
623 
630 void rn2xx3_mac_set_rx2_freq(rn2xx3_t *dev, uint32_t freq);
631 
639 uint8_t rn2xx3_mac_get_tx_port(rn2xx3_t *dev);
640 
647 void rn2xx3_mac_set_tx_port(rn2xx3_t *dev, uint8_t port);
648 
657 
665 
673 uint8_t rn2xx3_mac_get_rx_port(rn2xx3_t *dev);
674 
681 void rn2xx3_sys_set_sleep_duration(rn2xx3_t *dev, uint32_t sleep);
682 
683 #ifdef __cplusplus
684 }
685 #endif
686 
687 #endif /* RN2XX3_H */
688 
waiting for mac rx port
Definition: rn2xx3.h:120
uint8_t rx_port
RX port (between 1 and 223)
Definition: rn2xx3.h:132
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:107
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:93
MAC transmission successful.
Definition: rn2xx3.h:100
MAC was paused.
Definition: rn2xx3.h:95
RN2483/RN2903 device descriptor.
Definition: rn2xx3.h:148
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:156
Keys not configured ("mac join" command)
Definition: rn2xx3.h:97
Low-level GPIO peripheral driver interface definitions.
unsigned int uart_t
Define default UART type identifier.
Definition: uart.h:76
xtimer_t sleep_timer
Timer used to count module sleep time.
Definition: rn2xx3.h:175
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:149
Configuration parameters for RN2483/RN2903 devices.
Definition: rn2xx3.h:138
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:105
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:85
MAC is not in Idle state.
Definition: rn2xx3.h:94
waiting for incoming commands
Definition: rn2xx3.h:116
uint32_t sleep
module sleep duration
Definition: rn2xx3.h:176
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:86
uart_t uart
UART interfaced the device is connected to.
Definition: rn2xx3.h:139
uint16_t rx_size
counter for received char in RX
Definition: rn2xx3.h:172
Device mac initialization failed.
Definition: rn2xx3.h:88
waiting for mac tx reply
Definition: rn2xx3.h:119
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:131
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:130
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:121
Join procedure successful.
Definition: rn2xx3.h:104
Command is valid.
Definition: rn2xx3.h:84
All channels are busy.
Definition: rn2xx3.h:91
Data received from server.
Definition: rn2xx3.h:103
loramac_settings_t loramac
loramac communication settings
Definition: rn2xx3.h:152
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:299
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:114
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:102
Wrong command given.
Definition: rn2xx3.h:89
Device is in Silent Immediately state.
Definition: rn2xx3.h:92
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:96
No MAC reply received from server.
Definition: rn2xx3.h:106
void rn2xx3_mac_set_ar(rn2xx3_t *dev, bool ar)
Enables/disables LoRaMAC rn2xx3 MAC automatic reply state.
LoRaMAC communication settings.
Definition: rn2xx3.h:127
uint32_t baudrate
baudrate to use
Definition: rn2xx3.h:140
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:115
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:129
uint8_t int_state
current state of the device
Definition: rn2xx3.h:158
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:101
xtimer timer structure
Definition: xtimer.h:81
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:151
uint16_t resp_size
counter for received char in response
Definition: rn2xx3.h:164
sleep mode
Definition: rn2xx3.h:117
mutex_t resp_lock
mutex for waiting for command response
Definition: rn2xx3.h:161
Failure because device is in sleep mode.
Definition: rn2xx3.h:98
uint8_t resp_done
check if response has completed
Definition: rn2xx3.h:165
Network is not joined.
Definition: rn2xx3.h:90
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:141
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:128
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:118