sam r34/r35 microchip lorawan stack software api reference...

SAM R34/R35 SAM R34/R35 Microchip LoRaWAN™ Stack Software API

Reference Manual

Introduction

Microchip LoRaWAN Stack (MLS) Software API provides an interface to the different software modules.This document describes how to configure and enable functionalities of the API software. A generaldescription of each API is provided including the functionalities, syntax, responses, and an example. TheAPI description defines the parameter with its type, range (valid /acceptable values), the default value(when available), and the factory-programmed value (when applicable).

Default value is set automatically if the parameter is omitted and at the software reset (if the commandsetting is not stored in NVM). The factory-programmed value is set at the software reset when the settingis not modified with respect to the manufacturer setting; it is valid for the commands that store the settingin Nonvolatile Memory (NVM).

MLS provides APIs for following software modules:• LoRaWAN MAC Layer (MAC)• LoRaWAN Radio Layer (TAL)• Persistent Data Server (PDS)• Power Manager Module (PMM)• Hardware Abstraction Layer (HAL)

© 2018 Microchip Technology Inc. DS70005382A-page 1

Table of Contents

Introduction......................................................................................................................1

1. Quick Reference Info.................................................................................................41.1. Reference Documentation............................................................................................................41.2. Acronyms and Abbreviations Used.............................................................................................. 41.3. LoRaWAN Stack Directory Structure............................................................................................4

2. LoRaWAN API........................................................................................................... 62.1. MAC API.......................................................................................................................................6

2.1.1. LORAWAN_Init.............................................................................................................. 62.1.2. LORAWAN_Reset......................................................................................................... 62.1.3. LORAWAN_Join............................................................................................................ 72.1.4. LORAWAN_Send.......................................................................................................... 82.1.5. LORAWAN_SetAttr........................................................................................................92.1.6. LORAWAN_GetAttr..................................................................................................... 102.1.7. LORAWAN_Pause.......................................................................................................112.1.8. LORAWAN_Resume....................................................................................................112.1.9. LORAWAN_ForceEnable............................................................................................ 122.1.10. LORAWAN_ReadyToSleep......................................................................................... 12

2.2. TAL API...................................................................................................................................... 132.2.1. RADIO_Init...................................................................................................................132.2.2. RADIO_Receive.......................................................................................................... 132.2.3. RADIO_Transmit..........................................................................................................142.2.4. RADIO_TransmitCW....................................................................................................152.2.5. RADIO_StopCW..........................................................................................................152.2.6. RADIO_SetAttr............................................................................................................ 162.2.7. RADIO_GetAttr............................................................................................................16

2.3. Stack Attributes.......................................................................................................................... 172.3.1. Regional Configuration Parameters.............................................................................172.3.2. LoRaWAN/MAC Attributes...........................................................................................182.3.3. Radio/TAL Attributes....................................................................................................21

3. Supporting MAC Layers.......................................................................................... 233.1. Regional Band Layer..................................................................................................................233.2. PMM Layer.................................................................................................................................23

3.2.1. PMM Files....................................................................................................................233.2.2. PMM APIs....................................................................................................................23

3.2.2.1. PMM_Sleep...............................................................................................233.3. PDS Layer..................................................................................................................................24

3.3.1. PDS Files.....................................................................................................................243.3.2. PDS_Init.......................................................................................................................253.3.3. PDS_UnInit..................................................................................................................263.3.4. PDS_Store...................................................................................................................263.3.5. PDS_Restore...............................................................................................................27

SAM R34/R35


3.3.6. PDS_Delete.................................................................................................................273.3.7. PDS_IsRestorable....................................................................................................... 283.3.8. PDS_DeleteAll.............................................................................................................293.3.9. PDS_RestoreAll...........................................................................................................293.3.10. PDS_StoreAll...............................................................................................................303.3.11. PDS_RegFile...............................................................................................................303.3.12. PDS_UnRegFile.......................................................................................................... 31

3.4. Software Timer Module.............................................................................................................. 323.4.1. Software Timer Files....................................................................................................323.4.2. Software Timer APIs....................................................................................................32

3.4.2.1. SwTimerCreate..........................................................................................323.4.2.2. SwTimerGetTime.......................................................................................333.4.2.3. SystemTimerInit.........................................................................................333.4.2.4. SwTimerIsRunning.................................................................................... 333.4.2.5. SwTimerReset...........................................................................................343.4.2.6. SwTimerStart.............................................................................................343.4.2.7. SwTimerStop.............................................................................................35

4. HAL APIs................................................................................................................. 374.1. HAL Files....................................................................................................................................374.2. HAL_RadioInit............................................................................................................................ 374.3. HAL_RadioDeInit........................................................................................................................374.4. RADIO_Reset.............................................................................................................................374.5. RADIO_RegisterWrite................................................................................................................ 384.6. RADIO_RegisterRead................................................................................................................384.7. RADIO_FrameWrite................................................................................................................... 394.8. RADIO_FrameRead...................................................................................................................394.9. HAL_DisableRFCtrl....................................................................................................................394.10. HAL_EnableRFCtrl.....................................................................................................................40

5. Document Revision History..................................................................................... 43

The Microchip Web Site................................................................................................ 44

Customer Change Notification Service..........................................................................44

Customer Support......................................................................................................... 44

Microchip Devices Code Protection Feature................................................................. 44

Legal Notice...................................................................................................................45

Trademarks................................................................................................................... 45

Quality Management System Certified by DNV.............................................................46

Worldwide Sales and Service........................................................................................47

SAM R34/R35


1. Quick Reference Info

1.1 Reference DocumentationFollowing documents can be used for further study:

• SAM R34 MLS Getting Started Guide (DS50002812)• SAM R34/R35 Low Power LoRa® Sub-GHz SiP Datasheet (DS70005356)• ATSAMR34 Xplained Pro User Guide (DS50002803)

1.2 Acronyms and Abbreviations UsedTable 1-1. Acronyms and Abbreviations Used

Acronym Abbreviation

ABP Activation By Personalization

ADR Adaptive Data Rate

APPEUI Application End Unique Identifier

ASF Advanced Software Framework

DEVEUI End Device Unique Identifier

DR Data Rate

EDBG Embedded Debugger

FREQ Frequency

LoRa Long Range Modulation

LoRaWAN Long Range Wide Area Network

LPWAN Low Power Wide Area Network

MAC Media Access Controller

MLS Microchip LoRaWAN Stack

OTAA Over-The-Air Activation

PDS Persistent Data Storage

PMM Power Management Module

TAL Transceiver Abstraction Layer

UART Universal Asynchronous Receiver/Transmitter

1.3 LoRaWAN Stack Directory StructureThe LoRaWAN stack code base is available in the directory present in the package (src/ASF/thirdparty/wireless/lorawan).

SAM R34/R35Quick Reference Info


Table 1-2. LoRaWAN Stack Directory Structure

Directory Description

hal Contains implementation for radio's hardware interface, timers and so on.

inc Contains common include file(s)

libgen Contains the static library for LoRaWAN MAC and TAL

mac Contains headers of LoRaWAN MAC layer specification independent of regionalparameters

pmm Contains Power Management Module (PMM)

regparams Contains implementation of MAC layer functionality specific to the regional bands.

services Contains modules such as software timer, PDS, and AES

sys Contains system modules such as task manager, power management, and initialization

tal Contains transceiver related headers, drivers for supported transceivers

SAM R34/R35Quick Reference Info


2. LoRaWAN API

2.1 MAC APINote: All LoRaWAN MAC APIs and structures are present in the included file lorawan.h.

2.1.1 LORAWAN_InitDefinition: This function initializes the LoRaWAN MAC stack and radio software layers. During thisinitialization procedure:

• Software timers required for MAC operations are created• Application callback routine function pointers are stored in data base (DB)• Radio is initialized• MAC-related PDS files are registered

Syntax

void LORAWAN_Init(AppDataCb_t appdata, JoinResponseCb_t joindata);

Input Parameters

Table 2-1. Input Parameters

Parameter Name Parameter Type Description

appdata AppDataCb_t Pointer to function that is called when a down-link isreceived

joindata JoinResponseCb_t Pointer to function that is called when join response isreceived

Return Type and Values

API Type – Synchronous

2.1.2 LORAWAN_ResetDefinition: This function automatically resets the LoRaWAN stack software and initializes the stacks withthe parameters for the selected ISM band. During this Reset routine:

• MAC DB is initialized with default parameters• LoRaWAN regional parameters module is initialized• Radio layer default DB initialization is triggered

The Reset routine must be called after every software reset of the stack. To change the regional banddynamically, Reset routine calls the new ISM band, which un-initializes an old regional parameter and re-initiates the new ISM band. If the ISM band is same as the one stored in DB, the regional parameterinitializes the same default ISM band.

SAM R34/R35LoRaWAN API


Syntax

StackRetStatus_t LORAWAN_Reset (IsmBand_t ismBand);

Input Parameters



ismBand IsmBand_t ISM band types. Refer to Table 2-37 for a list of definedISM band types.


Table 2-3. Return Type


StackRetStatus_t ENUM Enumerated values containing all return types fromLoRaWAN layers

Table 2-4. Return Values

Return Value Reason

LORAWAN_SUCCESS LoRaWAN stack is successfully being reset and default valuesare restored

LORAWAN_INVALID_PARAMETER Given ISM band is invalid


2.1.3 LORAWAN_JoinDefinition: This API initiates the LoRaWAN join procedure and activates the end device to successfullyconnect to the LoRaWAN network.

Syntax

StackRetStatus_t LORAWAN_Join(ActivationType_t activationTypeNew);

Input Parameters



activationTypeNew ActivationType_t Activation type:• LORAWAN_OTAA = 0• LORAWAN_ABP = 1.








Return Value Reason

LORAWAN_SUCCESS LoRaWAN join procedure is successfully initiated

LORAWAN_MAC_PAUSED LoRaWAN MAC layer is paused. Join procedure willonly happen in Active state

LORAWAN_SILENT_IMMEDIATELY_ACTIVE The server decided that any further up-linktransmission is not possible from this end device

LORAWAN_NWK_JOIN_IN_PROGRESS Already one join procedure is in progress. MACcannot initiate join procedure until previous requestis completed.

LORAWAN_BUSY MAC layer is not IDLE. Until other transaction iscompleted, MAC cannot initiate join procedure

LORAWAN_KEYS_NOT_INITIALIZED For initiating join procedure, keys need to beavailable by MAC Layer. If keys are not set, MAClayer will not initiate join procedure.

API Type – Asynchronous

2.1.4 LORAWAN_SendDefinition: This API starts a bidirectional communication process and initiates the data packet sendprocedure. This API returns immediately after copying the data payload to MAC buffer and posting a taskto MAC scheduler. MAC transmits the data packet and wait for down-link packet(s). After down-linkprocedure is completed, MAC layer calls the application callback function and that ends this APIprocedure.

Syntax

StackRetStatus_t LORAWAN_Send (LorawanSendReq_t *lorasendreq);

Input Parameters



Table 2-8. Input Parameter


lorasendreq LorawanSendReq_t LoRaWAN send request –1. Transmission type2. Port value3. Pointer to application payload buffer4. Length of application payload






Return Value Reason

LORAWAN_SUCCESS LoRaWAN send request is successfully initiated

LORAWAN_MAC_PAUSED LoRaWAN MAC layer is paused. Join procedure will onlyhappen in Active state

LORAWAN_SILENT_IMMEDIATELY_ACTIVE The server decided that any further up-link transmissionis not possible from this end device

LORAWAN_INVALID_PARAMETER Port number is wrong

LORAWAN_BUSY MAC layer is not IDLE. Until other transaction iscompleted, MAC cannot initiate data packet sendprocedure

LORAWAN_NWK_NOT_JOINED LoRaWAN end device is not joined to the network

LORAWAN_INVALID_BUFFER_LENGTH Buffer length exceeds maximum payload size

LORAWAN_FCNTR_ERROR_REJOIN_NEEDED Re-joining is required.


2.1.5 LORAWAN_SetAttrDefinition: This API is used to set various LoRaWAN MAC attributes that are stored in the MAC database (DB).

Syntax

StackRetStatus_t LORAWAN_SetAttr(LorawanAttributes_t attrType, void *attrValue);



Input Parameters



attrType LorawanAttributes_t

List of LoRaWAN attributes. Refer to Table 2-38 for alist of defined attrType names.

attrValue Void pointer Value of attribute type.






Return Value Reason


LORAWAN_INVALID_PARAMETER Set attribute type is invalid

LORAWAN_BUSY MAC layer is not IDLE. Set attribute function cannot beperformed.


2.1.6 LORAWAN_GetAttrDefinition: This API is used to get various LoRaWAN MAC attributes that are stored in the MAC database.

Syntax

StackRetStatus_t LORAWAN_GetAttr(LorawanAttributes_t attrType, void *attrInput, void *attrOutput);

Input Parameters



attrType LorawanAttributes_t

List of LoRaWAN attributes. Refer to Table 2-38 for alist of defined attrType names.

attrInput Void pointer Pointer to attribute input value

attrOutput Void pointer Pointer to output value








Return Value Reason


LORAWAN_INVALID_PARAMETER Set attribute type is invalid

LORAWAN_BUSY MAC layer is not IDLE. Set attribute function cannot beperformed


2.1.7 LORAWAN_PauseDefinition: This function pauses the LoRaWAN stack functionality to allow transceiver (radio)configuration and functionality to be performed. Using "mac pause", radio commands can be generatedbetween a LoRaWAN protocol up-link application and the LoRaWAN protocol receive windows. Thisfunction will reply with the time interval in milliseconds that the transceiver can be used without affectingthe LoRaWAN functionality.

Syntax

uint32_t LORAWAN_Pause (void);

Input Parameters




Uint32_t Integer • Returns the number in milliseconds representinghow much it can be paused without affecting thefunctionality

• Returns ‘0’ if it cannot be paused, maximum valuewhen in Idle mode


2.1.8 LORAWAN_ResumeDefinition: This function resumes the LoRaWAN stack functionality, in order to continue normalfunctionality after being paused.



Syntax

void LORAWAN_Resume (void);

Input Parameters



2.1.9 LORAWAN_ForceEnableDefinition: The network can issue certain commands that would require the end device to go the SilentImmediately state. This mechanism disables any further communication of the module, effectivelyisolating it from the network. Using this function after this network command has been received restoresthe module’s connectivity by allowing it to send data.

Syntax

void LORAWAN_ForceEnable (void);

Input Parameters



2.1.10 LORAWAN_ReadyToSleepDefinition: This function is used for querying the stack’s readiness for sleep. This function has adependency on radio for the corresponding readiness check function in TAL.

Syntax

bool LORAWAN_ReadyToSleep(bool deviceResetAfterSleep);

Input Parameters



deviceResetAfterSleep boolean • ‘true’ means device is reset during the wake up• ‘false’ means device is not reset during wake up






Bool Boolean • ‘true’ – stack is in Ready state to sleepor

• ‘false’


2.2 TAL APINote: All LoRaWAN TAL APIs and structures are present in the included file radio_interface.h.

2.2.1 RADIO_InitDefinition: This API initializes the radio software module. During this initialization routine:

• Radio DB is updated with default parameters• Call-back routines for transmit and receive are updated in radio layer• DIO interrupt handlers are initialized• SX1276 transceiver is initialized and put into sleep after successful initialization

Syntax

void RADIO_Init(void);

Input Parameters



2.2.2 RADIO_ReceiveDefinition: This function receives the data and stores it in the buffer pointer space by doing a task post tothe RADIO_RxHandler.Syntax

RadioError_t RADIO_Receive(RadioReceiveParam_t *param);

Input Parameters



param RadioReceiveParam_t A structure for storing the receive parameters.

Using RadioReceiveParam_t, upper layers can control time window for receive operation, indefinitereceive open or receive stop.






RadioError_t ENUM Enumerated values containing all return types from radiolayer


Return Value Reason

ERR_RADIO_BUSY Radio is not in IDLE state

ERR_NONE Radio in IDLE state and configuring transceiver to Receivestate is initiated

ERR_INVALID_REQ Radio is already in Receive state


2.2.3 RADIO_TransmitDefinition: This function transmits the data by doing a task post to the RADIO_TxHandler.Syntax

RadioError_t RADIO_Transmit(RadioTransmitParam_t *param);

Input Parameter



param RadioTransmitParam_t

A structure for storing the transmit parameters






Return Value Reason


ERR_NONE Radio in IDLE state and configuring transceiver to Transmitstate is initiated

ERR_DATA_SIZE Data buffer in transmit request is greater than max size (64)




2.2.4 RADIO_TransmitCWDefinition: This function transmits a continuous wave. This API uses radio parameters (such asFrequency, Modulation, Spreading factor and so on) stored in TAL data base to transmit the continuouswave. Radio parameters can be configured using RADIO_SetAttr API described in 2.2.6 RADIO_SetAttr. If user did not configure any parameters, this API will use default parameters stored indata base. All default values for the radio layer are given in the 2.3.3 Radio/TAL Attributes.

Syntax

RadioError_t RADIO_TransmitCW(void);

Input Parameters






Return Value Reason


ERR_NONE Radio in IDLE state and starts the continuous transmission


2.2.5 RADIO_StopCWDefinition: This function stops the transmission of continuous wave.

Syntax

RadioError_t RADIO_StopCW(void);

Input Parameters








Return Value Reason


ERR_NONE Radio in IDLE state and stopping the continuoustransmission


2.2.6 RADIO_SetAttrDefinition: This function writes the given value to the specified attribute.

Syntax

RadioError_t RADIO_SetAttr(RadioAttribute_t attribute, void *value);

Input Parameter



attribute RadioAttribute_t Structure for attribute list. Refer to Table 2-39 for alist of defined attribute names.





Table 2-32. Return Value

Return Value Reason




2.2.7 RADIO_GetAttrDefinition: This function gets the stored value of the specified attribute.

Syntax

RadioError_t RADIO_GetAttr(RadioAttribute_t attribute, void *value);

Input Parameter





attribute RadioAttribute_t Structure for attribute list. Refer to Table 2-39 fora list of defined attribute names.






Return Value Reason




2.3 Stack Attributes

2.3.1 Regional Configuration ParametersNote: All LoRaWAN Regional Configuration Parameters are present in the included file conf/conf_regparams.h.Table 2-36. Regional Configuration Parameters

Macro Definition Default Value Description

MAC_DEF_TX_POWER_

• For AS: 1• For AU: 7• For EU: 1• For IN: 1• For JP: 1• For NA: 7

Transmission power table index

MAC_DEF_TX_CURRENT_DATARATE_

• For AS: DR3• For AU: DR3• For EU: DR3• For IN: DR3• For JP: DR3• For NA: DR2

Initial data rate to be used by applicationfor up-link



...........continuedMacro Definition Default Value Description

MAC_DATARATE_MIN

• For AS: DR7• For AU: DR6• For EU: DR7• For IN: DR7• For JP: DR7• For NA: DR4

Minimum data rate to be used by enddevice

MAC_DATARATE_MAX_r DR0 (all regions) Maximum data rate to be used by enddevice

Note: 1. The value is replaced by a 2-letter region identifier. The possible region identifiers are: NA, AS,

AU, EU, IN, JP, and KR.

Table 2-37. ISM Band Types

ISM Band Description

ISM_EU868 EU 863 - 870MHz ISM Band

ISM_EU433 EU 433MHz ISM Band

ISM_NA915 North America

ISM_AU915 Australia

ISM_KR920 South Korea

ISM_JPN923 Japan

ISM_BRN923 Brunei

ISM_CMB923 Cambodia

ISM_INS923 Indonesia

ISM_LAOS923 Laos

ISM_NZ923 New Zealand

ISM_SP923 Singapore

ISM_TWN923 Taiwan

ISM_THAI923 Thailand

ISM_VTM923 Vietnam

ISM_IND865 India

2.3.2 LoRaWAN/MAC AttributesNote: All LoRaWAN MAC Attributes are set or read using the LORAWAN_SetAttr, orLORAWAN_GetAttr APIs, respectively. Refer to 2.1.5 LORAWAN_SetAttr and 2.1.6 LORAWAN_GetAttr.



Table 2-38. LoRaWAN/MAC Attributes

Name (attrType) Type Range Address Default

ACKTIMEOUT uint16 0x0000-0xffff Read/Write 0x7D0

ADR bool True (Enabled) False(Disabled) Read/Write –

ADR_ACKDELAY uint8 0x00-0xff Read/Write 0x20

ADR_ACKLIMIT uint8 0x00-0xff Read/Write 0x40

APPS_KEY uint8[16] – Read/Write –

APP_EUI uint8[8] – Read/Write –

APP_KEY uint8[16] – Read/Write –

AUTOREPLY bool True, False Read/Write –

BATTERY uint8 0x00-0xff Read/Write 0xff (Batterylevel invalid)

CH_PARAM_FREQUENCY uint32 0x00000000-0xffffffff Read/Write –

CH_PARAM_DR_RANGE uint8 – Read/Write –

CH_PARAM_STATUS bool True, False Read/Write –

CURRENT_DATARATE uint8 DR0-DR7 Read/Write DR0

DEV_ADDR uint32 0x00000000-0xffffffff Read/Write –

DEV_EUI uint8[8] – Read/Write –

DOWNLINK_COUNTER uint32 0x00000000-0xffffffff Read/Write –

EDCLASS uint8 0 (Class A), 1 (ClassB), 2 (Class C) Read/Write 0 (Class A)

EDCLASS_SUPPORTED uint8 1 (Class A), 5 (ClassA and Class C) Read/WriteLORAWAN_SUPPORTED_ED_CLASSES

FHSS_CALLBACKFHSSCallback_t (functionpointer)

Valid function address Read/Write –

ISMBAND uint8 0x00-0xff Read Only ISM_EU868

JOINACCEPT_DELAY1 uint16 0x0000-0xffff Read/Write 0x1388



...........continuedName (attrType) Type Range Address Default

JOINACCEPT_DELAY2 uint16 0x0000-0xffff Read/Write 0x1770

LINK_CHECK_GWCNT uint8 0x00-0xff Read Only 0x00

LINK_CHECK_MARGIN uint8 0x00-0xff Read Only 0xff

LINK_CHECK_PERIOD uint16 0x0000-0xffff Read/Write 0x0000

LORAWAN_STATUS uint32 0x00000000-0xffffffff Read Only 0x00

MAX_FCOUNT_GAP uint16 0x0000-0xffff Read/Write 0x4000

MCAST_APPS_KEY uint8[16] – Read/Write –

MCAST_ENABLE bool True, False Read/Write 0x00

MCAST_FCNT_DOWN uint16 0x0000-0xffff Read Only –

MCAST_GROUP_ADDR uint32 0x00000000-0xffffffff Read/Write –

MCAST_NWKS_KEY uint8[16] – Read/Write –

NWKS_KEY uint8[16] – Read/Write –

CNF_RETRANSMISSION_NUM uint8 0x00-0xff Read/Write –

UNCNF_REPETITION_NUM uint8 0x00-0xff Read/Write –

RX2_WINDOW_PARAMSReceiveWindow2 Params_t(ENUM)

– Read/Write Specific toregion

RX_DELAY1 uint16 0x0000-0xffff Read/Write 0x3e8

RX_DELAY2 uint16 0x0000-0xffff Read/Write 0x7d0

SYNC_WORD uint8 0x00-0xff Read/Write 0x34

TX_POWER uint8For EU: 0 to 5,for NA:5,7,8,9,10

Read/WriteFor EU: 1,For NA: 7

UPLINK_COUNTER uint32 0x00000000-0xffffffff Read/Write 0x00000000



2.3.3 Radio/TAL AttributesNote: All radio/TAL Attributes are set or read using the RADIO_SetAttr, or RADIO_GetAttr APIsrespectively. Refer to 2.2.6 RADIO_SetAttr and 2.2.7 RADIO_GetAttr.

Table 2-39. Radio/TAL Attributes

Name (attribute) Type Range Access Default

BANDWIDTH RadioLoRaBandwidth_t (ENUM)enumeratedvalues Read/Write BW_125KHZ

CHANNEL_FREQUENCY uint32validfrequencyvalue

Read/Write

EU:FREQ_868100KHZ,NA:FREQ_923300KHZ

CHANNEL_FREQUENCY_DEVIATION uint32

0x00000000 –0xffffffff

Read/Write 0x61a8

CRC_ON uint80x00(Disabled),0x01(Enabled)

Read/Write 0x01 (Enabled)

ERROR_CODING_RATE RadioErrorCodingRate_t (ENUM)enumeratedvalues Read/Write CR_4_5

FREQUENCY_HOP_PERIOD uint16 0x0000 -0xffff Read Only 0x0000

FSK_AFC_BW RadioFSKShaping_t (ENUM)enumeratedvalues Read/Write FSKBW_83_3KHZ

FSK_BIT_RATE uint320x00000000 –0xffffffff

Read/Write 0xc350

FSK_DATA_SHAPING RadioFSKShaping_t (ENUM)enumeratedvalues Read/Write

FSK_SHAPING_GAUSS _BR_0_5

FSK_RX_BW RadioFSKShaping_t (ENUM)enumeratedvalues Read/Write FSK_BW_50_0KHZ

FSK_SYNC_WORD uint8 [8] 0x00 -0xff Read/Write{0xc1, 0x94,0xc1}

FSK_SYNC_WORD_LEN uint8 0x00 -0x08 Read/Write 0x03



...........continuedName (attribute) Type Range Access Default

IQINVERTED uint80x00(Disabled),0x01(Enabled)

Read/Write 0x00 (Disabled)

LORA_SYNC_WORD uint8 0x00 -0xff Read/Write 0x34

MODULATION RadioModulation_t (ENUM)enumeratedvalues Read/Write MODULATION_LORA

OUTPUT_POWER uint8 0x00 -0xff Read/Write 0x01

PABOOST uint8 0x00 -0xff Read/Write 0x01

PACKET_SNR int8 -128 to +127 Read Only -128

PREAMBLE_LEN uint16 0x0000 -0xffff Read/Write 0x08

RADIO_CALLBACK RadioCallback_t(function pointer)

Valid functionaddress Read/Write –

RADIO_LBT_PARAMS RadioLBT_t(structure)

structuremember type Read/Write

{0x00}

SPREADING_FACTOR RadioDataRate_t(ENUM)

enumeratedvalues Read/Write SF_12

WATCHDOG_TIMEOUT uint320x00000000 –0xffffffff

Read/Write 0x3a98



3. Supporting MAC Layers

3.1 Regional Band LayerRegional band APIs are not to be used by an application directly. All API and attribute configuration of aregional band must happen via MAC layer. Necessary attributes are available as part of MAC attribute listand the application can use that to configure the regional band layer.

3.2 PMM LayerMLS provides Power Management Module (PMM) in the stack. An application running on top of the MLScan choose to use PMM to save power during idle times. Power saving is done by switching the MCU toone of the available low-power modes. Currently, PMM is supported only on the SAM R34 microcontroller.In SAM R34, currently, STANDBY and BACKUP Sleep modes are supported by PMM.

3.2.1 PMM FilesTable 3-1. PMM Files

Files Description

pmm/inc/pmm.h This file contains the public API for the PowerManagement Module. This needs to be included by theapplication if power management is needed.

pmm/src/pmm.c This file contains the implementation of powermanagement that is the conditions for entering to sleep,calculating the sleep time, configuring and backing upthe timers and so on.

hal/inc/sleep_timer.h This file contains the APIs for the sleep timer. It is usedby the PMM to keep track of the sleep duration and alsoto wake-up the device in timed sleep scenarios.

hal/src/sleep_timer/sam0/sleep_timer.c

This file contains the implementation of sleep timer.Currently, sleep timer uses RTC internally.

hal/inc/sleep.h This file contains the API to switch the MCU to desiredSleep mode.

hal/src/sleep/sam0/src/sleep.c This file contains the implementation to switch the MCUto Sleep mode. Currently, the SAM R34 supports theSTANDBY and BACKUP mode.

3.2.2 PMM APIsNote: All PMM APIs are present in the included file pmm/inc/pmm.h.

3.2.2.1 PMM_SleepDefinition: This function puts the system to sleep if possible.

SAM R34/R35Supporting MAC Layers


Syntax

PMM_Status_t PMM_Sleep(PMM_SleepReq_t *req);

Input Parameter



req PMM_SleepReq_t Pointer to sleep request structure when being calledfrom application

Note: PMM_SleepReq_t – Definition is available in pmm.h.Return Type and Values



PMM_Status_t ENUM Describes the status of power manager for a sleeprequest

Note: PMM_Status_t – Definition is available in pmm.h.Table 3-4. Return Values

Return Value Reason

PMM_SLEEP_REQ_DENIED PMM denies the request because system is not ready to sleep at theinstance of sleep call

PMM_SLEEP_REQ_PROCESSED Power manager accepted and have already processed the request


3.3 PDS LayerPersistent Data Server (PDS) module facilitates storing of stack parameters/attributes in NonvolatileMemory (NVM) of MCU. The PDS module interfaces between NVM driver and stack.

3.3.1 PDS FilesTable 3-5. PDS Files

Files Description

services/pds/inc/pds_common.h

Header file for PDS common typedefs and structures

services/pds/inc/pds_interface.h

The PDS interface file which provides the API definitions forexternal layers



...........continuedFiles Description

services/pds/inc/pds_nvm.h The PDS NVM header file which contains NVM abstractions forPDS

services/pds/inc/pds_task_handler.h

The PDS driver task manager header file which calls PDS taskscheduler

services/pds/inc/pds_wl.h The PDS wear leveling header file which contains PDS wearleveling headers

services/pds/src/pds_interface.c

The PDS interface source file which has implementations for allpublic API's

services/pds/src/pds_nvm.c The PDS NVM source file which contains NVM abstraction forPDS

services/pds/src/pds_task_handler.c

The PDS driver task manager source file which contains PDStask scheduler

services/pds/src/pds_wl.c The PDS wear leveling source file which contains PDS wearleveling implementation

3.3.2 PDS_InitDefinition: Initialize the PDS software module.

Syntax

PdsStatus_t PDS_Init(void);

Input Parameter




PdsStatus_t ENUM PDS status codes. Definition available inpds_interface.h


Return Value Reason

PDS_OK PDS operation is success

PDS_ERROR NVM driver initialization failed

PDS_NOT_ENOUGH_MEMORY EEPROM_SIZE configured in conf_nvm.h is greater thanHW configured size in user page




3.3.3 PDS_UnInitDefinition: This API will disable storing the data in PDS.

Syntax

PdsStatus_t PDS_UnInit(void);

Input Parameter

Return Type and Value





Return Value Reason



3.3.4 PDS_StoreDefinition: This function sets the store operation bit in the file-marks for the item in PDS.

Syntax

dsStatus_t PDS_Store(PdsFileItemIdx_t pdsFileItemIdx, uint8_t item);

Input Parameters



pdsFileItemIdx PdsFileItemIdx_t PDS file ID of the item

item uint8_t PDS item ID








Return Value Reason


PDS_INVALID_FILE_IDX File ID is invalid


3.3.5 PDS_RestoreDefinition: This function restores an item from PDS to RAM.

Syntax

PdsStatus_t PDS_Restore(PdsFileItemIdx_t pdsFileItemIdx, uint8_t item);

Input Parameters


Parameters Name Parameters Type Description

pdsFileItemIdx PdsFileItemIdx_t

PDS file ID of the item







Return Value Reason



PDS_NOT_FOUND Item ID is not found in File ID or File reference is not in NVM

PDS_ITEM_DELETED Item is deleted from the PDS


3.3.6 PDS_DeleteDefinition: This function will set the delete operation for the item in the file ID bit mask.



Syntax

PdsStatus_t PDS_Delete(PdsFileItemIdx_t pdsFileItemIdx, uint8_t item);

Input Parameters


Parameter Names Parameter Types Description

pdsFileItemIdx PdsFileItemIdx_t PDS file ID of the item







Return Value Reason




3.3.7 PDS_IsRestorableDefinition: This function checks if all the registered files are restorable.

Syntax

bool PDS_IsRestorable(void);

Input Parameters




bool Boolean • ‘true’ – Valid PDS data is available in EEPROM• ‘false’ – No valid data is available in EEPROM




3.3.8 PDS_DeleteAllDefinition: This function will erase all the items stored in the PDS.

Syntax

PdsStatus_t PDS_DeleteAll(void);

Input Parameters

Return Type and Value





Return Value Reason



3.3.9 PDS_RestoreAllDefinition: This function will restore all the items from the PDS to RAM from all registered files.

Syntax

PdsStatus_t PDS_RestoreAll(void);

Input Parameters






Return Value Reason


PDS_NOT_FOUND PDS read from NVM failed




3.3.10 PDS_StoreAllDefinition: This function will set the store operation to all the items stored in all the registered files inPDS.

Syntax

PdsStatus_t PDS_StoreAll(void);

Input Parameters






Return Value Reason



3.3.11 PDS_RegFileDefinition: This function registers a file to the PDS.

Syntax

PdsStatus_t PDS_RegFile(PdsFileItemIdx_t argFileId, PdsFileMarks_t argFileMarks);

Input Parameters


Parameter Names Parameter Types Description

argFileId PdsFileItemIdx_t

PDS file ID of the item.

argFileMarks PdsFileMarks_t This structure contains details about number of items infile, RAM address for each item and size of each itemin a list form. This will be stored in PDS and used toretrieve data during PDS operations.






PdsStatus_t ENUM PDS status codes. Definition available inpds_interface.h.


Return Value Reason


PDS_INVALID_FILE_IDX File ID in the argument is not valid one


3.3.12 PDS_UnRegFileDefinition: This function un-registers a file to the PDS. This makes the data stored in the NVM invalidand any operation on this file ID will be invalid after this point.

Syntax

PdsStatus_t PDS_UnRegFile(PdsFileItemIdx_t argFileId);

Input Parameters



argFileId PdsFileItemIdx_t

PDS file ID of the item




PdsStatus_t ENUM PDS status codes. Definition available inpds_interface.h.


Return Value Reason


PDS_INVALID_FILE_IDX File ID in the argument is not valid one




3.4 Software Timer ModuleTimer provides the facility to measure desired amount of time. The SAM R34 has five hardware timersthat can measure only five individual amounts of time simultaneously. Every component in MLS such asradio, MAC and APP have timer requirements. Therefore, timers need to be efficiently shared by all therequired components.

The software timer module provides the needed abstractions for MLS to use timers. It handles theoperation of the hardware timer, for measuring the given amount of time, thus freeing the user frommanaging the hardware timers.

The software timer provides a set of interfaces to initialize, create, start, stop timers and so on. If the usercalls timer start, the software timer module takes Timer duration and callback function as input. Once theduration is elapsed, user-supplied callback function is invoked.

Simultaneously, more than one software timer can be started, which is automatically sorted according totheir duration and expires accordingly. Besides, running for user-desired duration, the software timermodule also keeps track of system time. System time is measured starting from the initialization of thesoftware timer during reset.

MLS currently supports a maximum of 25 software timer instances. It can be customized as perapplication requirements by changing the TOTAL_NUMBER_OF_TIMERS macro in the conf_app.h file.Note: To change the number of software timers, the user must rebuild an application firmware.

3.4.1 Software Timer FilesTable 3-32. Software Timer Files

Files Description

services/sw_timer/inc/sw_timer.h

Header file for software timer module

services/ sw_timer/inc/sw_timer.c

Software timer module source file

3.4.2 Software Timer APIs

3.4.2.1 SwTimerCreateDefinition: Returns a timer ID to be used before starting a timer. Timer ID is taken from common softwaretimer free pool.

Syntax

StackRetStatus_t SwTimerCreate(uint8_t *timerId);

Input Parameters



timerId uint8_t Timer ID of the item





StackRetStatus_t ENUM List of enumerated values for return status

Return Value Reason

LORAWAN_SUCCESS New timerId is allocated

LORAWAN_RESOURCE_UNAVAILABLE There is no more timerId to allocate


3.4.2.2 SwTimerGetTimeDefinition: Get current system time. Returns the system time in micro seconds.

Syntax

uint64_t SwTimerGetTime(void);

Input Parameters




uint64_t 64-bit unsignedinteger

System time in micro seconds


3.4.2.3 SystemTimerInitDefinition: Initializes the software timer module. Timer free pool array gets initialized. Hardware (HW)timer callback assignment and TC initialization will be carried out.

Syntax

void SystemTimerInit(void);

Input Parameters



3.4.2.4 SwTimerIsRunningDefinition: Checks whether a given timer is running or not.

Syntax

bool SwTimerIsRunning(uint8_t timerid);



Input Parameters



timerId uint8_t Timer identifier



Parameters Name Parameter Type Description

bool Boolean • ‘true’ – Timer is running• ‘false’ – Timer is stopped or not started


3.4.2.5 SwTimerResetDefinition: Resets the software timer module. Clears the SW timer pool.

Syntax

void SystemTimerReset(void);

Input Parameters



3.4.2.6 SwTimerStartDefinition: This function starts a regular timer and installs the corresponding callback function handlingthe timeout event.

Syntax

StackRetStatus_t SwTimerStart(uint8_t timerId, uint32_t timerCount,SwTimeoutType_t timeoutType, void *timerCb, void *paramCb);

Input Parameters




timerCount uint32_t Timeout in microseconds



...........continuedParameter Name Parameter Type Description

timeoutType SwTimeoutType_t • SW_TIMEOUT_RELATIVE – The timeout isrelative to the current time

• SW_TIMEOUT_ABSOLUTE – The timeout is anabsolute value

timerCb Void pointer Callback handler invoked upon timer expiry

paramCb Void pointer Argument for the callback handler




StackRetStatus_t ENUM List of enumerated values for return Status


Return Value Reason

LORAWAN_SUCCESS Timer is started successfully

LORAWAN_INVALID_REQUEST Timer is already running

LORAWAN_INVALID_PARAMETER Timer ID, timeout type or timeout value is wrong


3.4.2.7 SwTimerStopDefinition: Stops a running timer. This API stops a running timer with specified timerId - Timer identifier

Syntax

StackRetStatus_t SwTimerStop(uint8_t timerId);

Input Parameters







StackRetStatus_t ENUM List of enumerated values for return status




Return Value Reason

LORAWAN_SUCCESS Timer is started successfully

LORAWAN_INVALID_REQUEST Timer is not running

LORAWAN_INVALID_PARAMETER Timer ID value is wrong




4. HAL APIs

4.1 HAL FilesTable 4-1. HAL Files

Files Description

hal/inc/radio_driver_hal.h Header file for HALhal/src/radio_driver_hal.c HAL source file

4.2 HAL_RadioInitDefinition: This function initializes the radio hardware SPI interface, DIO and Reset pins.

Syntax

Void HAL_RadioInit (void)

Input Parameters


API Type - Synchronous

4.3 HAL_RadioDeInitDefinition: This function de-initializes the radio hardware SPI interface.

Syntax

Void HAL_RadioDeInit (void)

Input Parameters



4.4 RADIO_ResetDefinition: This function resets the Radio hardware by pulling the reset pin low.

Syntax

Void RADIO_Reset (void)

SAM R34/R35HAL APIs


Input Parameters



4.5 RADIO_RegisterWriteDefinition: This function is used to write a byte of data to the radio register

Syntax

void RADIO_RegisterWrite(uint8_t reg, uint8_t value)

Input Parameters

Parameter Names Parameter Type Description

reg uint8_t Register address to be written

value uint8_t Value to be written into the radio register



4.6 RADIO_RegisterReadDefinition: This function is used to read a byte of data from the radio register.

Syntax

Uint8_t RADIO_RegisterRead(uint8_t reg)

Input Parameters


reg uint8_t Register address to be read



Uint8_t 8-bit unsigned integer Value read from the radio register


SAM R34/R35HAL APIs


4.7 RADIO_FrameWriteDefinition: This function is used to write a stream of data into the radio frame buffer.

Syntax

void RADIO_FrameWrite(uint8_t offset, uint8_t* buffer, uint8_t bufferLen)

Input Parameters


offset Uint8_t FIFO offset to be written to

buffer Uint8_t * Pointer to the data to be written into the frame buffer

bufferLen Uint8_t Length of the data to be written



4.8 RADIO_FrameReadDefinition: This function is used to read a stream of data from the radio frame buffer.

Syntax

void RADIO_FrameRead(uint8_t offset, uint8_t* buffer, uint8_t bufferLen)

Input Parameters


offset Uint8_t FIFO offset to be read from

buffer Uint8_t * Pointer to the data to be read from the frame buffer

bufferLen Uint8_t Length of the data to be read from the frame buffer



4.9 HAL_DisableRFCtrlDefinition: This function is called by the stack to indicate HAL for resetting the Rfctrl GPIO pins to theirinactive state. Based on RFCTRL1 and RFCTRL2 values, different GPIOs will be controlled.

SAM R34/R35HAL APIs


Syntax

void HAL_DisableRFCtrl(RFCtrl1_t RFCtrl1, RFCtrl2_t RFCtrl2)

Input Parameters

ParametersName

Parameter Type Description

RFCtrl1 ENUM RF Control 1 indicates the FREQUENCY band (Higher UHF orLower UHF) or PA Boost enabled.

RFO_LF = 0

RFO_HF = 1

PA_BOOST = 2

RFCtrl2 ENUM RF Control 2 indicates Transmit or Receive path

RX = 0

TX = 1

Return Types and Values


4.10 HAL_EnableRFCtrlDefinition: This function is called by the stack to indicate HAL about which RF path signal is used forTX/RX and based on the RF front-end design respective GPIO pin will be controlled.

Usage of RFCTRL1 variable:

RFCtrl1 parameter is used to select the RF output frequency range (or band). Following values areapplicable for the parameter.

• RFO_LF is used when RF output frequency range is lesser than 525 MHz (band 2/3).• RFO_HF is used when RF output frequency range is greater than 779 MHz (band 1).• PA_BOOST is used regardless of RF output frequency. But, when TX power is greater than +15

dBm.• When TX power is between -4 dBm to +15 dBm, either RFO_LF or RFO_HF should be used. The

following table describes the frequency range and TX power of RFCtrl1.

Note: For more details on the frequency limits and required bands, refer to the SX1276 data sheet.

Table 4-2. RFCtrl1 Frequency Range and Power

ENUM Value Frequency Region TX Power

RFO_LF < 525 MHz -4 to +15 dBm

RFO_HF From 779 MHz -4 to +15 dBm

SAM R34/R35HAL APIs


...........continuedENUM Value Frequency Region TX Power

PA_BOOST All frequencies +2 to +17 dBm

• All 3 ENUM values represent a pin out from SX1276 transceiver.• RFCtrl1 value indicates in which of these 3 pin-out the signal will be received. For example: if

Frequency if 868MHz and Output power is +10dBm, then signal will come from RFO_HF pin.• Refer SX1276 data sheet, RF power amplifiers section for more details on Transceiver operation

with different frequencies and output power.• Refer SAM R34 data sheet for pin mapping details for these 3 pins.

Usage of RFCTRL2 variable:

RFCtrl2 parameter is used to select either transmit or receive operation by transceiver• For receive operation, front-end RF circuitry routes the received signal through either RFI_LF or

RFI_HF pin.• Based on the frequency range, either RFI_LF or RFI_HF is selected.• Frequency range can be determined from RFCtrl1 parameter, in order to select between RFI_LF

and RFI_HF.

Master truth table for RFCtrl1 and RFCtrl2,

RFCtrl1 RFCtrl2 Operation

RFO_LF TX • Transmit operation• Transmit Frequency - < 525 MHz• Output power - -4 to +15 dBM

RFO_HF TX • Transmit operation• Transmit Frequency - >779 MHz• Output power - -4 to +15 dBM

PA_BOOST Don’t care • Transmit operation• Transmit Frequency - All• Output power - >15 dBm

RFO_LF RX • Receive Operation• Receive Frequency - < 525 MHz

RFO_HF RX • Receive Operation• Receive Frequency - > 779 MHz

For the ATSAMR34 Xplained Pro:

1. Only RFO_HF and PA_BOOST values of RFCtrl1 is valid and used to set BAND_SELECT pin.Refer ATSAMR34 Xplained Pro User Guide for more details on front-end RF circuit design.

2. RFO_LF is not used. Since ATSAM R34 Xplained Pro doesn’t support frequency operation in < 525MHz.

SAM R34/R35HAL APIs


3. RFCtrl2 input is not used. The ATSAMR34 Xplained Pro front-end RF circuit doesn’t need to controlbased on TX and RX operation.

Syntax

void HAL_EnableRFCtrl(RFCtrl1_t RFCtrl1, RFCtrl2_t RFCtrl2)

Input Parameters

ParametersName

Parameter Type Description

RFCtrl1 ENUM RF Control 1 indicates the FREQUENCY band (Higher UHF orLower UHF) or PA Boost enabled.

• RFO_LF = 0• RFO_HF = 1• PA_BOOST = 2

RFCtrl2 ENUM RF Control 2 indicates Transmit or Receive path.

• RX = 0• TX = 1

Return Types and Values


SAM R34/R35HAL APIs


5. Document Revision HistoryRevision Date Section Description

A 10/2018 Document Initial Revision

SAM R34/R35Document Revision History


The Microchip Web Site

Microchip provides online support via our web site at http://www.microchip.com/. This web site is used asa means to make files and information easily available to customers. Accessible by using your favoriteInternet browser, the web site contains the following information:

• Product Support – Data sheets and errata, application notes and sample programs, designresources, user’s guides and hardware support documents, latest software releases and archivedsoftware

• General Technical Support – Frequently Asked Questions (FAQ), technical support requests,online discussion groups, Microchip consultant program member listing

• Business of Microchip – Product selector and ordering guides, latest Microchip press releases,listing of seminars and events, listings of Microchip sales offices, distributors and factoryrepresentatives

Customer Change Notification Service

Microchip’s customer notification service helps keep customers current on Microchip products.Subscribers will receive e-mail notification whenever there are changes, updates, revisions or erratarelated to a specified product family or development tool of interest.

To register, access the Microchip web site at http://www.microchip.com/. Under “Support”, click on“Customer Change Notification” and follow the registration instructions.

Customer Support

Users of Microchip products can receive assistance through several channels:

• Distributor or Representative• Local Sales Office• Field Application Engineer (FAE)• Technical Support

Customers should contact their distributor, representative or Field Application Engineer (FAE) for support.Local sales offices are also available to help customers. A listing of sales offices and locations is includedin the back of this document.

Technical support is available through the web site at: http://www.microchip.com/support

Microchip Devices Code Protection Feature

Note the following details of the code protection feature on Microchip devices:

• Microchip products meet the specification contained in their particular Microchip Data Sheet.• Microchip believes that its family of products is one of the most secure families of its kind on the

market today, when used in the intended manner and under normal conditions.• There are dishonest and possibly illegal methods used to breach the code protection feature. All of

these methods, to our knowledge, require using the Microchip products in a manner outside theoperating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so isengaged in theft of intellectual property.

• Microchip is willing to work with the customer who is concerned about the integrity of their code.

SAM R34/R35


http://www.microchip.com/http://www.microchip.com/http://www.microchip.com/support

• Neither Microchip nor any other semiconductor manufacturer can guarantee the security of theircode. Code protection does not mean that we are guaranteeing the product as “unbreakable.”

Code protection is constantly evolving. We at Microchip are committed to continuously improving thecode protection features of our products. Attempts to break Microchip’s code protection feature may be aviolation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your softwareor other copyrighted work, you may have a right to sue for relief under that Act.

Legal Notice

Information contained in this publication regarding device applications and the like is provided only foryour convenience and may be superseded by updates. It is your responsibility to ensure that yourapplication meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS ORWARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORYOR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITSCONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE.Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in lifesupport and/or safety applications is entirely at the buyer’s risk, and the buyer agrees to defend,indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resultingfrom such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectualproperty rights unless otherwise stated.

Trademarks

The Microchip name and logo, the Microchip logo, AnyRate, AVR, AVR logo, AVR Freaks, BitCloud,chipKIT, chipKIT logo, CryptoMemory, CryptoRF, dsPIC, FlashFlex, flexPWR, Heldo, JukeBlox, KeeLoq,Kleer, LANCheck, LINK MD, maXStylus, maXTouch, MediaLB, megaAVR, MOST, MOST logo, MPLAB,OptoLyzer, PIC, picoPower, PICSTART, PIC32 logo, Prochip Designer, QTouch, SAM-BA, SpyNIC, SST,SST Logo, SuperFlash, tinyAVR, UNI/O, and XMEGA are registered trademarks of Microchip TechnologyIncorporated in the U.S.A. and other countries.

ClockWorks, The Embedded Control Solutions Company, EtherSynch, Hyper Speed Control, HyperLightLoad, IntelliMOS, mTouch, Precision Edge, and Quiet-Wire are registered trademarks of MicrochipTechnology Incorporated in the U.S.A.

Adjacent Key Suppression, AKS, Analog-for-the-Digital Age, Any Capacitor, AnyIn, AnyOut, BodyCom,CodeGuard, CryptoAuthentication, CryptoAutomotive, CryptoCompanion, CryptoController, dsPICDEM,dsPICDEM.net, Dynamic Average Matching, DAM, ECAN, EtherGREEN, In-Circuit Serial Programming,ICSP, INICnet, Inter-Chip Connectivity, JitterBlocker, KleerNet, KleerNet logo, memBrain, Mindi, MiWi,motorBench, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, OmniscientCode Generation, PICDEM, PICDEM.net, PICkit, PICtail, PowerSmart, PureSilicon, QMatrix, REAL ICE,Ripple Blocker, SAM-ICE, Serial Quad I/O, SMART-I.S., SQI, SuperSwitcher, SuperSwitcher II, TotalEndurance, TSHARC, USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, and ZENA aretrademarks of Microchip Technology Incorporated in the U.S.A. and other countries.

SQTP is a service mark of Microchip Technology Incorporated in the U.S.A.

Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries.

GestIC is a registered trademark of Microchip Technology Germany II GmbH & Co. KG, a subsidiary ofMicrochip Technology Inc., in other countries.

All other trademarks mentioned herein are property of their respective companies.

SAM R34/R35


© 2018, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved.

ISBN: 978-1-5224-3781-9

Quality Management System Certified by DNV

ISO/TS 16949Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and waferfabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in Californiaand India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC®

DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory andanalog products. In addition, Microchip’s quality system for the design and manufacture of developmentsystems is ISO 9001:2000 certified.

SAM R34/R35


AMERICAS ASIA/PACIFIC ASIA/PACIFIC EUROPECorporate Office2355 West Chandler Blvd.Chandler, AZ 85224-6199Tel: 480-792-7200Fax: 480-792-7277Technical Support:http://www.microchip.com/supportWeb Address:www.microchip.comAtlantaDuluth, GATel: 678-957-9614Fax: 678-957-1455Austin, TXTel: 512-257-3370BostonWestborough, MATel: 774-760-0087Fax: 774-760-0088ChicagoItasca, ILTel: 630-285-0071Fax: 630-285-0075DallasAddison, TXTel: 972-818-7423Fax: 972-818-2924DetroitNovi, MITel: 248-848-4000Houston, TXTel: 281-894-5983IndianapolisNoblesville, INTel: 317-773-8323Fax: 317-773-5453Tel: 317-536-2380Los AngelesMission Viejo, CATel: 949-462-9523Fax: 949-462-9608Tel: 951-273-7800Raleigh, NCTel: 919-844-7510New York, NYTel: 631-435-6000San Jose, CATel: 408-735-9110Tel: 408-436-4270Canada - TorontoTel: 905-695-1980Fax: 905-695-2078

Australia - SydneyTel: 61-2-9868-6733China - BeijingTel: 86-10-8569-7000China - ChengduTel: 86-28-8665-5511China - ChongqingTel: 86-23-8980-9588China - DongguanTel: 86-769-8702-9880China - GuangzhouTel: 86-20-8755-8029China - HangzhouTel: 86-571-8792-8115China - Hong Kong SARTel: 852-2943-5100China - NanjingTel: 86-25-8473-2460China - QingdaoTel: 86-532-8502-7355China - ShanghaiTel: 86-21-3326-8000China - ShenyangTel: 86-24-2334-2829China - ShenzhenTel: 86-755-8864-2200China - SuzhouTel: 86-186-6233-1526China - WuhanTel: 86-27-5980-5300China - XianTel: 86-29-8833-7252China - XiamenTel: 86-592-2388138China - ZhuhaiTel: 86-756-3210040

India - BangaloreTel: 91-80-3090-4444India - New DelhiTel: 91-11-4160-8631India - PuneTel: 91-20-4121-0141Japan - OsakaTel: 81-6-6152-7160Japan - TokyoTel: 81-3-6880- 3770Korea - DaeguTel: 82-53-744-4301Korea - SeoulTel: 82-2-554-7200Malaysia - Kuala LumpurTel: 60-3-7651-7906Malaysia - PenangTel: 60-4-227-8870Philippines - ManilaTel: 63-2-634-9065SingaporeTel: 65-6334-8870Taiwan - Hsin ChuTel: 886-3-577-8366Taiwan - KaohsiungTel: 886-7-213-7830Taiwan - TaipeiTel: 886-2-2508-8600Thailand - BangkokTel: 66-2-694-1351Vietnam - Ho Chi MinhTel: 84-28-5448-2100

Austria - WelsTel: 43-7242-2244-39Fax: 43-7242-2244-393Denmark - CopenhagenTel: 45-4450-2828Fax: 45-4485-2829Finland - EspooTel: 358-9-4520-820France - ParisTel: 33-1-69-53-63-20Fax: 33-1-69-30-90-79Germany - GarchingTel: 49-8931-9700Germany - HaanTel: 49-2129-3766400Germany - HeilbronnTel: 49-7131-67-3636Germany - KarlsruheTel: 49-721-625370Germany - MunichTel: 49-89-627-144-0Fax: 49-89-627-144-44Germany - RosenheimTel: 49-8031-354-560Israel - Ra’ananaTel: 972-9-744-7705Italy - MilanTel: 39-0331-742611Fax: 39-0331-466781Italy - PadovaTel: 39-049-7625286Netherlands - DrunenTel: 31-416-690399Fax: 31-416-690340Norway - TrondheimTel: 47-72884388Poland - WarsawTel: 48-22-3325737Romania - BucharestTel: 40-21-407-87-50Spain - MadridTel: 34-91-708-08-90Fax: 34-91-708-08-91Sweden - GothenbergTel: 46-31-704-60-40Sweden - StockholmTel: 46-8-5090-4654UK - WokinghamTel: 44-118-921-5800Fax: 44-118-921-5820

Worldwide Sales and Service


IntroductionTable of Contents1. Quick Reference Info1.1. Reference Documentation1.2. Acronyms and Abbreviations Used1.3. LoRaWAN Stack Directory Structure

2. LoRaWAN API2.1. MAC API2.1.1. LORAWAN_Init2.1.2. LORAWAN_Reset2.1.3. LORAWAN_Join2.1.4. LORAWAN_Send2.1.5. LORAWAN_SetAttr2.1.6. LORAWAN_GetAttr2.1.7. LORAWAN_Pause2.1.8. LORAWAN_Resume2.1.9. LORAWAN_ForceEnable2.1.10. LORAWAN_ReadyToSleep

2.2. TAL API2.2.1. RADIO_Init2.2.2. RADIO_Receive2.2.3. RADIO_Transmit2.2.4. RADIO_TransmitCW2.2.5. RADIO_StopCW2.2.6. RADIO_SetAttr2.2.7. RADIO_GetAttr

2.3. Stack Attributes2.3.1. Regional Configuration Parameters2.3.2. LoRaWAN/MAC Attributes2.3.3. Radio/TAL Attributes

3. Supporting MAC Layers3.1. Regional Band Layer3.2. PMM Layer3.2.1. PMM Files3.2.2. PMM APIs3.2.2.1. PMM_Sleep

3.3. PDS Layer3.3.1. PDS Files3.3.2. PDS_Init3.3.3. PDS_UnInit3.3.4. PDS_Store3.3.5. PDS_Restore3.3.6. PDS_Delete3.3.7. PDS_IsRestorable3.3.8. PDS_DeleteAll3.3.9. PDS_RestoreAll3.3.10. PDS_StoreAll3.3.11. PDS_RegFile3.3.12. PDS_UnRegFile

3.4. Software Timer Module3.4.1. Software Timer Files3.4.2. Software Timer APIs3.4.2.1. SwTimerCreate3.4.2.2. SwTimerGetTime3.4.2.3. SystemTimerInit3.4.2.4. SwTimerIsRunning3.4.2.5. SwTimerReset3.4.2.6. SwTimerStart3.4.2.7. SwTimerStop

4. HAL APIs4.1. HAL Files4.2. HAL_RadioInit4.3. HAL_RadioDeInit4.4. RADIO_Reset4.5. RADIO_RegisterWrite4.6. RADIO_RegisterRead4.7. RADIO_FrameWrite4.8. RADIO_FrameRead4.9. HAL_DisableRFCtrl4.10. HAL_EnableRFCtrl

5. Document Revision HistoryThe Microchip Web SiteCustomer Change Notification ServiceCustomer SupportMicrochip Devices Code Protection FeatureLegal NoticeTrademarksQuality Management System Certified by DNVWorldwide Sales and Service

sam r34/r35 microchip lorawan stack software api reference...

Documents