1 /*! 2 * \file FragDecoder.h 3 * 4 * \brief Implements the LoRa-Alliance fragmentation decoder 5 * Specification: https://lora-alliance.org/sites/default/files/2018-09/fragmented_data_block_transport_v1.0.0.pdf 6 * 7 * \copyright Revised BSD License, see section \ref LICENSE. 8 * 9 * \code 10 * ______ _ 11 * / _____) _ | | 12 * ( (____ _____ ____ _| |_ _____ ____| |__ 13 * \____ \| ___ | (_ _) ___ |/ ___) _ \ 14 * _____) ) ____| | | || |_| ____( (___| | | | 15 * (______/|_____)_|_|_| \__)_____)\____)_| |_| 16 * (C)2013-2018 Semtech 17 * 18 * \endcode 19 * 20 * \author Fabien Holin ( Semtech ) 21 * \author Miguel Luis ( Semtech ) 22 */ 23 #ifndef __FRAG_DECODER_H__ 24 #define __FRAG_DECODER_H__ 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 #include <stdint.h> 31 32 /*! 33 * If set to 1 the new API defining \ref FragDecoderWrite and 34 * \ref FragDecoderReadfunction callbacks is used. 35 */ 36 #define FRAG_DECODER_FILE_HANDLING_NEW_API 1 37 38 /*! 39 * Maximum number of fragment that can be handled. 40 * 41 * \remark This parameter has an impact on the memory footprint. 42 */ 43 #define FRAG_MAX_NB 21 44 45 /*! 46 * Maximum fragment size that can be handled. 47 * 48 * \remark This parameter has an impact on the memory footprint. 49 */ 50 #define FRAG_MAX_SIZE 50 51 52 /*! 53 * Maximum number of extra frames that can be handled. 54 * 55 * \remark This parameter has an impact on the memory footprint. 56 */ 57 #define FRAG_MAX_REDUNDANCY 5 58 59 #define FRAG_SESSION_FINISHED ( int32_t )0 60 #define FRAG_SESSION_NOT_STARTED ( int32_t )-2 61 #define FRAG_SESSION_ONGOING ( int32_t )-1 62 63 typedef struct sFragDecoderStatus 64 { 65 uint16_t FragNbRx; 66 uint16_t FragNbLost; 67 uint16_t FragNbLastRx; 68 uint8_t MatrixError; 69 }FragDecoderStatus_t; 70 71 #if( FRAG_DECODER_FILE_HANDLING_NEW_API == 1 ) 72 typedef struct sFragDecoderCallbacks 73 { 74 /*! 75 * Writes `data` buffer of `size` starting at address `addr` 76 * 77 * \param [IN] addr Address start index to write to. 78 * \param [IN] data Data buffer to be written. 79 * \param [IN] size Size of data buffer to be written. 80 * 81 * \retval status Write operation status [0: Success, -1 Fail] 82 */ 83 int8_t ( *FragDecoderWrite )( uint32_t addr, uint8_t *data, uint32_t size ); 84 /*! 85 * Reads `data` buffer of `size` starting at address `addr` 86 * 87 * \param [IN] addr Address start index to read from. 88 * \param [IN] data Data buffer to be read. 89 * \param [IN] size Size of data buffer to be read. 90 * 91 * \retval status Read operation status [0: Success, -1 Fail] 92 */ 93 int8_t ( *FragDecoderRead )( uint32_t addr, uint8_t *data, uint32_t size ); 94 }FragDecoderCallbacks_t; 95 #endif 96 97 #if( FRAG_DECODER_FILE_HANDLING_NEW_API == 1 ) 98 /*! 99 * \brief Initializes the fragmentation decoder 100 * 101 * \param [IN] fragNb Number of expected fragments (without redundancy packets) 102 * \param [IN] fragSize Size of a fragment 103 * \param [IN] callbacks Pointer to the Write/Read functions. 104 */ 105 void FragDecoderInit( uint16_t fragNb, uint8_t fragSize, FragDecoderCallbacks_t *callbacks ); 106 #else 107 /*! 108 * \brief Initializes the fragmentation decoder 109 * 110 * \param [IN] fragNb Number of expected fragments (without redundancy packets) 111 * \param [IN] fragSize Size of a fragment 112 * \param [IN] file Pointer to file buffer size 113 * \param [IN] fileSize File buffer size 114 */ 115 void FragDecoderInit( uint16_t fragNb, uint8_t fragSize, uint8_t *file, uint32_t fileSize ); 116 #endif 117 118 #if( FRAG_DECODER_FILE_HANDLING_NEW_API == 1 ) 119 /*! 120 * \brief Gets the maximum file size that can be received 121 * 122 * \retval size FileSize 123 */ 124 uint32_t FragDecoderGetMaxFileSize( void ); 125 #endif 126 127 /*! 128 * \brief Function to decode and reconstruct the binary file 129 * Called for each receive frame 130 * 131 * \param [IN] fragCounter Fragment counter [1..(FragDecoder.FragNb + FragDecoder.Redundancy)] 132 * \param [IN] rawData Pointer to the fragment to be processed (length = FragDecoder.FragSize) 133 * 134 * \retval status Process status. [FRAG_SESSION_ONGOING, 135 * FRAG_SESSION_FINISHED or 136 * FragDecoder.Status.FragNbLost] 137 */ 138 int32_t FragDecoderProcess( uint16_t fragCounter, uint8_t *rawData ); 139 140 /*! 141 * \brief Gets the current fragmentation status 142 * 143 * \retval status Fragmentation decoder status 144 */ 145 FragDecoderStatus_t FragDecoderGetStatus( void ); 146 147 #ifdef __cplusplus 148 } 149 #endif 150 151 #endif // __FRAG_DECODER_H__ 152
