LDL  0.5.0
Function List | Typedefs
MAC

Description

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)
 

Functions

◆ LDL_MAC_init()

void LDL_MAC_init ( struct ldl_mac self,
enum ldl_region  region,
const struct ldl_mac_init_arg arg 
)

◆ LDL_MAC_entropy()

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:

Parameters
[in]selfldl_mac
Returns
ldl_mac_status
Return values
LDL_STATUS_OK
LDL_STATUS_BUSY

◆ LDL_MAC_otaa()

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.

Parameters
[in]selfldl_mac
Returns
ldl_mac_status
Return values
LDL_STATUS_OK
LDL_STATUS_BUSY
LDL_STATUS_JOINED

◆ LDL_MAC_unconfirmedData()

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:

  1. LDL_MAC_unconfirmedData() function will return LDL_STATUS_MACPRIORITY to indicate non-success for sending user data
  2. LDL will send the pending MAC commands as an unconfirmed data frame with the usual event notifications coming back to the application.

An application encountering LDL_STATUS_MACPRIORITY should try again after the MAC commands have been sent.

Parameters
[in]selfldl_mac
[in]portlorawan port (must be >0)
[in]datapointer to message to send
[in]lenbyte length of data
[in]optsldl_mac_data_opts (may be NULL)
Returns
ldl_mac_status
Return values
LDL_STATUS_OK
LDL_STATUS_NOTJOINED
LDL_STATUS_BUSY
LDL_STATUS_PORT
LDL_STATUS_NOCHANNEL
LDL_STATUS_SIZE
LDL_STATUS_MACPRIORITY

◆ LDL_MAC_confirmedData()

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().

Parameters
[in]selfldl_mac
[in]portlorawan port (must be >0)
[in]datapointer to message to send
[in]lenbyte length of data
[in]optsldl_mac_data_opts (may be NULL)
Returns
ldl_mac_status
Return values
LDL_STATUS_OK
LDL_STATUS_NOTJOINED
LDL_STATUS_BUSY
LDL_STATUS_PORT
LDL_STATUS_NOCHANNEL
LDL_STATUS_SIZE
LDL_STATUS_MACPRIORITY

◆ LDL_MAC_forget()

void LDL_MAC_forget ( struct ldl_mac self)

Forget network and cancel any operation

Parameters
[in]selfldl_mac

◆ LDL_MAC_cancel()

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.

Parameters
[in]selfldl_mac

◆ LDL_MAC_process()

void LDL_MAC_process ( struct ldl_mac self)

Call to process next events

Parameters
[in]selfldl_mac

◆ LDL_MAC_ticksUntilNextEvent()

uint32_t LDL_MAC_ticksUntilNextEvent ( const struct ldl_mac self)

Get number of ticks until the next event

Parameters
[in]selfldl_mac
Returns
system ticks
Return values
UINT32_MAXthere are no future events at this time
Note
interrupt safe if LDL_SYSTEM_ENTER_CRITICAL() and LDL_SYSTEM_ENTER_CRITICAL() have been defined

◆ LDL_MAC_setRate()

enum ldl_mac_status LDL_MAC_setRate ( struct ldl_mac self,
uint8_t  rate 
)

Set the desired transmit data rate

Parameters
[in]selfldl_mac
[in]rate
Returns
ldl_mac_status
Return values
LDL_STATUS_OK
LDL_STATUS_RATE

◆ LDL_MAC_getRate()

uint8_t LDL_MAC_getRate ( const struct ldl_mac self)

Get the current desired transmit data rate

Parameters
[in]selfldl_mac
Returns
transmit data rate setting

◆ LDL_MAC_setPower()

enum ldl_mac_status LDL_MAC_setPower ( struct ldl_mac self,
uint8_t  power 
)

Set the transmit power

Parameters
[in]selfldl_mac
[in]power
Returns
ldl_mac_status
Return values
LDL_STATUS_OK
LDL_STATUS_POWER

◆ LDL_MAC_getPower()

uint8_t LDL_MAC_getPower ( const struct ldl_mac self)

Get the current transmit power

Parameters
[in]selfldl_mac
Returns
transmit power setting

◆ LDL_MAC_setADR()

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.

Parameters
[in]selfldl_mac
[in]value

◆ LDL_MAC_getADR()

bool LDL_MAC_getADR ( const struct ldl_mac self)

Is ADR mode enabled?

Parameters
[in]selfldl_mac
Return values
trueenabled
falsenot enabled

◆ LDL_MAC_op()

enum ldl_mac_operation LDL_MAC_op ( const struct ldl_mac self)

Read the current operation

Parameters
[in]selfldl_mac
Returns
ldl_mac_operation

◆ LDL_MAC_state()

enum ldl_mac_state LDL_MAC_state ( const struct ldl_mac self)

Read the current state

Parameters
[in]selfldl_mac
Returns
ldl_mac_state

◆ LDL_MAC_joined()

bool LDL_MAC_joined ( const struct ldl_mac self)

Is MAC joined?

Parameters
[in]selfldl_mac
Return values
truejoined
falsenot joined

◆ LDL_MAC_ready()

bool LDL_MAC_ready ( const struct ldl_mac self)

Is MAC ready to send?

Parameters
[in]selfldl_mac
Return values
trueready
falsenot ready

◆ LDL_MAC_mtu()

uint8_t LDL_MAC_mtu ( const struct ldl_mac self)

Get the maximum transfer unit in bytes

The MTU depends on:

  • region
  • channel mask settings
  • pending mac commands
Parameters
[in]selfldl_mac
Return values
mtu

◆ LDL_MAC_setMaxDCycle()

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.

maxDCycle=0 (off-time=1)
maxDCycle=6 (off-time=0.015)
maxDCycle=12 (off-time=0.00024)
etc.
Note
the network may reset this via a MAC command
Parameters
[in]selfldl_mac
[in]maxDCycle
See also
LoRaWAN Specification: DutyCycleReq.DutyCyclePL.MaxDCycle

◆ LDL_MAC_getMaxDCycle()

uint8_t LDL_MAC_getMaxDCycle ( const struct ldl_mac self)

Get aggregated duty cycle limit

Parameters
[in]selfldl_mac
Returns
maxDCycle
See also
LoRaWAN Specification: DutyCycleReq.DutyCyclePL.MaxDCycle

◆ LDL_MAC_priority()

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.

Parameters
[in]selfldl_mac
[in]intervalseconds
Return values
true
false

◆ LDL_MAC_radioEvent()

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().

Parameters
[in]selfldl_mac
Note
interrupt safe if LDL_SYSTEM_ENTER_CRITICAL() and LDL_SYSTEM_ENTER_CRITICAL() have been defined

◆ LDL_MAC_radioEventWithTicks()

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().

Parameters
[in]selfldl_mac
[in]tickstimestamp from LDL_MAC_getTicks()
Note
interrupt safe if LDL_SYSTEM_ENTER_CRITICAL() and LDL_SYSTEM_ENTER_CRITICAL() have been defined

◆ LDL_MAC_getTicks()

uint32_t LDL_MAC_getTicks ( struct ldl_mac self)

Get current tick value

Parameters
[in]selfldl_mac
Returns
ticks

◆ LDL_MAC_setBeaconMode()

void LDL_MAC_setBeaconMode ( struct ldl_mac self,
bool  value 
)

Set beacon mode

Parameters
[in]selfldl_mac
[in]value

◆ LDL_MAC_getBeaconMode()

bool LDL_MAC_getBeaconMode ( struct ldl_mac self)

Get beacon mode

Parameters
[in]selfldl_mac
Return values
trueenabled
falsedisable

◆ LDL_MAC_setUnlimitedDutyCycle()

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.

Parameters
[in]selfldl_mac
[in]valuetrue for enabled, false for disabled

Data Structure Documentation

◆ ldl_mac_response_arg

union ldl_mac_response_arg

Event arguments sent to application

See also
ldl_mac_response_type
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

◆ ldl_mac_response_arg.rx

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

◆ ldl_mac_response_arg.link_status

struct ldl_mac_response_arg.link_status
Data Fields
uint8_t margin

SNR margin

uint8_t gwCount

number of gateways in range

◆ ldl_mac_response_arg.entropy

struct ldl_mac_response_arg.entropy

LDL_MAC_ENTROPY argument

Data Fields
uint32_t value

srand seed from radio driver

◆ ldl_mac_response_arg.session_updated

struct ldl_mac_response_arg.session_updated

◆ ldl_mac_response_arg.device_time

struct ldl_mac_response_arg.device_time
Data Fields
uint32_t seconds

seconds since jan 5 1980

uint8_t fractions

1/255 of a second

◆ ldl_mac_response_arg.join_complete

struct ldl_mac_response_arg.join_complete
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

◆ ldl_mac_data_opts

struct ldl_mac_data_opts

Data service invocation options

Data Fields
uint8_t nbTrans

redundancy (0..LDL_REDUNDANCY_MAX)

bool check

piggy-back a LinkCheckReq

bool getTime

piggy-back a DeviceTimeReq

◆ ldl_mac_session

struct ldl_mac_session

Session cache

◆ ldl_mac

struct ldl_mac

MAC layer data

◆ ldl_mac_init_arg

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

See also
LDL_MAC_JOIN_COMPLETE
uint32_t joinNonce

the most up to date joinNonce

See also
LDL_MAC_JOIN_COMPLETE
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 Documentation

◆ ldl_mac_response_fn

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

Parameters
[in]appfrom ldl_mac_init_arg.app
[in]typeldl_mac_response_type
[in]argOPTIONAL depending on ldl_mac_response_type

Enumeration Type Documentation

◆ ldl_mac_response_type

Event types pushed to application

See also
ldl_mac_response_arg
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:

  • devNonce has been updated. The next devNonce is pushed with this event and should be cached so that it can be restored the next time LDL_MAC_init() is called.
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

◆ ldl_mac_state

MAC state

Enumerator
LDL_STATE_INIT 

stack has been memset to zero

LDL_STATE_RADIO_RESET 

holding reset

LDL_STATE_RADIO_BOOT 

waiting for radio to start after reset

LDL_STATE_IDLE 

ready for operations

LDL_STATE_START_RADIO_FOR_ENTROPY 

waiting for radio to start before entropy

LDL_STATE_ENTROPY 

waiting to receive entropy

LDL_STATE_WAIT_TX 

waiting for channel to become available

LDL_STATE_START_RADIO_FOR_TX 

waiting for radio to start before TX

LDL_STATE_TX 

radio is TX

LDL_STATE_WAIT_RX1 

waiting for first RX window

LDL_STATE_RX1 

first RX window

LDL_STATE_WAIT_RX2 

waiting for second RX window

LDL_STATE_START_RADIO_FOR_RX2 

waiting for second RX window

LDL_STATE_RX2 

second RX window

LDL_STATE_RX2_LOCKOUT 

used to ensure an out of range RX2 window is not clobbered

◆ ldl_mac_operation

MAC operations

Enumerator
LDL_OP_NONE 

no active operation

LDL_OP_ENTROPY 

MAC is gathering entropy

LDL_OP_JOINING 

MAC is performing a join

LDL_OP_REJOINING 

MAC is performing a rejoin

LDL_OP_DATA_UNCONFIRMED 

MAC is sending unconfirmed data

LDL_OP_DATA_CONFIRMED 

MAC is sending confirmed data

◆ ldl_mac_status

MAC operation return status codes

Enumerator
LDL_STATUS_OK 

success/pending

LDL_STATUS_NOCHANNEL 

upstream channel not available

LDL_STATUS_SIZE 

message too large to send

LDL_STATUS_RATE 

invalid rate setting for region

LDL_STATUS_PORT 

invalid port number

LDL_STATUS_BUSY 

cannot perform operation because busy

LDL_STATUS_NOTJOINED 

cannot perform operation because not joined

LDL_STATUS_POWER 

invalid power setting for region

LDL_STATUS_MACPRIORITY 

data request failed due to MAC command(s) being prioritised

LDL_STATUS_JOINED 

cannot join because already joined

LDL_STATUS_NOACK 

confirmed service did not receive acknowledgement

LDL_STATUS_CANCELLED 

service was cancelled

LDL_STATUS_TIMEOUT 

user timeout waiting for service

LDL_STATUS_ERROR 

hardware error

◆ ldl_region

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