nanolr.h

Go to the documentation of this file.

/*
 * MikroSDK - MikroE Software Development Kit
 * Copyright© 2020 MikroElektronika d.o.o.
 * 
 * Permission is hereby granted, free of charge, to any person 
 * obtaining a copy of this software and associated documentation 
 * files (the "Software"), to deal in the Software without restriction, 
 * including without limitation the rights to use, copy, modify, merge, 
 * publish, distribute, sublicense, and/or sell copies of the Software, 
 * and to permit persons to whom the Software is furnished to do so, 
 * subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be 
 * included in all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 
 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE 
 * OR OTHER DEALINGS IN THE SOFTWARE. 
 */
 
// ----------------------------------------------------------------------------
 
#ifndef NANOLR_H
#define NANOLR_H
 
#ifdef PREINIT_SUPPORTED
#include "preinit.h"
#endif
 
#ifdef MikroCCoreVersion
    #if MikroCCoreVersion >= 1
        #include "delays.h"
    #endif
#endif
 
#include "drv_digital_out.h"
#include "drv_digital_in.h"
#include "drv_uart.h"
 
// -------------------------------------------------------------- PUBLIC MACROS 
#define NANOLR_MAP_MIKROBUS( cfg, mikrobus ) \
  cfg.tx_pin  = MIKROBUS( mikrobus, MIKROBUS_TX ); \
  cfg.rx_pin  = MIKROBUS( mikrobus, MIKROBUS_RX ); \
  cfg.st  = MIKROBUS( mikrobus, MIKROBUS_AN ); \
  cfg.rst = MIKROBUS( mikrobus, MIKROBUS_RST ); \
  cfg.cts = MIKROBUS( mikrobus, MIKROBUS_CS ); \
  cfg.gp1 = MIKROBUS( mikrobus, MIKROBUS_PWM ); \
  cfg.rts = MIKROBUS( mikrobus, MIKROBUS_INT )
#define NANOLR_RETVAL       uint8_t
 
#define NANOLR_OK           0x00
#define NANOLR_INIT_ERROR   0xFF
#define NANOLR_CMD_DEV_INFO                                   0x01
#define NANOLR_CMD_DEV_STATE                                  0x04
#define NANOLR_CMD_RESET                                      0x05
#define NANOLR_CMD_FW_VER                                     0x06
#define NANOLR_CMD_RESTORE_DEF_SETTINGS                       0x07
#define NANOLR_CMD_SAVE_SETTINGS                              0x08
#define NANOLR_CMD_SERIAL_PORT_CFG                            0x09
#define NANOLR_CMD_OUTPUT_POWER                               0x10
#define NANOLR_CMD_OP_CHAN                                    0x11
#define NANOLR_CMD_ENERGY_SAVE                                0x13
#define NANOLR_CMD_PHYSICAL_ADR                               0x20
#define NANOLR_CMD_NETWORK_ADR                                0x21
#define NANOLR_CMD_NETWORK_ID                                 0x22
#define NANOLR_CMD_NETWORK_ROLE                               0x23
#define NANOLR_CMD_NETWORK_AUTO_SETTINGS                      0x24
#define NANOLR_CMD_NETWORK_PREF                               0x25
#define NANOLR_CMD_NETWORK_SECURITY                           0x26
#define NANOLR_CMD_NETWORK_JOIN_MODE                          0x27
#define NANOLR_CMD_NETWORK_STOP                               0x30
#define NANOLR_CMD_NETWORK_START                              0x31
#define NANOLR_CMD_SEND_DATA                                  0x50
#define NANOLR_CMD_RECEIVED_DATA                              0x60
#define NANOLR_CMD_ENTER_BOOTLOADER                           0x70
#define NANOLR_SET_BOOTLOADER_OPTIONS                         0x71
#define NANOLR_ERASE_MEM                                      0x78
#define NANOLR_WRITE_MEM_CHUNK                                0x7A
#define NANOLR_READ_MEM_CHUNK                                 0x7B
#define NANOLR_COMMIT_FW                                      0x7F
#define NANOLR_SUCCESS                                        0x00
#define NANOLR_GENERIC_ERROR                                  0x01
#define NANOLR_PARAM_NOT_ACCEPTED                             0x02
#define NANOLR_OPERATION_TIMEOUT                              0x03
#define NANOLR_NO_MEMORY                                      0x04
#define NANOLR_UNSUPPORTED                                    0x05
#define NANOLR_BUSY                                           0x06
#define NANOLR_DEV_INFO_RESP                                  0x81
#define NANOLR_DEV_STATE_RESP                                 0x84
#define NANOLR_RESET_RESP                                     0x85
#define NANOLR_FW_VER_RESP                                    0x86
#define NANOLR_RESTORE_DEF_SETTINGS_RESP                      0x87
#define NANOLR_SAVE_SETTINGS_RESP                             0x88
#define NANOLR_SERIAL_PORT_CFG_RESP                           0x89
#define NANOLR_OUTPUT_POWER_RESP                              0x90
#define NANOLR_OP_CHAN_RESP                                   0x91
#define NANOLR_ENERGY_SAVE_RESP                               0x93
#define NANOLR_PHYSICAL_ADR_RESP                              0xA0
#define NANOLR_NETWORK_ADR_RESP                               0xA1
#define NANOLR_NETWORK_ID_RESP                                0xA2
#define NANOLR_NETWORK_ROLE_RESP                              0xA3
#define NANOLR_NETWORK_AUTO_SETTINGS_RESP                     0xA4
#define NANOLR_NETWORK_PREF_RESP                              0xA5
#define NANOLR_NETWORK_SECURITY_RESP                          0xA6
#define NANOLR_BAUD_RATE_MAINTAIN_SPEED                       0x00
#define NANOLR_BAUD_RATE_1200                                 0x01
#define NANOLR_BAUD_RATE_2400                                 0x02
#define NANOLR_BAUD_RATE_4800                                 0x03
#define NANOLR_BAUD_RATE_9600                                 0x04
#define NANOLR_BAUD_RATE_19200                                0x05
#define NANOLR_BAUD_RATE_38400                                0x06
#define NANOLR_BAUD_RATE_57600                                0x07
#define NANOLR_BAUD_RATE_115200                               0x08
#define NANOLR_DEVICE_ID_UNKNOWN                              0x00
#define NANOLR_DEVICE_ID_EMB_ZRF2XX                           0x20
#define NANOLR_DEVICE_ID_EMB_ZRF231XX                         0x24
#define NANOLR_DEVICE_ID_EMB_ZRF231PA                         0x26
#define NANOLR_DEVICE_ID_EMB_ZRF212XX                         0x28
#define NANOLR_DEVICE_ID_EMB_ZRF212B                          0x29
#define NANOLR_DEVICE_ID_EMB_Z253X                            0x30
#define NANOLR_DEVICE_ID_EMB_Z2530X                           0x34
#define NANOLR_DEVICE_ID_EMB_Z2530PA                          0x36
#define NANOLR_DEVICE_ID_EMB_Z2531X                           0x38
#define NANOLR_DEVICE_ID_EMB_Z2531PA_USB                      0x3A
#define NANOLR_DEVICE_ID_EMB_Z2538X                           0x3C
#define NANOLR_DEVICE_ID_EMB_Z2538PA                          0x3D
#define NANOLR_DEVICE_ID_EMB_WMBX                             0x40
#define NANOLR_DEVICE_ID_EMB_WMB169X                          0x44
#define NANOLR_DEVICE_ID_EMB_WMB169T                          0x45
#define NANOLR_DEVICE_ID_EMB_WMB169PA                         0x46
#define NANOLR_DEVICE_ID_EMB_WMB868X                          0x48
#define NANOLR_DEVICE_ID_EMB_WMB868                           0x49
#define NANOLR_DEVICE_ID_EMB_LRX                              0x50
#define NANOLR_DEVICE_ID_EMB_LR1272                           0x54
#define NANOLR_NETWORK_ROLE_COORDINATOR                       0x00
#define NANOLR_NETWORK_ROLE_RESERVED                          0x01
#define NANOLR_NETWORK_ROLE_END_DEV                           0x02
#define NANOLR_DEV_STATE_BOOTING                              0x00
#define NANOLR_DEV_STATE_INSIDE_BOOTLOADER                    0x01
#define NANOLR_DEV_STATE_RDY_STARTUP_OP_SUCC                  0x10
#define NANOLR_DEV_STATE_RDY_STARTUP_OP_FAILED                0x11
#define NANOLR_DEV_STATE_OFFLINE                              0x20
#define NANOLR_DEV_STATE_CONNECTING                           0x21
#define NANOLR_DEV_STATE_TRANSPARENT_MODE_STARTUP             0x22
#define NANOLR_DEV_STATE_ONLINE                               0x30
#define NANOLR_DEV_STATE_DISCONNECTING                        0x40
#define NANOLR_DEV_STATE_RESERVED                             0x50
#define NANOLR_DEV_STATE_END_RECEIVING_WINDOW                 0x51
#define NANOLR_ENERGY_SAVE_MODE_ALWAYS_ON                     0x00
#define NANOLR_ENERGY_SAVE_MODE_RX_WINDOW                     0x01
#define NANOLR_ENERGY_SAVE_MODE_TX_ONLY                       0x02
#define NANOLR_OP_CHANNEL_CH_1_868_1MHz                       0x01
#define NANOLR_OP_CHANNEL_CH_2_868_3MHz                       0x02
#define NANOLR_OP_CHANNEL_CH_3_868_5MHz                       0x03
#define NANOLR_OP_CHANNEL_CH_4_869_525MHz                     0x04
#define NANOLR_OP_CHANNEL_SPR_FCT_128                         0x07
#define NANOLR_OP_CHANNEL_SPR_FCT_256                         0x08
#define NANOLR_OP_CHANNEL_SPR_FCT_512                         0x09
#define NANOLR_OP_CHANNEL_SPR_FCT_1024                        0x0A
#define NANOLR_OP_CHANNEL_SPR_FCT_2048                        0x0B
#define NANOLR_OP_CHANNEL_SPR_FCT_4096                        0x0C
#define NANOLR_OP_CHANNEL_BANDWIDTH_125KHz                    0x00
#define NANOLR_OP_CHANNEL_BANDWIDTH_250KHz                    0x01
#define NANOLR_OP_CHANNEL_CODING_RATE_4_5                     0x01
#define NANOLR_OP_CHANNEL_CODING_RATE_4_6                     0x02
#define NANOLR_OP_CHANNEL_CODING_RATE_4_7                     0x03
#define NANOLR_OP_CHANNEL_CODING_RATE_4_8                     0x04
#define NANOLR_NTW_ROLE_COORDINATOR                           0x00
#define NANOLR_NTW_ROLE_END_DEVICE                            0x02
#define NANOLR_NTW_PREFERENCE_PROTOCOL_LR_EMB                 0x00
#define NANOLR_NTW_PREFERENCE_PROTOCOL_LR_WAN                 0x80
#define NANOLR_NTW_PREFERENCE_AUTO_JOIN_DISABLE               0x00
#define NANOLR_NTW_PREFERENCE_AUTO_JOIN_ENABLE                0x40
#define NANOLR_NTW_PREFERENCE_ADAPTIVE_DATA_RATE_DISABLE      0x00
#define NANOLR_NTW_PREFERENCE_ADAPTIVE_DATA_RATE_ENABLE       0x20
#define NANOLR_NTW_JOIN_MODE_ABP                              0x00
#define NANOLR_NTW_JOIN_MODE_OTAA                             0x01
 
#define NANOLR_RSP_READY                                      0x01
#define NANOLR_RSP_NOT_READY                                  0x00
 
#define NANOLR_ERR_CRC                                        0x01
#define NANOLR_ERR_STATUS_OK                                  0x00
#define DRV_RX_BUFFER_SIZE 500
 // End group macro 
// --------------------------------------------------------------- PUBLIC TYPES
#define nanolr_err_t  uint8_t
 
typedef struct
{
    // Output pins 
 
    digital_out_t st;
    digital_out_t rst;
    digital_out_t cts;
 
    // Input pins 
 
    digital_in_t gp1;
    digital_in_t rts;
    
    // Modules 
 
    uart_t uart;
 
    char uart_rx_buffer[ DRV_RX_BUFFER_SIZE ];
    char uart_tx_buffer[ DRV_RX_BUFFER_SIZE ];
 
    char rx_data[ 256 ];
    uint16_t rsp_len;
    uint8_t rsp_rdy;
 
} nanolr_t;
 
typedef struct
{
    // Communication gpio pins 
 
    pin_name_t rx_pin;
    pin_name_t tx_pin;
    
    // Additional gpio pins 
 
    pin_name_t st;
    pin_name_t rst;
    pin_name_t cts;
    pin_name_t gp1;
    pin_name_t rts;
 
    // static variable 
 
    uint32_t          baud_rate;     // Clock speed.
    bool              uart_blocking;
    uart_data_bits_t  data_bit;      // Data bits.
    uart_parity_t     parity_bit;    // Parity bit.  
    uart_stop_bits_t  stop_bit;      // Stop bits.    
 
} nanolr_cfg_t;
 
typedef struct
{
    uint16_t length;
    uint8_t message_id;
    uint8_t payload[ 256 ];
    uint8_t crc;
 
} nanolr_rsp_t;
 
typedef struct
{
    uint8_t channel;
    uint8_t spreading_factor;
    uint8_t bandwidth;
    uint8_t coding_rate;
 
} nanolr_network_t;
 
 // End types group
// ----------------------------------------------- PUBLIC FUNCTION DECLARATIONS
 
#ifdef __cplusplus
extern "C"{
#endif
 
void nanolr_cfg_setup ( nanolr_cfg_t *cfg );
 
NANOLR_RETVAL nanolr_init ( nanolr_t *ctx, nanolr_cfg_t *cfg );
 
void nanolr_default_cfg ( nanolr_t *ctx );
 
void nanolr_reset ( nanolr_t *ctx );
 
void nanolr_generic_write ( nanolr_t *ctx, char *data_buf, uint16_t len );
 
int32_t nanolr_generic_read ( nanolr_t *ctx, char *data_buf, uint16_t max_len );
 
uint8_t nanolr_request_2_send ( nanolr_t *ctx );
 
void nanolr_clear_2_send ( nanolr_t *ctx, uint8_t state );
 
uint8_t nanolr_get_gp1_pin ( nanolr_t *ctx );
 
void nanolr_set_st_pin ( nanolr_t *ctx, uint8_t state );
 
void nanolr_get_device_info ( nanolr_t *ctx );
 
void nanolr_get_device_state ( nanolr_t *ctx );
 
void nanolr_sw_reset ( nanolr_t *ctx );
 
void nanolr_get_fw_ver ( nanolr_t *ctx );
 
void nanolr_restore_2_factory ( nanolr_t *ctx );
 
void nanolr_save_settings ( nanolr_t *ctx );
 
void nanolr_get_output_power ( nanolr_t *ctx );
 
void nanolr_get_operating_channel ( nanolr_t *ctx );
 
void nanolr_set_output_power ( nanolr_t *ctx, uint8_t out_pwr );
 
void nanolr_set_operating_channel ( nanolr_t *ctx, nanolr_network_t *net );
 
void nanolr_save_energy_always_on ( nanolr_t *ctx );
 
void nanolr_save_energy_rx_window ( nanolr_t *ctx );
 
void nanolr_save_energy_tx_only ( nanolr_t *ctx );
 
void nanolr_get_physical_address ( nanolr_t *ctx );
 
void nanolr_set_physical_address ( nanolr_t *ctx, uint8_t *app_eui, uint8_t *dev_eui );
 
void nanolr_get_network_address ( nanolr_t *ctx );
 
void nanolr_set_network_address ( nanolr_t *ctx, uint16_t ntw_addr );
 
void nanolr_get_network_id ( nanolr_t *ctx );
 
void nanolr_set_network_id ( nanolr_t *ctx, uint16_t ntw_id );
 
void nanolr_get_network_role ( nanolr_t *ctx );
 
void nanolr_set_network_role ( nanolr_t *ctx, uint8_t ntw_role );
 
void nanolr_get_network_auto_settings ( nanolr_t *ctx );
 
void nanolr_get_network_preference ( nanolr_t *ctx );
 
void nanolr_set_network_preference ( nanolr_t *ctx, uint8_t prot, uint8_t auto_join, uint8_t adr );
 
void nanolr_get_network_join_mode ( nanolr_t *ctx );
 
void nanolr_set_network_join_mode ( nanolr_t *ctx, uint8_t ntw_join_mode );
 
void nanolr_get_battery_level  ( nanolr_t *ctx );
 
void nanolr_get_wan_network_type ( nanolr_t *ctx );
 
void nanolr_wan_network_public ( nanolr_t *ctx );
 
void nanolr_wan_network_private ( nanolr_t *ctx );
 
void nanolr_network_stop ( nanolr_t *ctx );
 
void nanolr_network_start ( nanolr_t *ctx );
 
void nanolr_send_data ( nanolr_t *ctx, uint8_t *tx_data, uint8_t length );
 
uint8_t nanolr_rsp_rdy ( nanolr_t *ctx );
 
void nanolr_uart_isr ( nanolr_t *ctx );
 
nanolr_err_t nanolr_parser_rsp ( nanolr_t *ctx, nanolr_rsp_t *response );
 
#ifdef __cplusplus
}
#endif
#endif  // _NANOLR_H_
 
 // End public_function group
 
// ------------------------------------------------------------------------- END