Uplink Encoding / Decoding¶

Include¶

Include the uplink header for uplink functionality:

#include <uplink.h>

sfx_ule_err sfx_uplink_encode(sfx_ul_plain uplink, sfx_commoninfo common, sfx_ul_encoded *encoded)¶

generate raw Sigfox uplink frame for the given frame contents

Parameters

Returns

SFX_ULE_ERR_NONE if decoding was successful, otherwise some error defined in sfx_ule_err

sfx_uld_err sfx_uplink_decode(sfx_ul_encoded to_decode, sfx_ul_plain *uplink_out, sfx_commoninfo *common, bool check_mac)¶

retrieve contents of Sigfox uplink from given raw frame

Parameters

to_decode – the raw contents of the Sigfox uplink frame to decode, only first frame is processed (can be initial transmission or any replica frame)
uplink_out – output, decoded plain contents of uplink frame
common – general information about the Sigfox object and its state: NAK is an optional input and only required, if MAC tag checking is enabled. Sequence number and and device ID fileds are used as outputs
check_mac – If true, check MAC tag of uplink frame. In this case, a valid NAK has to be provided.

Returns

SFX_ULD_ERR_NONE if decoding was successful, otherwise some error defined in sfx_uld_err

struct sfx_ul_plain¶

properties that describe the plain contents of an uplink frame, that is the frame contents before encoding or after decoding

Public Members

uint8_t payload[SFX_UL_MAX_PAYLOADLEN]¶: payload of uplink frame with length between 0 and 12 bytes

bool request_downlink¶: indicates whether downlink request flag should be / is set

bool singlebit¶: indicates whether uplink frame is a single-bit (class A) frame

bool replicas¶: indicates whether replica frames (true) or only initial transmission (false) should be generated, only used for encoding (sfx_uplink_encode)

struct sfx_ul_encoded¶

properties that describe the encoded contents of a raw uplink frame after reception / before transmission

Public Members

uint8_t frame[3][SFX_UL_MAX_FRAMELEN]¶: frame content of initial transmission and up to two replicas; sfx_uplink_decode only uses first frame, without preamble, up to 47 nibbles length

uint8_t framelen_nibbles¶: length of frame (length of initial transmission and replicas is identical) in nibbles (4 bits), excluding preamble, must be an odd number

enum sfx_ule_err¶

set of errors that can occur during uplink frame encoding, returned by sfx_uplink_encode

Values:

enumerator SFX_ULE_ERR_PAYLOAD_TOO_LONG¶: length of payload is too high, does not fit in Sigfox uplink frame

enumerator SFX_ULE_SINGLEBIT_MISMATCH¶: single-bit uplink was transmitted, but payload length was not defined to be 0

enum sfx_uld_err¶

set of errors that can occur during uplink frame decoding, returned by sfx_uplink_decode

Values:

enumerator SFX_ULD_ERR_FRAMELEN_EVEN¶: number of nibbles in message frame is even; only odd lengths can naturally occur

enumerator SFX_ULD_ERR_FTYPE_MISMATCH¶: frame type doesn’t match given messsage length

enumerator SFX_ULD_ERR_CRC_INVALID¶: frame’s CRC16 doesn’t match CRC16 computed from frame contents

enumerator SFX_ULD_ERR_MAC_INVALID¶: frame’s MAC doesn’t match MAC computed from frame contents (and private key); can only occur if check_mac parameter to sfx_uplink_decode is set

The encoding / decoding functions handle uplinks excluding the preamble. However, the preamble content can be obtained from the following array:

uint8_t SFX_UL_PREAMBLE[]¶: content of Sigfox’s 5-nibble (SFX_UL_PREAMBLELEN_NIBBLES) uplink preamble, only use first 5 nibbles

SFX_UL_PREAMBLELEN_NIBBLES¶: length of Sigfox’s uplink preamble, in nibbles