|
LDL
0.5.0
|
Before accessing any of the interfaces MAC must be initialised by calling LDL_MAC_init().
Any operation that cannot be completed immediately runs from a state machine in LDL_MAC_process(). Applications that sleep can use LDL_MAC_ticksUntilNextEvent() to work out when LDL_MAC_process() needs to be called.
Events (ldl_mac_response_type) that occur within LDL_MAC_process() are pushed back to the application using the ldl_mac_response_fn function pointer. This includes everything from state change notifications to data received from the network.
Data services are not available until ldl_mac is joined to a network. The join procedure is initiated by calling LDL_MAC_otaa(). Join will run indefintely until either join succeeds, or the application calls LDL_MAC_cancel() or LDL_MAC_forget(). The application can check on the join status by calling LDL_MAC_joined().
The application can un-join by call LDL_MAC_forget().
The application can cancel an operation by calling LDL_MAC_cancel().
Function List | |
| void | LDL_MAC_init (struct ldl_mac *self, enum ldl_region region, const struct ldl_mac_init_arg *arg) |
| enum ldl_mac_status | LDL_MAC_entropy (struct ldl_mac *self) |
| enum ldl_mac_status | LDL_MAC_otaa (struct ldl_mac *self) |
| enum ldl_mac_status | LDL_MAC_unconfirmedData (struct ldl_mac *self, uint8_t port, const void *data, uint8_t len, const struct ldl_mac_data_opts *opts) |
| enum ldl_mac_status | LDL_MAC_confirmedData (struct ldl_mac *self, uint8_t port, const void *data, uint8_t len, const struct ldl_mac_data_opts *opts) |
| void | LDL_MAC_forget (struct ldl_mac *self) |
| void | LDL_MAC_cancel (struct ldl_mac *self) |
| void | LDL_MAC_process (struct ldl_mac *self) |
| uint32_t | LDL_MAC_ticksUntilNextEvent (const struct ldl_mac *self) |
| enum ldl_mac_status | LDL_MAC_setRate (struct ldl_mac *self, uint8_t rate) |
| uint8_t | LDL_MAC_getRate (const struct ldl_mac *self) |
| enum ldl_mac_status | LDL_MAC_setPower (struct ldl_mac *self, uint8_t power) |
| uint8_t | LDL_MAC_getPower (const struct ldl_mac *self) |
| void | LDL_MAC_setADR (struct ldl_mac *self, bool value) |
| bool | LDL_MAC_getADR (const struct ldl_mac *self) |
| enum ldl_mac_operation | LDL_MAC_op (const struct ldl_mac *self) |
| enum ldl_mac_state | LDL_MAC_state (const struct ldl_mac *self) |
| bool | LDL_MAC_joined (const struct ldl_mac *self) |
| bool | LDL_MAC_ready (const struct ldl_mac *self) |
| uint8_t | LDL_MAC_mtu (const struct ldl_mac *self) |
| void | LDL_MAC_setMaxDCycle (struct ldl_mac *self, uint8_t maxDCycle) |
| uint8_t | LDL_MAC_getMaxDCycle (const struct ldl_mac *self) |
| bool | LDL_MAC_priority (const struct ldl_mac *self, uint8_t interval) |
| void | LDL_MAC_radioEvent (struct ldl_mac *self) |
| void | LDL_MAC_radioEventWithTicks (struct ldl_mac *self, uint32_t ticks) |
| uint32_t | LDL_MAC_getTicks (struct ldl_mac *self) |
| void | LDL_MAC_setBeaconMode (struct ldl_mac *self, bool value) |
| bool | LDL_MAC_getBeaconMode (struct ldl_mac *self) |
| void | LDL_MAC_setUnlimitedDutyCycle (struct ldl_mac *self, bool value) |
Typedefs | |
| typedef void(* | ldl_mac_response_fn) (void *app, enum ldl_mac_response_type type, const union ldl_mac_response_arg *arg) |
| void LDL_MAC_init | ( | struct ldl_mac * | self, |
| enum ldl_region | region, | ||
| const struct ldl_mac_init_arg * | arg | ||
| ) |
Initialise ldl_mac
Parameters are injected into ldl_mac via arg.
The following paramters are MANDATORY:
The following parameters are OPTIONAL (leave NULL or 0):
| [in] | self | ldl_mac |
| [in] | region | ldl_region |
| [in] | arg | ldl_mac_init_arg |
| enum ldl_mac_status LDL_MAC_entropy | ( | struct ldl_mac * | self | ) |
Read entropy from the radio
The application shall be notified of completion via ldl_mac_response_fn. One of the following events can be expected:
| [in] | self | ldl_mac |
| LDL_STATUS_OK | |
| LDL_STATUS_BUSY |
| enum ldl_mac_status LDL_MAC_otaa | ( | struct ldl_mac * | self | ) |
Initiate Over The Air Activation
Once initiated MAC will keep trying to join forever.
The application can cancel the service while it is in progress by calling LDL_MAC_cancel().
The application shall be notified of completion via ldl_mac_response_fn. One of the following events can be expected:
Unlike data services, OTAA will continue even if radio errors are detected.
| [in] | self | ldl_mac |
| LDL_STATUS_OK | |
| LDL_STATUS_BUSY | |
| LDL_STATUS_JOINED |
| enum ldl_mac_status LDL_MAC_unconfirmedData | ( | struct ldl_mac * | self, |
| uint8_t | port, | ||
| const void * | data, | ||
| uint8_t | len, | ||
| const struct ldl_mac_data_opts * | opts | ||
| ) |
Send data without network confirmation
Once initiated MAC will send at most nbTrans times or until a valid downlink is received. NbTrans may be set:
The application can cancel the service while it is in progress by calling LDL_MAC_cancel().
The application shall be notified of completion via ldl_mac_response_fn. One of the following events can be expected:
Be aware that pending MAC commands are piggy-backed onto upstream data frames. If the pending MAC commands will not fit into the same frame as the application data, the MAC commands will be prioritised.
In the event this happens, please be aware that:
An application encountering LDL_STATUS_MACPRIORITY should try again after the MAC commands have been sent.
| [in] | self | ldl_mac |
| [in] | port | lorawan port (must be >0) |
| [in] | data | pointer to message to send |
| [in] | len | byte length of data |
| [in] | opts | ldl_mac_data_opts (may be NULL) |
| enum ldl_mac_status LDL_MAC_confirmedData | ( | struct ldl_mac * | self, |
| uint8_t | port, | ||
| const void * | data, | ||
| uint8_t | len, | ||
| const struct ldl_mac_data_opts * | opts | ||
| ) |
Send data with network confirmation
Once initiated MAC will send at most nbTrans times until a confirmation is received. NbTrans may be set per invocation by ldl_mac_data_opts.nbTrans
The application can cancel the operation while it is in progress by calling LDL_MAC_cancel().
The application shall be notified of completion via ldl_mac_response_fn. One of the following events can be expected:
MAC commands are piggy-backed and prioritised the same as they are for LDL_MAC_unconfirmedData().
| [in] | self | ldl_mac |
| [in] | port | lorawan port (must be >0) |
| [in] | data | pointer to message to send |
| [in] | len | byte length of data |
| [in] | opts | ldl_mac_data_opts (may be NULL) |
| void LDL_MAC_forget | ( | struct ldl_mac * | self | ) |
Forget network and cancel any operation
| [in] | self | ldl_mac |
| void LDL_MAC_cancel | ( | struct ldl_mac * | self | ) |
Cancel any operation
Calling this function will always cause the radio hardware to be reset. This may be useful for long running applications that wish to periodically cycle the radio.
| [in] | self | ldl_mac |
| void LDL_MAC_process | ( | struct ldl_mac * | self | ) |
Call to process next events
| [in] | self | ldl_mac |
| uint32_t LDL_MAC_ticksUntilNextEvent | ( | const struct ldl_mac * | self | ) |
Get number of ticks until the next event
| [in] | self | ldl_mac |
| UINT32_MAX | there are no future events at this time |
| enum ldl_mac_status LDL_MAC_setRate | ( | struct ldl_mac * | self, |
| uint8_t | rate | ||
| ) |
Set the desired transmit data rate
| [in] | self | ldl_mac |
| [in] | rate |
| LDL_STATUS_OK | |
| LDL_STATUS_RATE |
| uint8_t LDL_MAC_getRate | ( | const struct ldl_mac * | self | ) |
Get the current desired transmit data rate
| [in] | self | ldl_mac |
| enum ldl_mac_status LDL_MAC_setPower | ( | struct ldl_mac * | self, |
| uint8_t | power | ||
| ) |
Set the transmit power
| [in] | self | ldl_mac |
| [in] | power |
| LDL_STATUS_OK | |
| LDL_STATUS_POWER |
| uint8_t LDL_MAC_getPower | ( | const struct ldl_mac * | self | ) |
| void LDL_MAC_setADR | ( | struct ldl_mac * | self, |
| bool | value | ||
| ) |
Enable or Disable ADR
Note that ADR is enabled by default after OTAA is successful.
| [in] | self | ldl_mac |
| [in] | value |
| bool LDL_MAC_getADR | ( | const struct ldl_mac * | self | ) |
| enum ldl_mac_operation LDL_MAC_op | ( | const struct ldl_mac * | self | ) |
| enum ldl_mac_state LDL_MAC_state | ( | const struct ldl_mac * | self | ) |
| bool LDL_MAC_joined | ( | const struct ldl_mac * | self | ) |
| bool LDL_MAC_ready | ( | const struct ldl_mac * | self | ) |
| uint8_t LDL_MAC_mtu | ( | const struct ldl_mac * | self | ) |
Get the maximum transfer unit in bytes
The MTU depends on:
| [in] | self | ldl_mac |
| mtu |
| void LDL_MAC_setMaxDCycle | ( | struct ldl_mac * | self, |
| uint8_t | maxDCycle | ||
| ) |
Set the aggregated duty cycle limit
duty cycle limit = 1 / (2 ^ limit)
This is useful for slowing the rate at which a device is able to send messages, especially if the device is operating in a region that doesn't limit duty cycle.
e.g.
| [in] | self | ldl_mac |
| [in] | maxDCycle |
| uint8_t LDL_MAC_getMaxDCycle | ( | const struct ldl_mac * | self | ) |
Get aggregated duty cycle limit
| [in] | self | ldl_mac |
| bool LDL_MAC_priority | ( | const struct ldl_mac * | self, |
| uint8_t | interval | ||
| ) |
Return true to indicate that LDL is expecting to handle a time sensitive event in the next interval.
This can be used by an application to ensure long-running tasks do not cause LDL to miss important events.
| [in] | self | ldl_mac |
| [in] | interval | seconds |
| true | |
| false |
| void LDL_MAC_radioEvent | ( | struct ldl_mac * | self | ) |
Radio calls this function to notify MAC that an event has occurred.
Normally this will happen via the function pointer set as an argument in LDL_Radio_setHandler().
| [in] | self | ldl_mac |
| void LDL_MAC_radioEventWithTicks | ( | struct ldl_mac * | self, |
| uint32_t | ticks | ||
| ) |
LDL_MAC_radioEvent() but with ticks passed as argument
Normally this will happen via the function pointer set as an argument in LDL_Radio_setHandler().
| [in] | self | ldl_mac |
| [in] | ticks | timestamp from LDL_MAC_getTicks() |
| uint32_t LDL_MAC_getTicks | ( | struct ldl_mac * | self | ) |
| void LDL_MAC_setBeaconMode | ( | struct ldl_mac * | self, |
| bool | value | ||
| ) |
Set beacon mode
| [in] | self | ldl_mac |
| [in] | value |
| bool LDL_MAC_getBeaconMode | ( | struct ldl_mac * | self | ) |
| void LDL_MAC_setUnlimitedDutyCycle | ( | struct ldl_mac * | self, |
| bool | value | ||
| ) |
Use this setting to remove duty cycle limits to speed up testing
This feature is only available when LDL_ENABLE_TEST_MODE is enabled. It must not be used in production.
| [in] | self | ldl_mac |
| [in] | value | true for enabled, false for disabled |
| union ldl_mac_response_arg |
Event arguments sent to application
| Data Fields | ||
|---|---|---|
| struct ldl_mac_response_arg | rx |
LDL_MAC_RX argument |
| struct ldl_mac_response_arg | link_status |
LDL_MAC_LINK_STATUS argument |
| struct ldl_mac_response_arg | entropy |
LDL_MAC_ENTROPY argument |
| struct ldl_mac_response_arg | session_updated |
LDL_MAC_SESSION_UPDATED argument |
| struct ldl_mac_response_arg | device_time |
LDL_MAC_DEVICE_TIME argument |
| struct ldl_mac_response_arg | join_complete |
LDL_MAC_JOIN_COMPLETE argument |
| struct ldl_mac_response_arg.rx |
LDL_MAC_RX argument
| Data Fields | ||
|---|---|---|
| const uint8_t * | data |
message data |
| uint8_t | port |
lorawan application port |
| uint8_t | size |
size of message |
| struct ldl_mac_response_arg.link_status |
LDL_MAC_LINK_STATUS argument
| Data Fields | ||
|---|---|---|
| uint8_t | margin |
SNR margin |
| uint8_t | gwCount |
number of gateways in range |
| struct ldl_mac_response_arg.entropy |
LDL_MAC_ENTROPY argument
| Data Fields | ||
|---|---|---|
| uint32_t | value |
srand seed from radio driver |
| struct ldl_mac_response_arg.session_updated |
LDL_MAC_SESSION_UPDATED argument
| struct ldl_mac_response_arg.device_time |
LDL_MAC_DEVICE_TIME argument
| Data Fields | ||
|---|---|---|
| uint32_t | seconds |
seconds since jan 5 1980 |
| uint8_t | fractions |
1/255 of a second |
| struct ldl_mac_response_arg.join_complete |
LDL_MAC_JOIN_COMPLETE argument
| Data Fields | ||
|---|---|---|
| uint32_t | joinNonce |
the most up to date joinNonce |
| uint16_t | nextDevNonce |
the next devNonce to use in OTAA |
| uint32_t | netID |
netID |
| uint32_t | devAddr |
devAddr |
| struct ldl_mac_data_opts |
| struct ldl_mac_session |
Session cache
| struct ldl_mac |
MAC layer data
| struct ldl_mac_init_arg |
Passed as an argument to LDL_MAC_init()
| Data Fields | ||
|---|---|---|
| void * | app |
pointer passed to ldl_mac_response_fn and System functions |
| struct ldl_radio * | radio |
pointer to initialised Radio |
| const struct ldl_radio_interface * | radio_interface |
pointer to Radio interfaces |
| struct ldl_sm * | sm |
pointer to initialised Security Module |
| const struct ldl_sm_interface * | sm_interface |
pointer to SM interfaces |
| ldl_mac_response_fn | handler |
application callback ldl_mac_response_fn |
| const struct ldl_mac_session * | session |
optional pointer to session data to restore |
| const void * | joinEUI |
pointer to 8 byte identifier |
| const void * | devEUI |
pointer to 8 byte identifier |
| uint16_t | devNonce |
the next devNonce to use in OTAA
|
| uint32_t | joinNonce |
the most up to date joinNonce
|
| ldl_system_rand_fn | rand |
System interface for getting random numbers |
| ldl_system_ticks_fn | ticks |
system interface for getting ticks |
| ldl_system_get_battery_level_fn | get_battery_level |
System interface for getting battery level Leave this field NULL to use the default implementation. |
| uint32_t | tps |
The rate at which ldl_mac_init_arg.ticks() increments i.e. "ticks per second" This is not required if LDL_PARAM_TPS has been defined. Refer to porting.md for details. |
| uint32_t | a |
ldl_mac_init_arg.ticks() compensation parameter A This is not required if LDL_PARAM_A has been defined. Refer to porting.md for details. |
| uint32_t | b |
ldl_mac_init_arg.ticks() compensation parameter B This is not required if LDL_PARAM_B has been defined. Refer to porting.md for details. |
| uint32_t | advance |
Advance window open events by this many ticks This is not required if LDL_PARAM_ADVANCE has been defined. Useful if there is a constant and significant latency between when a window is scheduled to open, and when it actually opens. |
| typedef void(* ldl_mac_response_fn) (void *app, enum ldl_mac_response_type type, const union ldl_mac_response_arg *arg) |
LDL calls this function pointer to notify application of events
| [in] | app | from ldl_mac_init_arg.app |
| [in] | type | ldl_mac_response_type |
| [in] | arg | OPTIONAL depending on ldl_mac_response_type |
Event types pushed to application
| Enumerator | |
|---|---|
| LDL_MAC_ENTROPY | Entropy has received from the radio driver |
| LDL_MAC_CHANNEL_READY | A channel has become ready. This event can be spurious in some situations and so make sure to check that LDL can actually send on next attempt. |
| LDL_MAC_OP_ERROR | The last requested OP failed due to a radio error |
| LDL_MAC_OP_CANCELLED | The last requested OP was cancelled using LDL_MAC_cancel() |
| LDL_MAC_JOIN_COMPLETE | Join request was answered and MAC is now joined Receipt of this event also means:
|
| LDL_MAC_DATA_COMPLETE | data request (confirmed or unconfirmed) completed successfully |
| LDL_MAC_DATA_TIMEOUT | confirmed data request was not answered |
| LDL_MAC_RX | data received |
| LDL_MAC_LINK_STATUS | LinkCheckAns received |
| LDL_MAC_SESSION_UPDATED | ldl_mac_session has changed The application can choose to save the session at this point |
| LDL_MAC_DEVICE_TIME | deviceTimeAns received |
| enum ldl_mac_state |
MAC state
| enum ldl_mac_operation |
| enum ldl_mac_status |
MAC operation return status codes
| enum ldl_region |
LoRaWAN Region
The region selected at LDL_MAC_init() needs to have first been included in the build.
Regions are included in the build by defining:
| Enumerator | |
|---|---|
| LDL_EU_863_870 | EU_863_870 |
| LDL_US_902_928 | US_902_928 |
| LDL_AU_915_928 | AU_915_928 |
| LDL_EU_433 | EU_433 |