Uplink Encoding / Decoding¶
Functions¶
-
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
uplink – the content of the payload to encode
common – general information about the Sigfox object and its state
encoded – output, raw encoded Sigfox uplink frame(s), including preamble
- 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
Inputs and outputs¶
-
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
-
uint8_t
payloadlen
¶ length of payload
-
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)
-
uint8_t
-
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
-
uint8_t
Errors¶
-
enum
sfx_ule_err
¶ set of errors that can occur during uplink frame encoding, returned by sfx_uplink_encode
Values:
-
enumerator
SFX_ULE_ERR_NONE
¶ no error occured, success
-
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
-
enumerator
-
enum
sfx_uld_err
¶ set of errors that can occur during uplink frame decoding, returned by sfx_uplink_decode
Values:
-
enumerator
SFX_ULD_ERR_NONE
¶ no error occured, success
-
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
-
enumerator
Preamble¶
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