lr4  2.0.0.0
lr4.h
Go to the documentation of this file.
1 /*
2  * MikroSDK - MikroE Software Development Kit
3  * Copyright© 2020 MikroElektronika d.o.o.
4  *
5  * Permission is hereby granted, free of charge, to any person
6  * obtaining a copy of this software and associated documentation
7  * files (the "Software"), to deal in the Software without restriction,
8  * including without limitation the rights to use, copy, modify, merge,
9  * publish, distribute, sublicense, and/or sell copies of the Software,
10  * and to permit persons to whom the Software is furnished to do so,
11  * subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be
14  * included in all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
20  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
22  * OR OTHER DEALINGS IN THE SOFTWARE.
23  */
24 
33 // ----------------------------------------------------------------------------
34 
35 #ifndef LR4_H
36 #define LR4_H
37 
38 #include "drv_digital_out.h"
39 #include "drv_digital_in.h"
40 #include "drv_uart.h"
41 
42 // -------------------------------------------------------------- PUBLIC MACROS
52 #define LR4_MAP_MIKROBUS( cfg, mikrobus ) \
53  cfg.tx_pin = MIKROBUS( mikrobus, MIKROBUS_TX ); \
54  cfg.rx_pin = MIKROBUS( mikrobus, MIKROBUS_RX ); \
55  cfg.rst = MIKROBUS( mikrobus, MIKROBUS_RST ); \
56  cfg.wk = MIKROBUS( mikrobus, MIKROBUS_CS ); \
57  cfg.int_pin = MIKROBUS( mikrobus, MIKROBUS_INT )
58 
64 #define LR4_RETVAL uint8_t
65 
66 #define LR4_OK 0x00
67 #define LR4_INIT_ERROR 0xFF
68 
74 #define LR4_FRAME_HEADER 0xAA
75 #define LR4_RESPONSE_BIT 0x80
76 
82 #define LR4_CMD_RESET 0x30
83 #define LR4_CMD_FACTORY_RESET 0x31
84 #define LR4_CMD_EEPROM_WRITE 0x32
85 #define LR4_CMD_EEPROM_READ 0x33
86 #define LR4_CMD_GET_FW_VERSION 0x34
87 #define LR4_CMD_GET_SERIAL_NO 0x35
88 #define LR4_CMD_GET_DEV_EUI 0x36
89 #define LR4_CMD_JOIN 0x40
90 #define LR4_CMD_GET_ACTIVATION_STATUS 0x42
91 #define LR4_CMD_SET_APP_KEY 0x43
92 #define LR4_CMD_SET_APP_SESSION_KEY 0x44
93 #define LR4_CMD_SET_NWK_SESSION_KEY 0x45
94 #define LR4_CMD_TX_MSG 0x46
95 #define LR4_CMD_GET_SESSION_STATUS 0x4A
96 #define LR4_CMD_SET_NEXT_DR 0x4B
97 #define LR4_CMD_SET_BATTERY_LVL 0x50
98 #define LR4_CMD_GET_BATTERY_LVL 0x51
99 #define LR4_CMD_SET_UPLINK_CNT 0x52
100 #define LR4_CMD_GET_UPLINK_CNT 0x53
101 #define LR4_CMD_SET_DOWNLINK_CNT 0x54
102 #define LR4_CMD_GET_DOWNLINK_CNT 0x55
103 #define LR4_CMD_SET_CH_PARAMETERS 0x57
104 #define LR4_CMD_GET_CH_PARAMETERS 0x58
105 
106 #define LR4_INDICATES_JOIN 0x41
107 #define LR4_INDICATES_TX_MSG_CONFIRMED 0x47
108 #define LR4_INDICATES_TX_MSG_UNCONFIRMED 0x48
109 #define LR4_INDICATES_RX_MSG 0x49
110 
111 #define LR4_OK 0x00
112 #define LR4_ERR_ADDR_RANGE 0x01
113 #define LR4_ERR_NOT_IDLE 0x02
114 
115 #define LR4_ERR_PL_LEN 0xFC
116 #define LR4_ERR_CHKSUM 0xFD
117 #define LR4_ERR_RESPONSE 0xFE
118 #define LR4_ERR_HEADER 0xFF
119 
120 
121 #define LR4_JOIN_ACTIVATION_BY_PERSONALIZATION_MODE 0x00
122 #define LR4_JOIN_OVER_THE_AIR_ACTIVATION_MODE 0x01
123 #define LR4_GET_ACTIVATION_MODE 0x00
124 #define LR4_GET_SESSION_STATUS_MODE 0x01
125 #define LR4_SET_APP_KEY_MODE 0x00
126 #define LR4_SET_NWK_SESSION_KEY_MODE 0x01
127 #define LR4_UPLINK_CNT 0x00
128 #define LR4_DOWNLINK_CNT 0x01
129 #define LR4_CHANNEL_DISABLED 0x00
130 #define LR4_CHANNEL_ENABLED 0x01
131 #define LR4_UNCONFIRMED_TRANSMISSION 0x00
132 #define LR4_CONFIRMED_TRANSMISSION 0x01
133 
134 
135 #define LR4_STATUS_IDLE 0x00
136 #define LR4_STATUS_BUSY 0x01
137 #define LR4_STATUS_DEV_NOT_ACTIVATED 0x02
138 #define LR4_STATUS_DELAYED 0x03
139 
140 #define LR4_STATUS_NOT_ACTIVATED 0x00
141 #define LR4_STATUS_JOINING 0x01
142 #define LR4_STATUS_JOINED 0x02
143 #define LR4_STATUS_MAC_ERROR 0x03
144 
150 #define LR4_MODULE_POWER_ON 1
151 #define LR4_MODULE_POWER_OFF 0
152 
158 #define DRV_RX_BUFFER_SIZE 500
159  // End group macro
162 // --------------------------------------------------------------- PUBLIC TYPES
171 typedef void ( *lr4_ind_hdl_t )( uint8_t *cmd, uint8_t* p_load_size, uint8_t *p_load );
172 
176 typedef struct
177 {
178  // Output pins
179 
180  digital_out_t rst;
181  digital_out_t wk;
182 
183  // Input pins
184 
185  digital_in_t int_pin;
186 
187  // Modules
188 
189  uart_t uart;
190 
191  char uart_rx_buffer[ DRV_RX_BUFFER_SIZE ];
192  char uart_tx_buffer[ DRV_RX_BUFFER_SIZE ];
193 
195 } lr4_t;
196 
200 typedef struct
201 {
202  // Communication gpio pins
203 
204  pin_name_t rx_pin;
205  pin_name_t tx_pin;
206 
207  // Additional gpio pins
208 
209  pin_name_t rst;
210  pin_name_t wk;
211  pin_name_t int_pin;
212 
213  // static variable
214 
215  uint32_t baud_rate; // Clock speed.
217  uart_data_bits_t data_bit; // Data bits.
218  uart_parity_t parity_bit; // Parity bit.
219  uart_stop_bits_t stop_bit; // Stop bits.
220 
221 } lr4_cfg_t;
222 
223 typedef struct {
224 
225  uint8_t command;
226  uint8_t payload_size;
227  uint8_t payload[ 255 ];
228 
229 } lr4_message_t;
230 
231 typedef struct {
232 
233  uint8_t *data_in;
234  uint8_t n_bytes;
235  uint8_t port;
236  uint8_t option;
237 
238 } lr4_tx_msg_t;
239  // End types group
241 // ----------------------------------------------- PUBLIC FUNCTION DECLARATIONS
242 
248 #ifdef __cplusplus
249 extern "C"{
250 #endif
251 
260 void lr4_cfg_setup ( lr4_cfg_t *cfg );
261 
271 
283 int32_t lr4_generic_read ( lr4_t *ctx, char *data_buf, uint16_t max_len );
284 
291 void lr4_generic_write ( lr4_t *ctx, char *data_buf, uint16_t len );
292 
300 void lr4_hard_reset ( lr4_t *ctx );
301 
310 void lr4_wake_up ( lr4_t *ctx, uint8_t state );
311 
321 
334 uint8_t lr4_command ( lr4_t *ctx, lr4_message_t *msg, lr4_message_t *rsp );
335 
345 
356 
368 
382 LR4_RETVAL lr4_write_eeprom ( lr4_t *ctx, uint8_t address, uint8_t n_bytes, uint8_t *data_in );
383 
397 LR4_RETVAL lr4_read_eeprom ( lr4_t *ctx, uint8_t address, uint8_t n_bytes, uint8_t *data_out );
398 
409 LR4_RETVAL lr4_get_fw_version ( lr4_t *ctx, uint32_t *fw_version );
410 
421 LR4_RETVAL lr4_get_serial_no ( lr4_t *ctx, uint32_t *serial_no );
422 
433 LR4_RETVAL lr4_get_dev_eui ( lr4_t *ctx, uint8_t *dev_eui );
434 
445 LR4_RETVAL lr4_join_network ( lr4_t *ctx, uint8_t mode );
446 
459 LR4_RETVAL lr4_get_status ( lr4_t *ctx, uint8_t status_mode );
460 
473 LR4_RETVAL lr4_set_key ( lr4_t *ctx, uint8_t *key_data, uint8_t key_mode );
474 
495 
508 LR4_RETVAL lr4_set_next_tx_data_rate ( lr4_t *ctx, uint8_t data_rate );
509 
523 LR4_RETVAL lr4_set_battery_level ( lr4_t *ctx, uint8_t battery_level );
524 
538 
550 LR4_RETVAL lr4_set_counter ( lr4_t *ctx, uint32_t cnt, uint8_t cnt_mode );
551 
563 LR4_RETVAL lr4_get_counter ( lr4_t *ctx, uint32_t *cnt, uint8_t cnt_mode );
564 
580 LR4_RETVAL lr4_set_channel ( lr4_t *ctx, uint8_t index, uint32_t freq, uint8_t data_rate_range, uint8_t status );
581 
592 uint8_t lr4_chk_sum ( lr4_message_t *cmd );
593 
594 #ifdef __cplusplus
595 }
596 #endif
597 #endif // _LR4_H_
598  // End public_function group
601 
602 // ------------------------------------------------------------------------- END
DRV_RX_BUFFER_SIZE
#define DRV_RX_BUFFER_SIZE
Definition: lr4.h:158
lr4_init
LR4_RETVAL lr4_init(lr4_t *ctx, lr4_cfg_t *cfg)
Initialization function.
lr4_generic_read
int32_t lr4_generic_read(lr4_t *ctx, char *data_buf, uint16_t max_len)
Generic read function.
lr4_t::int_pin
digital_in_t int_pin
Definition: lr4.h:185
lr4_set_battery_level
LR4_RETVAL lr4_set_battery_level(lr4_t *ctx, uint8_t battery_level)
Set Battery Level function.
lr4_soft_reset
LR4_RETVAL lr4_soft_reset(lr4_t *ctx)
Software reset function.
lr4_tx_msg_t::option
uint8_t option
Definition: lr4.h:236
lr4_cfg_t::baud_rate
uint32_t baud_rate
Definition: lr4.h:215
lr4_t::wk
digital_out_t wk
Definition: lr4.h:181
lr4_cfg_t::int_pin
pin_name_t int_pin
Definition: lr4.h:211
lr4_get_battery_level
LR4_RETVAL lr4_get_battery_level(lr4_t *ctx)
Get Battery Level function.
lr4_t::rst
digital_out_t rst
Definition: lr4.h:180
lr4_ind_hdl_t
void(* lr4_ind_hdl_t)(uint8_t *cmd, uint8_t *p_load_size, uint8_t *p_load)
LR4_TYPES Types.
Definition: lr4.h:171
lr4_set_next_tx_data_rate
LR4_RETVAL lr4_set_next_tx_data_rate(lr4_t *ctx, uint8_t data_rate)
Set Next Data Rate function.
lr4_hard_reset
void lr4_hard_reset(lr4_t *ctx)
Hardware reset function.
lr4_read_eeprom
LR4_RETVAL lr4_read_eeprom(lr4_t *ctx, uint8_t address, uint8_t n_bytes, uint8_t *data_out)
EEPROM read function.
lr4_cfg_t::uart_blocking
bool uart_blocking
Definition: lr4.h:216
lr4_chk_sum
uint8_t lr4_chk_sum(lr4_message_t *cmd)
Check sum function.
lr4_t::ind_handler
lr4_ind_hdl_t ind_handler
Definition: lr4.h:194
lr4_t::uart
uart_t uart
Definition: lr4.h:189
lr4_get_counter
LR4_RETVAL lr4_get_counter(lr4_t *ctx, uint32_t *cnt, uint8_t cnt_mode)
Get Counter function.
lr4_read_message_process
uint8_t lr4_read_message_process(lr4_t *ctx)
Process function.
lr4_set_counter
LR4_RETVAL lr4_set_counter(lr4_t *ctx, uint32_t cnt, uint8_t cnt_mode)
Set Counter function.
lr4_t
Click ctx object definition.
Definition: lr4.h:177
lr4_command
uint8_t lr4_command(lr4_t *ctx, lr4_message_t *msg, lr4_message_t *rsp)
Command function.
lr4_generic_write
void lr4_generic_write(lr4_t *ctx, char *data_buf, uint16_t len)
Generic write function.
lr4_tx_msg_t::n_bytes
uint8_t n_bytes
Definition: lr4.h:234
lr4_cfg_setup
void lr4_cfg_setup(lr4_cfg_t *cfg)
Config Object Initialization function.
lr4_get_dev_eui
LR4_RETVAL lr4_get_dev_eui(lr4_t *ctx, uint8_t *dev_eui)
Get DevEUI function.
lr4_set_key
LR4_RETVAL lr4_set_key(lr4_t *ctx, uint8_t *key_data, uint8_t key_mode)
Set Key function.
lr4_set_ind_handler
void lr4_set_ind_handler(lr4_t *ctx, lr4_ind_hdl_t hdl)
Set indication handler function.
lr4_message_t::command
uint8_t command
Definition: lr4.h:225
lr4_get_serial_no
LR4_RETVAL lr4_get_serial_no(lr4_t *ctx, uint32_t *serial_no)
Get Serial Number function.
lr4_tx_msg_t
Definition: lr4.h:231
LR4_RETVAL
#define LR4_RETVAL
Definition: lr4.h:64
lr4_cfg_t
Click configuration structure definition.
Definition: lr4.h:201
lr4_join_network
LR4_RETVAL lr4_join_network(lr4_t *ctx, uint8_t mode)
Join Network function.
lr4_cfg_t::wk
pin_name_t wk
Definition: lr4.h:210
lr4_message_t::payload_size
uint8_t payload_size
Definition: lr4.h:226
lr4_cfg_t::stop_bit
uart_stop_bits_t stop_bit
Definition: lr4.h:219
lr4_write_eeprom
LR4_RETVAL lr4_write_eeprom(lr4_t *ctx, uint8_t address, uint8_t n_bytes, uint8_t *data_in)
EEPROM write function.
lr4_get_fw_version
LR4_RETVAL lr4_get_fw_version(lr4_t *ctx, uint32_t *fw_version)
Get FW Version function.
lr4_set_channel
LR4_RETVAL lr4_set_channel(lr4_t *ctx, uint8_t index, uint32_t freq, uint8_t data_rate_range, uint8_t status)
Set Channel function.
lr4_tx_msg_t::port
uint8_t port
Definition: lr4.h:235
lr4_tx_msg_t::data_in
uint8_t * data_in
Definition: lr4.h:233
lr4_cfg_t::rx_pin
pin_name_t rx_pin
Definition: lr4.h:204
lr4_factory_reset
LR4_RETVAL lr4_factory_reset(lr4_t *ctx)
Factory reset function.
lr4_cfg_t::data_bit
uart_data_bits_t data_bit
Definition: lr4.h:217
lr4_message_t
Definition: lr4.h:223
lr4_cfg_t::tx_pin
pin_name_t tx_pin
Definition: lr4.h:205
lr4_wake_up
void lr4_wake_up(lr4_t *ctx, uint8_t state)
Wake Up function.
lr4_get_status
LR4_RETVAL lr4_get_status(lr4_t *ctx, uint8_t status_mode)
Get Status function.
lr4_tx_message
LR4_RETVAL lr4_tx_message(lr4_t *ctx, lr4_tx_msg_t *tx_msg)
Radio frame Transmission function.
lr4_cfg_t::rst
pin_name_t rst
Definition: lr4.h:209
lr4_cfg_t::parity_bit
uart_parity_t parity_bit
Definition: lr4.h:218