diff --git a/impl/src/packet_mod.h b/impl/src/packet_mod.h index 22a4637..5109d3d 100644 --- a/impl/src/packet_mod.h +++ b/impl/src/packet_mod.h @@ -34,18 +34,145 @@ typedef struct } packet_mod_ctx_t; +/*!\brief Initialize the packet modulator context. + * + * \param[inout] ctx The context to initialize. + * \returns An result code (see results.h). + */ result_t packet_mod_init(packet_mod_ctx_t *ctx); + +/*!\brief Free all resources in the given context. + * + * \param[inout] ctx The context to free. + * \returns An result code (see results.h). + */ result_t packet_mod_free(packet_mod_ctx_t *ctx); +/*!\brief Set the raw packet data. + * + * In this step, the CRC of the data is calculated. + * + * This is the first step in packet processing. The context must be freshly + * initialized. + * + * The stored data can be retrieved for verification using \ref + * packet_mod_get_result_b(). + * + * \param[inout] ctx The context to use for this operation. + * \returns An result code (see results.h). + */ result_t packet_mod_set_data(packet_mod_ctx_t *ctx, const unsigned char *data, size_t length); + +/*!\brief Channel-code the stored packet data. + * + * This can only be called after \ref packet_mod_set_data(). + * + * The resulting data can be retrieved for verification using \ref + * packet_mod_get_result_b(). + * + * \param[inout] ctx The context to use for this operation. + * \returns An result code (see results.h). + */ result_t packet_mod_encode(packet_mod_ctx_t *ctx); + +/*!\brief Modulate the packet data. + * + * This can be called after \ref packet_mod_set_data() or \ref + * packet_mod_encode(). + * + * The resulting data can be retrieved for verification using \ref + * packet_mod_get_result_cf(). + * + * \param[inout] ctx The context to use for this operation. + * \returns An result code (see results.h). + */ result_t packet_mod_modulate(packet_mod_ctx_t *ctx); + +/*!\brief Add a channel-coded and modulated packet header. + * + * The header contains the length of the data part (in symbols) and the CRC of + * the original raw data. The channel coding scheme and modulation are + * different than for the actual packet data, see \ref HEADER_CHANNEL_CODING + * and \ref HEADER_MODULATION. These settings should be chosen to be slightly + * more robust than the actual data encoding and modulation. + * + * This can only be called after \ref packet_mod_modulate(). + * + * The resulting data can be retrieved for verification using \ref + * packet_mod_get_result_cf(). + * + * \param[inout] ctx The context to use for this operation. + * \returns An result code (see results.h). + */ result_t packet_mod_add_header(packet_mod_ctx_t *ctx); + +/*!\brief Add the preamble to the packet. + * + * The preamble is one cycle of a m-sequence, modulated using BPSK. Adding such + * a preamble allows to find the packet start time and further signal + * parameters such as phase offset using cross-correlation at the receiver. + * + * This can only be called after \ref packet_mod_add_header(). + * + * The resulting data can be retrieved using \ref packet_mod_get_result_cf(). + * + * \param[inout] ctx The context to use for this operation. + * \returns An result code (see results.h). + */ result_t packet_mod_add_preamble(packet_mod_ctx_t *ctx); + +/*!\brief Dump the internal data to the given file. + * + * The format of the resulting file depends on the current state of the packet + * modulation context. + * + * \param[in] ctx The context to use for this operation. + * \param[in] filename Name of the file to write to. + * \returns An result code (see results.h). + */ result_t packet_mod_dump(packet_mod_ctx_t *ctx, const char *filename); + +/*!\brief Get the result data as raw bytes. + * + * Raw bytes can be retrieved after \ref packet_mod_set_data() and \ref + * packet_mod_encode(). In all other states, this returns ERR_INVALID_STATE. + * + * \param[in] ctx The context to use for this operation. + * \param[out] data A pointer to the memory location where the data should be written. + * \param[inout length A pointer to the data length (in array items). The + * value shall be set to the size of the data buffer. + * After the call, it is set to the required buffer size + * (if \ref data is NULL or the length is not sufficient) + * or the number of items actually written to \ref data. + * \retval OK If the data was copied successfully or \ref data was + * NULL. In the latter case, only \ref length is modified + * to the required buffer size. + * \retval ERR_NO_MEM If the \ref length was not sufficient for the data. + * \retval ERR_INVALID_STATE If byte data is unavailable in the current state. + */ result_t packet_mod_get_result_b(packet_mod_ctx_t *ctx, unsigned char *data, size_t *length); + +/*!\brief Get the result data as complex numbers. + * + * Complex numbers can be retrieved after \ref packet_mod_modulate(), \ref + * packet_mod_add_header() and \ref packet_mod_add_preamble(). In all other + * states, this returns ERR_INVALID_STATE. + * + * \param[in] ctx The context to use for this operation. + * \param[out] data A pointer to the memory location where the data should be written. + * \param[inout length A pointer to the data length (in array items). The + * value shall be set to the size of the data buffer. + * After the call, it is set to the required buffer size + * (if \ref data is NULL or the length is not sufficient) + * or the number of items actually written to \ref data. + * \retval OK If the data was copied successfully or \ref data was + * NULL. In the latter case, only \ref length is modified + * to the required buffer size. + * \retval ERR_NO_MEM If the \ref length was not sufficient for the data. + * \retval ERR_INVALID_STATE If byte data is unavailable in the current state. + */ result_t packet_mod_get_result_cf(packet_mod_ctx_t *ctx, float complex *data, size_t *length); #endif // PACKET_MOD