Release v3.1.0

Author: bboulet

CHANGELOG.md

@@ -4,8 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v3.1.0] 2021-08-06
+
+### Added
+
+* `lr1110_modem_set_crystal_error()` and `lr1110_modem_set_crystal_error()` functions
+* `lr1110_modem_helper_get_event_data()` helper function
+* `lr1110_modem_event_t` structure definition
+
 ## [v3.0.1] 2021-05-11
 
+### Fixed
+
+* Documentation for `lr1110_modem_get_duty_cycle_status()` - definition of the parameter based on its sign
+
+## [v3.0.0] 2021-05-07
+
 ### Added
 
 * `LR1110_LORAWAN_REGION_AS923_GRP1/2/3`, `LR1110_LORAWAN_REGION_AU915`, `LR1110_LORAWAN_REGION_CN470`, `LR1110_LORAWAN_REGION_IN865`, `LR1110_LORAWAN_REGION_KR920` and `LR1110_LORAWAN_REGION_RU864` in `lr1110_modem_regions_t`

src/lr1110_modem_driver_version.h

@@ -40,12 +40,12 @@
 /*!
  * @brief Current minor version number of the driver
  */
-#define LR1110_MODEM_DRIVER_VERSION_MINOR 0
+#define LR1110_MODEM_DRIVER_VERSION_MINOR 1
 
 /*!
  * @brief Current patch version number of the driver
  */
-#define LR1110_MODEM_DRIVER_VERSION_PATCH 1
+#define LR1110_MODEM_DRIVER_VERSION_PATCH 0
 
 #ifdef __cplusplus
 extern "C" {

src/lr1110_modem_gnss.h

@@ -416,6 +416,9 @@ lr1110_modem_response_code_t lr1110_modem_gnss_set_assistance_position(
 /*!
  * @brief Function to read the assistance position.
  *
+ * The assistance position read may be different from the one set beforehand
+ * with lr1110_modem_gnss_set_assistance_position due to a scaling computation.
+ *
  * @param [in] context Chip implementation context
  * @param [out] assistance_position latitude 12 bits and longitude 12 bits @ref
  * lr1110_modem_gnss_solver_assistance_position_t

src/lr1110_modem_helper.c

@@ -35,7 +35,6 @@
  */
 
 #include "lr1110_modem_helper.h"
-#include "lr1110_modem_lorawan.h"
 
 /*
  * -----------------------------------------------------------------------------
@@ -229,6 +228,75 @@ lr1110_modem_helper_status_t lr1110_modem_helper_gnss_get_event_type( const uint
     return status;
 }
 
+lr1110_modem_helper_status_t lr1110_modem_helper_get_event_data( const void*           context,
+                                                                 lr1110_modem_event_t* modem_event )
+{
+    lr1110_modem_helper_status_t status              = LR1110_MODEM_HELPER_STATUS_ERROR;
+    lr1110_modem_response_code_t modem_response_code = LR1110_MODEM_RESPONSE_CODE_OK;
+    lr1110_modem_event_fields_t  event_fields;
+
+    modem_response_code = lr1110_modem_get_event( context, &event_fields );
+
+    if( modem_response_code == LR1110_MODEM_RESPONSE_CODE_OK )
+    {
+        status                     = LR1110_MODEM_HELPER_STATUS_OK;
+        modem_event->event_type    = event_fields.event_type;
+        modem_event->missed_events = event_fields.missed_events_count;
+
+        switch( modem_event->event_type )
+        {
+        case LR1110_MODEM_LORAWAN_EVENT_RESET:
+            modem_event->event_data.reset.count = ( ( uint16_t ) event_fields.buffer[0] << 8 ) + event_fields.buffer[1];
+            break;
+        case LR1110_MODEM_LORAWAN_EVENT_TX_DONE:
+            modem_event->event_data.txdone.status = ( lr1110_modem_tx_done_event_t ) event_fields.buffer[0];
+            break;
+        case LR1110_MODEM_LORAWAN_EVENT_DOWN_DATA:
+            modem_event->event_data.downdata.rssi  = ( ( int8_t ) event_fields.buffer[0] ) - 64;
+            modem_event->event_data.downdata.snr   = ( ( ( int8_t ) event_fields.buffer[1] ) >> 2 );
+            modem_event->event_data.downdata.flag  = ( lr1110_modem_down_data_flag_t ) event_fields.buffer[2];
+            modem_event->event_data.downdata.fport = event_fields.buffer[3];
+            modem_event->event_data.downdata.length =
+                event_fields.buffer_len - 4;  // remove rssi/snr/flag and fport from buffer
+            for( uint8_t i = 0; i < modem_event->event_data.downdata.length; i++ )
+            {
+                modem_event->event_data.downdata.data[i] = event_fields.buffer[i + 4];
+            }
+            break;
+        case LR1110_MODEM_LORAWAN_EVENT_UPLOAD_DONE:
+            modem_event->event_data.upload.status = ( lr1110_modem_upload_event_t ) event_fields.buffer[0];
+            break;
+        case LR1110_MODEM_LORAWAN_EVENT_SET_CONF:
+            modem_event->event_data.setconf.tag = ( lr1110_modem_event_setconf_tag_t ) event_fields.buffer[0];
+            break;
+        case LR1110_MODEM_LORAWAN_EVENT_MUTE:
+            modem_event->event_data.mute.status = ( lr1110_modem_mute_t ) event_fields.buffer[0];
+            break;
+        case LR1110_MODEM_LORAWAN_EVENT_WIFI_SCAN_DONE:
+            modem_event->event_data.wifi.len = event_fields.buffer_len;
+            for( uint16_t i = 0; i < event_fields.buffer_len; i++ )
+            {
+                modem_event->event_data.wifi.buffer[i] = event_fields.buffer[i];
+            }
+            break;
+        case LR1110_MODEM_LORAWAN_EVENT_GNSS_SCAN_DONE:
+            modem_event->event_data.gnss.len = event_fields.buffer_len;
+            for( uint16_t i = 0; i < event_fields.buffer_len; i++ )
+            {
+                modem_event->event_data.gnss.nav_message[i] = event_fields.buffer[i];
+            }
+            break;
+        case LR1110_MODEM_LORAWAN_EVENT_TIME_UPDATED_ALC_SYNC:
+            modem_event->event_data.time.status = ( lr1110_modem_alc_sync_state_t ) event_fields.buffer[0];
+            break;
+        default:
+            break;
+        }
+    }
+
+    return status;
+}
+
 /*
  * -----------------------------------------------------------------------------
  * --- PRIVATE FUNCTIONS DEFINITION --------------------------------------------

src/lr1110_modem_helper.h

@@ -44,6 +44,7 @@ extern "C" {
 #include <stdbool.h>
 #include <stdint.h>
 #include "lr1110_modem_common.h"
+#include "lr1110_modem_lorawan.h"
 #include "lr1110_modem_gnss.h"
 
 /*
@@ -86,6 +87,21 @@ extern "C" {
  */
 #define LR1110_MODEM_HELPER_NB_DAY_PER_WEEK 7
 
+/**
+ * @brief Maximum payload size in byte of a downlink
+ */
+#define LR1110_MODEM_HELPER_MAX_DOWNLINK_LENGTH 242
+
+/*!
+ * @brief Maximum payload size in byte of a nav message
+ */
+#define LR1110_MODEM_HELPER_GNSS_MAX_NAV_LENGTH 255
+
+/*!
+ * @brief Maximum payload size in byte of a Wi-Fi result
+ */
+#define LR1110_MODEM_HELPER_WIFI_MAX_BUFFER_LENGTH 948  // 12 results * LR1110_WIFI_EXTENDED_FULL_RESULT_SIZE
+
 /*
  * -----------------------------------------------------------------------------
  * --- PUBLIC TYPES ------------------------------------------------------------
@@ -100,6 +116,61 @@ typedef enum
     LR1110_MODEM_HELPER_STATUS_ERROR = 3,
 } lr1110_modem_helper_status_t;
 
+/**
+ * @brief Structure holding event-related data
+ */
+typedef struct
+{
+    uint8_t event_type;
+    uint8_t missed_events;  //!< Number of event_type events missed before the current one
+    union
+    {
+        struct
+        {
+            uint16_t count;
+        } reset;
+        struct
+        {
+            lr1110_modem_tx_done_event_t status;
+        } txdone;
+        struct
+        {
+            int8_t                        rssi;  //!< Signed value in dBm + 64
+            int8_t                        snr;   //!< Signed value in dB given in 0.25dB step
+            lr1110_modem_down_data_flag_t flag;
+            uint8_t                       fport;
+            uint8_t                       data[LR1110_MODEM_HELPER_MAX_DOWNLINK_LENGTH];
+            uint8_t                       length;
+        } downdata;
+        struct
+        {
+            lr1110_modem_upload_event_t status;
+        } upload;
+        struct
+        {
+            lr1110_modem_event_setconf_tag_t tag;
+        } setconf;
+        struct
+        {
+            lr1110_modem_mute_t status;
+        } mute;
+         struct
+        {
+            uint16_t len;
+            uint8_t buffer[LR1110_MODEM_HELPER_WIFI_MAX_BUFFER_LENGTH];
+        } wifi;
+         struct
+        {
+            uint16_t len;
+            uint8_t nav_message[LR1110_MODEM_HELPER_GNSS_MAX_NAV_LENGTH];
+        } gnss;
+        struct
+        {
+            lr1110_modem_alc_sync_state_t status;
+        } time;
+    } event_data;
+} lr1110_modem_event_t;
+
 /*
  * -----------------------------------------------------------------------------
  * --- PUBLIC FUNCTIONS PROTOTYPES ---------------------------------------------
@@ -171,6 +242,17 @@ lr1110_modem_helper_status_t lr1110_modem_helper_gnss_get_event_type( const uint
                                                                       const uint16_t result_buffer_size,
                                                                       lr1110_modem_gnss_scan_done_event_t* event_type );
 
+/**
+ * @brief Extract the event data contained in the event field buffer
+ *
+ * @param [in] context Chip implementation context
+ * @param [out] modem_event Struct containing the event data \see lr1110_modem_event_t
+ *
+ * @returns  Operation status
+ */
+lr1110_modem_helper_status_t lr1110_modem_helper_get_event_data( const void*           context,
+                                                                 lr1110_modem_event_t* modem_event );
+
 #ifdef __cplusplus
 }
 #endif

src/lr1110_modem_lorawan.c

@@ -133,6 +133,8 @@
 #define LR1110_MODEM_GET_NB_TRANS_CMD_LENGTH ( 2 )
 #define LR1110_MODEM_SET_STREAM_REDUNDANCY_RATE_CMD_LENGTH ( 2 + 1 )
 #define LR1110_MODEM_GET_STREAM_REDUNDANCY_RATE_CMD_LENGTH ( 2 )
+#define LR1110_MODEM_SET_CRYSTAL_ERROR_CMD_LENGTH ( 2 + 4 )
+#define LR1110_MODEM_GET_CRYSTAL_ERROR_CMD_LENGTH ( 2 )
 
 #define LR1110_MODEM_INFO_FIELDS_RBUFFER_MAX_LENGTH ( 20 )
 #define LR1110_MODEM_CHIP_EUI_RBUFFER_LENGTH ( 8 )
@@ -229,6 +231,8 @@ enum
     LR1110_MODEM_GET_NB_TRANS_CMD                      = 0x50,
     LR1110_MODEM_SET_STREAM_REDUNDANCY_RATE_CMD        = 0x51,
     LR1110_MODEM_GET_STREAM_REDUNDANCY_RATE_CMD        = 0x52,
+    LR1110_MODEM_SET_CRYSTAL_ERROR_CMD                 = 0x53,
+    LR1110_MODEM_GET_CRYSTAL_ERROR_CMD                 = 0x54,
 };
 
 /*
@@ -1711,6 +1715,40 @@ lr1110_modem_response_code_t lr1110_modem_get_stream_redundancy_rate( const void
                                                                    stream_redundancy_rate, sizeof( uint8_t ) );
 }
 
+lr1110_modem_response_code_t lr1110_modem_set_crystal_error( const void* context, const uint32_t crystal_error )
+{
+    uint8_t cbuffer[LR1110_MODEM_SET_CRYSTAL_ERROR_CMD_LENGTH];
+
+    cbuffer[0] = LR1110_MODEM_GROUP_ID_MODEM;
+    cbuffer[1] = LR1110_MODEM_SET_CRYSTAL_ERROR_CMD;
+
+    cbuffer[2] = ( uint8_t )( crystal_error >> 24 );
+    cbuffer[3] = ( uint8_t )( crystal_error >> 16 );
+    cbuffer[4] = ( uint8_t )( crystal_error >> 8 );
+    cbuffer[5] = ( uint8_t ) crystal_error;
+
+    return ( lr1110_modem_response_code_t ) lr1110_modem_hal_write( context, cbuffer,
+                                                                    LR1110_MODEM_SET_CRYSTAL_ERROR_CMD_LENGTH, 0, 0 );
+}
+
+lr1110_modem_response_code_t lr1110_modem_get_crystal_error( const void* context, uint32_t* crystal_error )
+{
+    uint8_t                      cbuffer[LR1110_MODEM_GET_CRYSTAL_ERROR_CMD_LENGTH];
+    uint8_t                      rbuffer[sizeof( uint32_t )] = { 0x00 };
+    lr1110_modem_response_code_t rc;
+
+    cbuffer[0] = LR1110_MODEM_GROUP_ID_MODEM;
+    cbuffer[1] = LR1110_MODEM_GET_CRYSTAL_ERROR_CMD;
+
+    rc = ( lr1110_modem_response_code_t ) lr1110_modem_hal_read(
+        context, cbuffer, LR1110_MODEM_GET_CRYSTAL_ERROR_CMD_LENGTH, rbuffer, sizeof( uint32_t ) );
+
+    *crystal_error = ( ( uint32_t ) rbuffer[0] << 24 ) + ( ( uint32_t ) rbuffer[1] << 16 ) +
+                     ( ( uint32_t ) rbuffer[2] << 8 ) + ( ( uint32_t ) rbuffer[3] );
+
+    return rc;
+}
+
 /*
  * -----------------------------------------------------------------------------
  * --- PRIVATE FUNCTIONS DEFINITION --------------------------------------------

src/lr1110_modem_lorawan.h

@@ -205,7 +205,6 @@ typedef enum
     LR1110_MODEM_DM_INFO_TYPE_UPLOAD                                  = 0x0E,
     LR1110_MODEM_DM_INFO_TYPE_RESET_COUNT                             = 0x0F,
     LR1110_MODEM_DM_INFO_TYPE_DEV_EUI                                 = 0x10,
-    LR1110_MODEM_DM_INFO_TYPE_OWNER_COUNTER                           = 0x11,
     LR1110_MODEM_DM_INFO_TYPE_SESSION_ID                              = 0x12,
     LR1110_MODEM_DM_INFO_TYPE_CHIP_EUI                                = 0x13,
     LR1110_MODEM_DM_INFO_TYPE_STREAM                                  = 0x14,
@@ -333,6 +332,15 @@ typedef enum
     LR1110_MODEM_DOWN_DATA_EVENT_RXC  = 0x03,  //!< received in Class C DN slot
 } lr1110_modem_down_data_flag_t;
 
+/*!
+ * @brief Upload status values
+ */
+typedef enum
+{
+    LR1110_MODEM_UPLOAD_ERROR   = 0x00,
+    LR1110_MODEM_UPLOAD_SUCCESS = 0x01,
+} lr1110_modem_upload_event_t;
+
 /*!
  * @brief Modem charge type
  */
@@ -396,6 +404,16 @@ typedef enum
     LR1110_MODEM_SUSPEND = 0x01,
 } lr1110_modem_suspend_t;
 
+/**
+ * @brief Modem set conf type
+ */
+typedef enum
+{
+    LR1110_MODEM_EVENT_SETCONF_ADR_MODE_UPDATED    = LR1110_MODEM_DM_INFO_TYPE_ADR_MODE,
+    LR1110_MODEM_EVENT_SETCONF_JOIN_EUI_UPDATED    = LR1110_MODEM_DM_INFO_TYPE_JOIN_EUI,
+    LR1110_MODEM_EVENT_SETCONF_DM_INTERVAL_UPDATED = LR1110_MODEM_DM_INFO_TYPE_INTERVAL,
+} lr1110_modem_event_setconf_tag_t;
+
 /*!
  * @brief Ramping time for PA
  *
@@ -1610,6 +1628,27 @@ lr1110_modem_response_code_t lr1110_modem_set_stream_redundancy_rate( const void
 lr1110_modem_response_code_t lr1110_modem_get_stream_redundancy_rate( const void* context,
                                                                       uint8_t*    stream_redundancy_rate );
 
+/*!
+ * @brief Set the Crystal error of the MCU to fine adjust the rx window for lorawan ( ex: set 30 for a crystal error =
+ * 0.3% ).
+ *
+ * @param [in] context Chip implementation context
+ * @param [out] crystal_error Crystal error
+ *
+ * @returns Operation status
+ */
+lr1110_modem_response_code_t lr1110_modem_set_crystal_error( const void* context, const uint32_t crystal_error );
+
+/*!
+ * @brief Get the Crystal error.
+ *
+ * @param [in] context Chip implementation context
+ * @param [out] crystal_error Crystal error
+ *
+ * @returns Operation status
+ */
+lr1110_modem_response_code_t lr1110_modem_get_crystal_error( const void* context, uint32_t* crystal_error );
+
 #ifdef __cplusplus
 }
 #endif