Release v2.0.0

Author: Matthieu Antoine

CHANGELOG.md

@@ -1,5 +1,25 @@
-# LR1110 Modem Driver Changelog
+# LR1110 modem driver changelog
+
+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).
+
+## [v2.0.0] 2020-10-23
+
+### Added
+
+### Changed
+
+* `lr1110_modem_almanac_read_by_index` is renamed `lr1110_modem_gnss_almanac_read_by_index`
+* `lr1110_modem_gnss_scan_autonomous_md` takes an effort mode as parameter
+
+### Fixed
+
+* Various compilation warnings
+* Harmonization of the documentation
 
 ## [v1.0.0] 2020-10-19
 
-Initial release
+### Added
+
+* Initial release

src/lr1110_bootloader.c

@@ -1,7 +1,7 @@
 /*!
- * \file      lr1110_bootloader.c
+ * @file      lr1110_bootloader.c
  *
- * \brief     Bootloader driver implementation for LR1110
+ * @brief     Bootloader driver implementation for LR1110
  *
  * Revised BSD License
  * Copyright Semtech Corporation 2020. All rights reserved.
@@ -20,8 +20,8 @@
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- * ARE DISCLAIMED. IN NO EVENT SHALL SEMTECH S.A. BE LIABLE FOR ANY DIRECT,
- * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * ARE DISCLAIMED. IN NO EVENT SHALL SEMTECH CORPORATION BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
@@ -103,30 +103,30 @@ uint32_t min( uint32_t a, uint32_t b )
 }
 
 /*!
- * \brief Helper function to fill cbuffer with opcode and offset
+ * @brief Helper function to fill cbuffer with opcode and offset
  *
  * Typically used in write flash functions.
  *
- * \warning It is up to the caller to ensure the size of cbuffer is big enough to contain all information!
+ * @warning It is up to the caller to ensure the size of cbuffer is big enough to contain all information!
  */
 static void lr1110_bootloader_fill_cbuffer_opcode_offset_flash( uint8_t* cbuffer, uint16_t opcode, uint32_t offset );
 
 /*!
- * \brief Helper function to fill cdata with data
+ * @brief Helper function to fill cdata with data
  *
  * Typically used in write flash functions.
  *
- * \warning It is up to the caller to ensure the size of cdata is big enough to contain all data!
+ * @warning It is up to the caller to ensure the size of cdata is big enough to contain all data!
  */
 static void lr1110_bootloader_fill_cdata_flash( uint8_t* cdata, const uint32_t* data, uint8_t data_length );
 
 /*!
- * \brief Helper function to fill cbuffer and cdata with information to write flash
+ * @brief Helper function to fill cbuffer and cdata with information to write flash
  *
  * Typically used in write flash functions. Internally calls lr1110_bootloader_fill_cbuffer_opcode_offset_flash and
  * lr1110_bootloader_fill_cdata_flash.
  *
- * \warning It is up to the caller to ensure the sizes of cbuffer and cdata are big enough to contain their respective
+ * @warning It is up to the caller to ensure the sizes of cbuffer and cdata are big enough to contain their respective
  * information!
  */
 static void lr1110_bootloader_fill_cbuffer_cdata_flash( uint8_t* cbuffer, uint8_t* cdata, uint16_t opcode,

src/lr1110_bootloader.h

@@ -1,7 +1,7 @@
 /*!
- * \file      lr1110_bootloader.h
+ * @file      lr1110_bootloader.h
  *
- * \brief     Bootloader driver definition for LR1110
+ * @brief     Bootloader driver definition for LR1110
  *
  * Revised BSD License
  * Copyright Semtech Corporation 2020. All rights reserved.
@@ -20,17 +20,17 @@
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- * ARE DISCLAIMED. IN NO EVENT SHALL SEMTECH S.A. BE LIABLE FOR ANY DIRECT,
- * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * ARE DISCLAIMED. IN NO EVENT SHALL SEMTECH CORPORATION BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-#ifndef __LR1110_BOOTLOADER_H__
-#define __LR1110_BOOTLOADER_H__
+#ifndef LR1110_BOOTLOADER_H
+#define LR1110_BOOTLOADER_H
 
 /*
  * -----------------------------------------------------------------------------
@@ -65,174 +65,156 @@ extern "C" {
  */
 
 /*!
- * \brief Return the version of the system (hardware and software)
+ * @brief Return the version of the system (hardware and software)
  *
- * \param [in] context Chip implementation context
+ * @param [in] context Chip implementation context
+ * @param [out] version Pointer to the structure holding the system version
  *
- * \param [out] version Pointer to the structure holding the system version
- *
- * \returns Operation status
+ * @returns Operation status
  */
 lr1110_status_t lr1110_bootloader_get_version( const void* context, lr1110_bootloader_version_t* version );
 
 /*!
- * \brief Erase the whole flash memory of the chip
+ * @brief Erase the whole flash memory of the chip
  *
  * This function shall be called before any attempt to write a new firmware in flash memory
  *
- * \param [in] context Chip implementation context
+ * @param [in] context Chip implementation context
  *
- * \returns Operation status
+ * @returns Operation status
  */
 lr1110_status_t lr1110_bootloader_erase_flash( const void* context );
 
 /*!
- * \brief Erase the specified page in the flash memory
- *
- * \param [in] context Chip implementation context
+ * @brief Erase the specified page in the flash memory
  *
- * \param [in] page_number The index of the page to erase
+ * @param [in] context Chip implementation context
+ * @param [in] page_number The index of the page to erase
  *
- * \returns Operation status
+ * @returns Operation status
  */
 lr1110_status_t lr1110_bootloader_erase_page( const void* context, const uint8_t page_number );
 
 /*!
- * \brief Write data in program flash memory of the chip
+ * @brief Write data in program flash memory of the chip
  *
  * This function shall be used when updating the flash content of the LR1110.
  * The flash payload to transfer shall be represented as an array of words (ie 4 bytes values).
  *
- * \param [in] context Chip implementation context
- *
- * \param [in] offset The offset from start register of flash
- *
- * \param [in] buffer A pointer to the buffer holding the content of flash to transfert. Its size in words must be at
+ * @param [in] context Chip implementation context
+ * @param [in] offset The offset from start register of flash
+ * @param [in] buffer A pointer to the buffer holding the content of flash to transfert. Its size in words must be at
  * least length
+ * @param [in] length Number of words (i.e. 4 bytes) in the buffer to transfer
  *
- * \param [in] length Number of words (i.e. 4 bytes) in the buffer to transfer
- *
- * \returns Operation status
+ * @returns Operation status
  */
 lr1110_status_t lr1110_bootloader_write_flash( const void* context, const uint32_t offset, const uint32_t* buffer,
                                                const uint8_t length );
 
 /*!
- * \brief Write data in program flash memory of the chip
+ * @brief Write data in program flash memory of the chip
  *
  * This function shall be used when updating the flash content of the LR1110.
  * The flash payload to transfer shall be represented as an array of words (i.e. 4 bytes values).
  *
- * \param [in] context Chip implementation context
- *
- * \param [in] offset The offset from start register of flash
- *
- * \param [in] buffer A pointer to the buffer holding the content of flash to transfert. Its size in words must be at
+ * @param [in] context Chip implementation context
+ * @param [in] offset The offset from start register of flash
+ * @param [in] buffer A pointer to the buffer holding the content of flash to transfert. Its size in words must be at
  * least length
+ * @param [in] length Number of words (i.e. 4 bytes) in the buffer to transfer
  *
- * \param [in] length Number of words (i.e. 4 bytes) in the buffer to transfer
- *
- * \returns Operation status
+ * @returns Operation status
  */
 lr1110_status_t lr1110_bootloader_write_flash_full( const void* context, const uint32_t offset, const uint32_t* buffer,
                                                     const uint32_t length );
 
 /*!
- * \brief Write encrypted data in program flash memory of the chip
+ * @brief Write encrypted data in program flash memory of the chip
  *
  * This function shall be used when updating the encrypted flash content of the LR1110.
  * The encrypted flash payload to transfer shall be represented as an array of words (i.e. 4 bytes values).
  *
- * \param [in] context Chip implementation context
- *
- * \param [in] offset The offset from start register of flash
+ * @param [in] context Chip implementation context
+ * @param [in] offset The offset from start register of flash
+ * @param [in] buffer A pointer to the buffer holding the encrypted content of flash to transfert. Its size in words
+ * must be at least length
+ * @param [in] length Number of words (i.e. 4 bytes) in the buffer to transfer
  *
- * \param [in] buffer A pointer to the buffer holding the encrypted content of
- * flash to transfert. Its size in words must be at least length
- *
- * \param [in] length Number of words (i.e. 4 bytes) in the buffer to transfer
- *
- * \returns Operation status
+ * @returns Operation status
  */
 lr1110_status_t lr1110_bootloader_write_flash_encrypted( const void* context, const uint32_t offset,
                                                          const uint32_t* buffer, const uint8_t length );
 
 /*!
- * \brief Write encrypted data in program flash memory of the chip
+ * @brief Write encrypted data in program flash memory of the chip
  *
  * This function shall be used when updating the encrypted flash content of the LR1110.
  * The encrypted flash payload to transfer shall be represented as an array of words (ie 4 * bytes values).
  *
- * \param [in] context Chip implementation context
- *
- * \param [in] offset The offset from start register of flash
- *
- * \param [in] buffer A pointer to the buffer holding the encrypted content of
- * flash to transfert. Its size in words must be at least length
- *
- * \param [in] length Number of words (i.e. 4 bytes) in the buffer to transfer
+ * @param [in] context Chip implementation context
+ * @param [in] offset The offset from start register of flash
+ * @param [in] buffer A pointer to the buffer holding the encrypted content of flash to transfert. Its size in words
+ * must be at least length
+ * @param [in] length Number of words (i.e. 4 bytes) in the buffer to transfer
  *
- * \returns Operation status
+ * @returns Operation status
  */
 lr1110_status_t lr1110_bootloader_write_flash_encrypted_full( const void* context, const uint32_t offset,
                                                               const uint32_t* buffer, const uint32_t length );
 
 /*!
- * \brief Get calculated hash of flash content.
+ * @brief Get calculated hash of flash content.
  *
  * This method should be used to get the hash of flash content.
  *
- * \param [in] context Chip implementation context
+ * @param [in] context Chip implementation context
+ * @param [out] hash Pointer to the hash array to be populated with hash value
  *
- * \param [out] hash Pointer to the hash array to be populated with hash value
- *
- * \returns Operation status
+ * @returns Operation status
  */
 lr1110_status_t lr1110_bootloader_get_hash( const void* context, lr1110_bootloader_hash_t hash );
 
 /*!
- * \brief Software reset of the chip.
+ * @brief Software reset of the chip.
  *
  * This method should be used to reboot the chip in a specified mode.
  * Rebooting in flash mode presumes that the content in flash memory is not corrupted (i.e. the integrity check
  * performed by the bootloader before executing the first instruction in flash is OK).
  *
- * \param [in] context Chip implementation context
- *
- * \param [in] stay_in_bootloader Selector to stay in bootloader or execute flash code after reboot. If true, the
+ * @param [in] context Chip implementation context
+ * @param [in] stay_in_bootloader Selector to stay in bootloader or execute flash code after reboot. If true, the
  * bootloader will not execute the flash code but activate SPI interface to allow firmware upgrade
  *
- * \returns Operation status
+ * @returns Operation status
  */
 lr1110_status_t lr1110_bootloader_reboot( const void* context, const bool stay_in_bootloader );
 
 /*!
- * \brief Returns the 4-byte PIN which can be used to register a device on cloud
+ * @brief Returns the 4-byte PIN which can be used to register a device on cloud
  * services.
  *
- * \param [in] context Chip implementation context
+ * @param [in] context Chip implementation context
+ * @param [out] pin Pointer to the array to be populated with the PIN
  *
- * \param [out] pin Pointer to the array to be populated with the PIN
- *
- * \returns Operation status
+ * @returns Operation status
  */
 lr1110_status_t lr1110_bootloader_read_pin( const void* context, lr1110_bootloader_pin_t pin );
 
 /*!
- * \brief Returns the 8-byte the factory UUID.
- *
- * \param [in] context Chip implementation context
+ * @brief Returns the 8-byte the factory UUID.
  *
- * \param [out] chip_eui Pointer to the array to be populated with the chip eui
+ * @param [in] context Chip implementation context
+ * @param [out] chip_eui Pointer to the array to be populated with the chip eui
  *
- * \returns Operation status
+ * @returns Operation status
  */
 lr1110_status_t lr1110_bootloader_read_chip_eui( const void* context, lr1110_bootloader_chip_eui_t chip_eui );
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif  // __LR1110_BOOTLOADER_H__
+#endif  // LR1110_BOOTLOADER_H
 
 /* --- EOF ------------------------------------------------------------------ */