SAM4C

G3-PLC Firmware Stack

USER GUIDE

Introduction

This document is the user guide for the Atmel G3-PLC firmware stack.
The mechanisms and functionality of the G3-PLC specification is the basis of the
entire firmware stack implementation. Therefore, it is highly recommended to use
it as a reference. Basic concepts that are introduced by this G3-PLC specification
are assumed to be known within this document.

Features

Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
 Table of Contents
1 General architecture .................................................................................................... 9
1.1 PHY Layer ........................................................................................................................................... 10
1.2 Physical Abstraction Layer (PAL) ........................................................................................................ 10
1.3 MAC Layer (IEEE 802.15.4) ................................................................................................................ 11
1.4 ADP Layer (IETF RFC 4944) .............................................................................................................. 11
1.5 Serialization Layers. Universal Serial Interface (USI) .......................................................................... 13
1.6 Hardware Abstraction Layer (HAL)...................................................................................................... 13
1.7 User Application .................................................................................................................................. 13

2 Understanding the firmware package ...................................................................... 14

2.1 G3-PLC package directory structure ................................................................................................... 14

3 Brief about ASF ......................................................................................................... 16

4 Understanding the G3-PLC FW stack....................................................................... 17
4.1 Operation modes (Operating System Support) ................................................................................... 17
4.2 Following provided example as a use guide of G3-PLC stack ............................................................ 17
4.2.1 First step. Initialization ............................................................................................................ 18
4.2.2 Second step. Setting user function pointers ........................................................................... 18
4.2.3 Third step. Start program execution ....................................................................................... 18
4.3 DATA LINK processes ........................................................................................................................ 23
4.3.1 Network Discovery Request ................................................................................................... 23
4.3.2 Network Join Request............................................................................................................. 24
4.3.3 Route/Path Discovery Request ............................................................................................... 25
4.3.4 Network Leave ........................................................................................................................ 27
4.3.5 Data Request.......................................................................................................................... 28
4.3.6 ADP Reset .............................................................................................................................. 29
4.3.7 GET/SET MIBs ....................................................................................................................... 29
4.4 Configuration files................................................................................................................................ 30
4.4.1 ATPL360 Configuration - conf_atpl360.h ................................................................................ 30
4.4.2 Board Configuration - conf_board.h ........................................................................................ 30
4.4.3 Bootstrap Module configuration – conf_bs.h........................................................................... 30
4.4.4 PLC UART Buffered configuration - conf_buart_if.h ............................................................... 31
4.4.5 PLC USART Buffered configuration - conf_busart_if.h ........................................................... 31
4.4.6 ATPL360AMB LCD configuration - conf_c0216CiZ.h ............................................................. 31
4.4.7 Clock Configuration – conf_clock.h ........................................................................................ 31
4.4.8 OSS Layer configuration – conf_oss.h ................................................................................... 31
4.4.9 Platform configuration – conf_platform.h ................................................................................ 31
4.4.10 PPLC Interface configuration – conf_ pplc_if.h ....................................................................... 31
4.4.11 Project configuration – conf_project.h..................................................................................... 31
4.4.12 Serial USART Service configuration – conf_uart_serial.h....................................................... 31
4.4.13 Universal Serial Interface configuration – conf_usi.h .............................................................. 32
4.4.14 Generic FreeRTOS peripheral control functions configuration – FreeRTOSConfig.h ............. 32
4.5 Persistent Data Storage ...................................................................................................................... 32
4.6 Firmware Update process ................................................................................................................... 32

5 Operating System Support ....................................................................................... 33

5.1 Overview ............................................................................................................................................. 33
5.2 G3-PLC process. Requirements, Handling and Usage of the G3-PLC FW stack ............................... 33

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

2 Atmel
2 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
6 Toolchain ................................................................................................................... 34
6.1 General prerequisites .......................................................................................................................... 34
6.2 Building the applications ...................................................................................................................... 34
6.2.1 Using Atmel Studio ................................................................................................................. 34
6.2.2 Using IAR Embedded Workbench .......................................................................................... 34
6.2.3 Using Keil ............................................................................................................................... 34

7 Example applications ................................................................................................ 35

7.1 ADP examples..................................................................................................................................... 35
7.1.1 DLMS App .............................................................................................................................. 35
7.1.2 Gateway App .......................................................................................................................... 36
7.1.3 ADP & MAC Serialization App ................................................................................................ 36
7.1.4 Conformance App ................................................................................................................... 36
7.2 PHY examples..................................................................................................................................... 36
7.2.1 PHY Tester ............................................................................................................................. 36
7.2.2 PHY Sniffer ............................................................................................................................. 36
7.2.3 TX console.............................................................................................................................. 37

8 Supported platforms ................................................................................................. 38

8.1 Supported MCU families ..................................................................................................................... 38
8.2 Supported transceivers ....................................................................................................................... 38
8.3 Supported boards ................................................................................................................................ 38
8.4 Platform porting ................................................................................................................................... 38

9 Protocol implementation conformance statement .................................................. 39

9.1 Band-plan support ............................................................................................................................... 39
9.2 Feature implementation statement ...................................................................................................... 39
9.3 Other features ..................................................................................................................................... 39

10 Abbreviations............................................................................................................. 40
11 References ................................................................................................................. 41
12 Evaluation License Agreement ................................................................................. 42
13 Revision History ........................................................................................................ 44
Appendix A API of PHY and PAL Layers ..................................................................... 45
A.1 PHY SAP ............................................................................................................................................. 45
A.1.1 Initialization function ............................................................................................................... 45
A.1.2 Event Handler function ........................................................................................................... 45
A.1.3 Phy Data Primitives ................................................................................................................ 45
A.1.4 Configuring PHY layer parameters ......................................................................................... 50
A.1.5 Phy Management Primitives ................................................................................................... 52
A.2 PAL SAP ............................................................................................................................................. 53
A.2.1 Initialization function ............................................................................................................... 53
A.2.2 Event handler function ............................................................................................................ 53
A.3 PAL Primitives ..................................................................................................................................... 53
A.3.1 Data Primitives ....................................................................................................................... 53
A.3.2 Management Primitives .......................................................................................................... 53

Appendix B API of DATA LINK Layer .......................................................................... 55

B.1 MAC SAP ............................................................................................................................................ 55

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 3 3
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
 B.1.1 Initialization function ............................................................................................................... 55
B.1.2 Event handler function ............................................................................................................ 55
B.2 MAC Primitives .................................................................................................................................... 55
B.2.1 Mac Data Primitives ................................................................................................................ 55
B.2.2 Mac Management Primitives .................................................................................................. 56
B.3 MIB Objects Specification and Access ................................................................................................ 56
B.3.1 MAC_PIB _ACK_WAIT_DURATION (0x00000040) ............................................................... 56
B.3.2 MAC_PIB_BSN (0x00000049) ............................................................................................... 56
B.3.3 MAC_PIB_DSN (0x0000004C) ............................................................................................... 56
B.3.4 MAC_PIB_MAX_BE (0x00000047) ........................................................................................ 57
B.3.5 MAC_PIB_MAX_CSMA_BACKOFFS (0x0000004E) ............................................................. 57
B.3.6 MAC_PIB_MAX_FRAME_RETRIES (0x00000059) ............................................................... 57
B.3.7 MAC_PIB_MIN_BE (0x0000004F) ......................................................................................... 57
B.3.8 MAC_PIB_PAN_ID (0x00000050) .......................................................................................... 57
B.3.9 MAC_PIB_SECURITY_ENABLED (0x0000005D) ................................................................. 57
B.3.10 MAC_PIB_SHORT_ADDRESS (0x00000053) ....................................................................... 57
B.3.11 MAC_PIB_PROMISCUOUS_MODE (0x00000051) ............................................................... 58
B.3.12 MAC_PIB_TIMESTAMP_SUPPORTED (0x0000005C) ......................................................... 58
B.3.13 MAC_PIB_KEY_TABLE (0x00000071) .................................................................................. 58
B.3.14 MAC_PIB_FRAME_COUNTER (0x00000077) ....................................................................... 58
B.3.15 MAC_PIB_HIGH_PRIORITY_WINDOW_SIZE (0x00000100) ............................................... 59
B.3.16 MAC_PIB_TX_DATA_PACKET_COUNT (0x00000101) ........................................................ 59
B.3.17 MAC_PIB_RX_DATA_PACKET_COUNT (0x00000102) ....................................................... 59
B.3.18 MAC_PIB_TX_CMD_PACKET_COUNT (0x00000103) ......................................................... 59
B.3.19 MAC_PIB_RX_CMD_PACKET_COUNT (0x00000104) ......................................................... 59
B.3.20 MAC_PIB_CSMA_FAIL_COUNT (0x00000105) .................................................................... 59
B.3.21 MAC_PIB_CSMA_NO_ACK_COUNT (0x00000106) ............................................................. 59
B.3.22 MAC_PIB_RX_DATA_BROADCAST_COUNT (0x00000107) ............................................... 60
B.3.23 MAC_PIB_TX_DATA_BROADCAST_COUNT (0x00000108) ................................................ 60
B.3.24 MAC_PIB_BAD_CRC_COUNT (0x00000109) ....................................................................... 60
B.3.25 MAC_PIB_NEIGHBOUR_TABLE (0x0000010A) ................................................................... 60
B.3.26 MAC_PIB_FREQ_NOTCHING (0x0000010B) ....................................................................... 61
B.3.27 MAC_PIB_CSMA_FAIRNESS_LIMIT (0x0000010C) ............................................................. 61
B.3.28 MAC_PIB_TMR_TTL (0x0000010D) ...................................................................................... 61
B.3.29 MAC_PIB_NEIGHBOUR_TABLE_ENTRY_TTL (0x0000010E) ............................................. 61
B.3.30 MAC_PIB_RC_COORD (0x0000010F) .................................................................................. 61
B.3.31 MAC_PIB_TONE_MASK (0x00000110) ................................................................................. 62
B.3.32 MAC_PIB_BEACON_RANDOMIZATION_WINDOW_LENGTH (0x00000111) ...................... 62
B.3.33 MAC_PIB_A (0x00000112) .................................................................................................... 62
B.3.34 MAC_PIB_K (0x00000113) .................................................................................................... 62
B.3.35 MAC_PIB_MIN_CW_ATTEMPTS (0x00000114) ................................................................... 62
B.3.36 MAC_PIB_CENELEC_LEGACY_MODE (0x00000115) ......................................................... 62
B.3.37 MAC_PIB_FCC_LEGACY_MODE (0x00000116) .................................................................. 63
B.3.38 MAC_PIB_MANUF_DEVICE_TABLE (0x80000000).............................................................. 63
B.3.39 MAC_PIB_MANUF_EXTENDED_ADDRESS (0x80000001) ................................................. 63
B.3.40 MAC_PIB_MANUF_NEIGHBOUR_TABLE_ELEMENT (0x80000002) .................................. 63
B.3.41 MAC_PIB_MANUF_BAND_INFORMATION (0x80000003) ................................................... 63
B.3.42 MAC_PIB_MANUF_COORD_SHORT_ADDRESS (0x08000004) ......................................... 64
B.3.43 MAC_PIB_MANUF_MAX_MAC_PAYLOAD_SIZE (0x08000005) .......................................... 64
B.3.44 MAC_PIB_MANUF_SECURITY_RESET (0x08000006) ........................................................ 64
B.3.45 MAC_PIB_MANUF_FORCED_MOD_SCHEME (0x08000007) ............................................. 65

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

4 Atmel
4 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
 B.3.46 MAC_PIB_MANUF_FORCED_MOD_TYPE (0x08000008) ................................................... 65
B.3.47 MAC_PIB_MANUF_FORCED_TONEMAP (0x08000009) ..................................................... 65
B.3.48 MAC_PIB_MANUF_FORCED_MOD_SCHEME_ON_TMRESPONSE (0x0800000A) ........... 65
B.3.49 MAC_PIB_MANUF_FORCED_MOD_TYPE_ON_TMRESPONSE (0x0800000B) ................. 66
B.3.50 MAC_PIB_MANUF_FORCED_TONEMAP_ON_TMRESPONSE (0x0800000C) .................. 66
B.3.51 MAC_PIB_MANUF_LAST_RX_MOD_SCHEME (0x0800000D) ............................................ 66
B.3.52 MAC_PIB_MANUF_LAST_RX_MOD_TYPE (0x0800000E) .................................................. 66
B.3.53 MAC_PIB_MANUF_LBP_FRAME_RECEIVED (0x0800000F) .............................................. 67
B.3.54 MAC_PIB_MANUF_LNG_FRAME_RECEIVED (0x08000010) .............................................. 67
B.3.55 MAC_PIB_MANUF_BCN_FRAME_RECEIVED (0x08000011) .............................................. 67
B.3.56 MAC_PIB_MANUF_NEIGHBOUR_TABLE_COUNT (0x08000012) ...................................... 67
B.3.57 MAC_PIB_MANUF_PHY_PARAM (0x08000020) .................................................................. 67
B.4 ADP SAP ............................................................................................................................................. 72
B.4.1 Initialization function ............................................................................................................... 72
B.4.2 Event handler function ............................................................................................................ 73
B.5 ADP Data Primitives ............................................................................................................................ 73
B.5.1 ADPD-DATA.request .............................................................................................................. 73
B.5.2 ADPD-DATA.confirm .............................................................................................................. 74
B.5.3 ADPD-DATA.indication ........................................................................................................... 74
B.6 ADP Management Service Primitives .................................................................................................. 74
B.6.1 ADPM-DISCOVERY.request .................................................................................................. 75
B.6.2 ADPM-DISCOVERY.indication ............................................................................................... 75
B.6.3 ADPM-DISCOVERY.confirm .................................................................................................. 75
B.6.4 ADPM-NETWORK-START.request ........................................................................................ 76
B.6.5 ADPM-NETWORK-START.confirm ........................................................................................ 76
B.6.6 ADPM-NETWORK-JOIN.request ........................................................................................... 76
B.6.7 ADPM-NETWORK-JOIN.confirm ............................................................................................ 76
B.6.8 ADPM-NETWORK-JOIN.indication ........................................................................................ 77
B.6.9 ADPM-NETWORK-LEAVE.request ........................................................................................ 77
B.6.10 ADPM-NETWORK-LEAVE.indication ..................................................................................... 77
B.6.11 ADPM-NETWORK-LEAVE.confirm ........................................................................................ 77
B.6.12 ADPM-RESET.request ........................................................................................................... 77
B.6.13 ADPM-RESET.confirm ........................................................................................................... 78
B.6.14 ADPM-GET.request ................................................................................................................ 78
B.6.15 ADPM-GET.confirm ................................................................................................................ 78
B.6.16 ADPM-MAC.GET.request ....................................................................................................... 79
B.6.17 ADPM-MAC.GET.confirm ....................................................................................................... 80
B.6.18 ADPM-SET.request ................................................................................................................ 81
B.6.19 ADPM-SET.confirm ................................................................................................................ 81
B.6.20 ADPM-MAC.SET.request ....................................................................................................... 82
B.6.21 ADPM-MAC.SET.confirm ....................................................................................................... 83
B.6.22 ADPM-NETWORK-STATUS.indication .................................................................................. 83
B.6.23 ADPM-BUFFER.indication...................................................................................................... 84
B.6.24 ADPM-PREQ.indication .......................................................................................................... 84
B.6.25 ADPM-UPD_NON_VOLATILE_DATA.indication .................................................................... 84
B.6.26 ADPM-BROKEN_ROUTE.indication ...................................................................................... 84
B.6.27 ADPM-ROUTE-DISCOVERY.request .................................................................................... 85
B.6.28 ADPM-ROUTE-DISCOVERY.confirm..................................................................................... 85
B.6.29 ADPM-PATH-DISCOVERY.request ....................................................................................... 86
B.6.30 ADPM-PATH-DISCOVERY.confirm ....................................................................................... 86
B.6.31 ADPM-LBP.request ................................................................................................................ 87

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 5 5
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
 B.6.32 ADPM-LBP.confirm................................................................................................................. 87
B.6.33 ADPM-LBP.indication ............................................................................................................. 88
B.7 ADPIB Objects Specification and Access............................................................................................ 88
B.7.1 ADP_IB_SECURITY_LEVEL = 0x00000000 .......................................................................... 89
B.7.2 ADP_IB_PREFIX_TABLE = 0x00000001 ............................................................................... 89
B.7.3 ADP_IB_BROADCAST_LOG_TABLE_ENTRY_TTL = 0x00000002 ...................................... 89
B.7.4 ADP_IB_METRIC_TYPE = 0x00000003 ................................................................................ 89
B.7.5 ADP_IB_LOW_LQI_VALUE = 0x00000004 ........................................................................... 89
B.7.6 ADP_IB_HIGH_LQI_VALUE = 0x00000005 ........................................................................... 89
B.7.7 ADP_IB_RREP_WAIT = 0x00000006 .................................................................................... 89
B.7.8 ADP_IB_CONTEXT_INFORMATION_TABLE = 0x00000007 ................................................ 90
B.7.9 ADP_IB_COORD_SHORT_ADDRESS = 0x00000008 .......................................................... 90
B.7.10 ADP_IB_RLC_ENABLED = 0x00000009 ............................................................................... 90
B.7.11 ADP_IB_ADD_REV_LINK_COST = 0x0000000A .................................................................. 90
B.7.12 ADP_IB_BROADCAST_LOG_TABLE = 0x0000000B ............................................................ 90
B.7.13 ADP_IB_ROUTING_TABLE = 0x0000000C ........................................................................... 90
B.7.14 ADP_IB_UNICAST_RREQ_GEN_ENABLE = 0x0000000D ................................................... 91
B.7.15 ADP_IB_GROUP_TABLE = 0x0000000E .............................................................................. 91
B.7.16 ADP_IB_MAX_HOPS = 0x0000000F ..................................................................................... 91
B.7.17 ADP_IB_DEVICE_TYPE= 0x00000010 ................................................................................. 91
B.7.18 ADP_IB_NET_TRAVERSAL_TIME = 0x00000011 ................................................................ 91
B.7.19 ADP_IB_ROUTING_TABLE_ENTRY_TTL = 0x00000012 ..................................................... 91
B.7.20 ADP_IB_KR = 0x00000013 .................................................................................................... 91
B.7.21 ADP_IB_KM = 0x00000014 .................................................................................................... 91
B.7.22 ADP_IB_KC = 0x00000015 .................................................................................................... 91
B.7.23 ADP_IB_KQ = 0x00000016 .................................................................................................... 91
B.7.24 ADP_IB_KH = 0x00000017 .................................................................................................... 92
B.7.25 ADP_IB_RREQ_RETRIES = 0x00000018 ............................................................................. 92
B.7.26 ADP_IB_RREQ_RERR_WAIT = 0x00000019 ........................................................................ 92
B.7.27 ADP_IB_WEAK_LQI_VALUE = 0x0000001A ......................................................................... 92
B.7.28 ADP_IB_KRT = 0x0000001B.................................................................................................. 92
B.7.29 ADP_IB_SOFT_VERSION = 0x0000001C ............................................................................. 92
B.7.30 ADP_IB_SNIFFER_MODE = 0x0000001D ............................................................................ 92
B.7.31 ADP_IB_BLACKLIST_TABLE = 0x0000001E ........................................................................ 92
B.7.32 ADP_IB_BLACKLIST_TABLE_ENTRY_TTL = 0x0000001F .................................................. 92
B.7.33 ADP_IB_MAX_JOIN_WAIT_TIME = 0x00000020 .................................................................. 93
B.7.34 ADP_IB_PATH_DISCOVERY_TIME = 0x00000021 .............................................................. 93
B.7.35 ADP_IB_ACTIVE_KEY_INDEX = 0x00000022 ...................................................................... 93
B.7.36 ADP_IB_DISABLE_DEFAULT_ROUTING = 0x000000F0 ..................................................... 93
B.7.37 ADP_IB_MANUF_REASSEMBY_TIMER = 0x800000C0 ...................................................... 93
B.7.38 ADP_IB_MANUF_IPV6_HEADER_COMPRESSION = 0x800000C1 .................................... 93
B.7.39 ADP_IB_MANUF_EAP_PRESHARED_KEY = 0x800000C2 ................................................. 93
B.7.40 ADP_IB_MANUF_EAP_NETWORK_ACCESS_IDENTIFIER = 0x800000C3 ........................ 93
B.7.41 ADP_IB_MANUF_BROADCAST_SEQUENCE_NUMBER = 0x800000C4 ............................ 93
B.7.42 ADP_IB_MANUF_REGISTER_DEVICE = 0x800000C5 ........................................................ 93
B.7.43 ADP_IB_MANUF_DATAGRAM_TAG = 0x800000C6 ............................................................ 94
B.7.44 ADP_IB_MANUF_RANDP = 0x800000C7 ............................................................................. 94
B.7.45 ADP_IB_MANUF_ROUTING_TABLE_COUNT = 0x800000C8 ............................................. 94
B.7.46 ADP_IB_MANUF_DISCOVER_SEQUENCE_NUMBER = 0x800000C9 ................................ 94
B.7.47 ADP_IB_MANUF_FORCED_NO_ACK_REQUEST = 0x800000CA ...................................... 94
B.7.48 ADP_IB_MANUF_LQI_TO_COORD = 0x800000CB ............................................................. 94

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

6 Atmel
6 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
 B.7.49 ADP_IB_MANUF_BROADCAST_ROUTE_ALL = 0x800000CC ............................................ 94
B.7.50 ADP_IB_MANUF_KEEP_PARAMS_AFTER_KICK_LEAVE = 0x800000CD ......................... 94
B.7.51 ADP_IB_MANUF_ADP_MAC_INTERNAL_VERSION = 0x800000CE .................................. 95
B.7.52 ADP_IB_MANUF_CIRCULAR_ROUTES_DETECTED = 0x800000CF ................................. 95
B.7.53 ADP_IB_MANUF_LAST_CIRCULAR_ROUTE_ADDRESS = 0x800000D0 ........................... 95
B.7.54 ADP_IB_MANUF_IPV6_ULA_DEST_SHORT_ADDRESS = 0x800000D1 ............................ 95
B.7.55 ADP_IB_MANUF_MAX_REPAIR_RESEND_ATTEMPTS = 0x800000D2 ............................. 95
B.7.56 ADP_IB_MANUF_TRIGGER_REPAIR_ON_ROUTE_BROKEN = 0x800000D3 ................... 95
B.8 ADP Status codes description ............................................................................................................. 95
B.8.1 G3_SUCCESS (0x00) ............................................................................................................ 95
B.8.2 G3_INVALID_REQUEST (0xA1) ............................................................................................ 96
B.8.3 G3_FAILED (0xA2) ................................................................................................................. 96
B.8.4 G3_INVALID_IPV6_FRAME (0xA3) ....................................................................................... 96
B.8.5 G3_NOT_PERMITED (0xA4) ................................................................................................. 96
B.8.6 G3_ROUTE_ERROR (0xA5) .................................................................................................. 96
B.8.7 G3_TIMEOUT (0xA6) ............................................................................................................. 97
B.8.8 G3_INVALID_INDEX (0xA7) .................................................................................................. 97
B.8.9 G3_INVALID_PARAMETER (0xA8) ....................................................................................... 97
B.8.10 G3_NO_BEACON (0xA9) ....................................................................................................... 97
B.8.11 G3_READ_ONLY (0xB0) ........................................................................................................ 97
B.8.12 G3_UNSUPPORTED_ATTRIBUTE (0xB1) ............................................................................ 97
B.8.13 G3_INCOMPLETE_PATH (0xB2) .......................................................................................... 97
B.8.14 G3_BUSY (0xB3) ................................................................................................................... 97
B.8.15 G3_NO_BUFFERS (0xB4) ..................................................................................................... 98
B.8.16 G3_ERROR_INTERNAL (0xFF) ............................................................................................. 98
B.8.17 MAC layer status codes .......................................................................................................... 98

Appendix C LBP module .............................................................................................. 99

C.1 Functional description ......................................................................................................................... 99
C.2 API listing ............................................................................................................................................ 99
C.2.1 Bootstrap module initialization ................................................................................................ 99
C.2.2 Re-keying ............................................................................................................................... 99
C.2.3 Joined devices table access ................................................................................................... 99
C.2.4 Kick ....................................................................................................................................... 100
C.2.5 PIB access............................................................................................................................ 100
C.2.6 Callback integration with upper and lower layers .................................................................. 101
C.3 LBP Objects Specification and Access.............................................................................................. 102
C.3.1 LBP_IB_IDS = 0x00000000 .................................................................................................. 102
C.3.2 LBP_IB_DEVICE_LIST = 0x00000001 ................................................................................. 102
C.3.3 LBP_IB_INITIAL_SHORT_ADDRESS = 0x00000002 .......................................................... 102
C.3.4 LBP_IB_ADD_DEVICE_TO_BLACKLIST = 0x00000003 ..................................................... 102
C.3.5 LBP_IB_PSK = 0x00000004 ................................................................................................ 102
C.3.6 LBP_IB_GMK = 0x00000005................................................................................................ 102
C.3.7 LBP_IB_REKEY_GMK = 0x00000006 ................................................................................. 103
C.4 Brief of provided LBP Module example ............................................................................................. 103
C.4.1 Initialization function ............................................................................................................. 103
C.4.2 LBD Device list ..................................................................................................................... 103
C.4.3 LBD Blacklist ........................................................................................................................ 103
C.4.4 Processing of LBP frames .................................................................................................... 103
C.4.5 Rekeying............................................................................................................................... 104

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 7 7
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
Table of figures

FIGURE 1-1. BLOCK DIAGRAM OF ATMEL G3-PLC STACK (ATPL250A) ................................................................................. 9

FIGURE 1-2. BLOCK DIAGRAM OF ATMEL G3-PLC STACK (SAM4CP16C) ............................................................................. 9
FIGURE 4-1. NETWORK DISCOVERY REQUEST FLOW CHART. ............................................................................................... 23
FIGURE 4-2. NETWORK JOIN REQUEST FLOW CHART. .......................................................................................................... 24
FIGURE 4-3. ROUTE DISCOVERY REQUEST FLOW CHART. .................................................................................................... 25
FIGURE 4-4. PATH DISCOVERY REQUEST FLOW CHART. ...................................................................................................... 26
FIGURE 4-5. NETWORK LEAVE FLOW CHART. ...................................................................................................................... 27
FIGURE 4-6. ADP DATA REQUEST FLOW CHART. ................................................................................................................ 28
FIGURE 4-7. ADP DATA REQUEST FLOW CHART. RETRANSMISSION DUE TO ACK FAIL. ......................................................... 28
FIGURE 4-8. ADP RESET FLOW CHART. .............................................................................................................................. 29
FIGURE 4-9. ADP GET REQUEST AND ADP SET REQUEST FLOW CHARTS. ......................................................................... 29
FIGURE 4-10.ADPMAC GET REQUEST AND ADPMAC SET REQUEST FLOW CHARTS. ......................................................... 30

FIGURE A-1. ZC_DELAY CALCULATION ............................................................................................................................... 51

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

8 Atmel
8 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
1 General architecture
The Atmel G3-PLC Firmware Stack follows a layered approach based on the G3-PLC specification. The Figure
1-1 shows the stack’s architecture:

Figure 1-1. Block Diagram of Atmel G3-PLC Stack (ATPL250A / ATPL360A)

app_if
USER APPLICATION

G3-PLC Stack

Embedded USI
Adaptation adp_if
SAM4C

Layer
HAL

(IETF RFC 4944)

MAC mac_if
Layer (IEEE 802.15.4)
PAL
Layer (ITU-T G.9903)
phy_if
PHY Layer sniffer_if

SPI

G3-PLC Transceiver
ATPL250A
ATPL360A
PLC

Figure 1-2. Block Diagram of Atmel G3-PLC Stack (SAM4CP16C)

app_if
USER APPLICATION

G3-PLC Stack
Embedded USI
SAM4CP16C

Adaptation adp_if
Layer (IETF RFC 4944)
HAL

MAC mac_if
Layer (IEEE 802.15.4)
PAL
Layer (ITU-T G.9903)
phy_if
PHY Layer sniffer_if

GPLC

PLC

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 9 9
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
1.1 PHY Layer
PHY layer is in charge of frame transmission and reception, this layer is mainly interrupt driven with events
coming from PLC modem.
Interrupt events occur while transmitting and receiving frames using PLC modem. There are 2 special events
which are a frame reception and the end of a frame transmission. These particular events cause callback
functions to be called on the upper layer (PHY Abstraction Layer) to capture such messages.
Apart from these events, PHY layer implements entry functions in order to transmit a frame using the PLC
modem, to perform periodic tasks, and to access the PHY Information Base (PIB) to read, write, or modify
parameters.
In case of ATPL360A architecture, Phy layer firmware is managed by ATPL360A device, to do so, a binary file
is downloaded to ATPL360 from the flash memory of the external microcontroller. Next figure depicts the memory
allocation configured in the provided Microchip applications project examples. As it can be seen, there is a region
reserved for the ATPL360A binary file. File location can be configured by upper layer. For further details, please
refer to ATPL360 Controller document provided by Microchip.

1.2 Physical Abstraction Layer (PAL)

This layer abstracts the interface of the PHY Layer developed by Atmel and provides an interface compliant with
the G3-PLC PHY Layer. For more details please refer to G3 PLC Spec [G3-PLC Alliance: http://www.g3-
plc.com/]. In other words, this layer is the one which acts as the interface between the currently developed PHY
and MAC layers, and is in charge of communicating both layers properly.
It implements primitives to inform the MAC layer of events coming from PLC, namely PhyDataConfirm,
PhyAckConfirm, PhyDataIndication and PhyAckIndication.
Apart from these tasks, PHY API will directly address function calls from MAC to transmit a frame,
PhyDataRequest and PhyAckRequest to PHY layer. The same will occur with MAC calls to PLME functions
(PhyPlmeSetRequest, PhyPlmeSetConfirm, PhyPlmeGetRequest, PhyPlmeGetConfirm,
PhyPlmeSetTrxStateRequest, PhyPlmeSetTrxStateConfirm, PhyPlmeCsRequest, PhyPlmeCsConfirm,
PhyPlmeResetRequest) which will be directly addressed to PHY functions related to PIB access.
Please note that the semantics of the PHY primitives included in this firmware stack cover the requirements of
the G3-PLC PHY specs and provide more information:

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

10 Atmel
1 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
  PhyInitialize has to be called to initialize PHY layer.
 PhyEventHandler has to be called to perform periodic tasks.
 PhyGetTime retrieves the value of the internal PHY timer used to control Rx and Tx times.
 PhyGetToneMapResponseData is used to retrieve information from PHY layer in order to fill a Tone Map
Response frame.
 PhySetToneMask can be used to change the Tone Mask used by Phy layer.
 PhyGetLegacyMode can be used to the PHY layer is running in legacy mode or not.
 PhyGetParam and PhySetParam are used to access PIB objects not present in the standard
PhyPlmeGetRequest and PhyPlmeSetRequest functions.
For further details, please refer to pal.h header file.

1.3 MAC Layer (IEEE 802.15.4)

The MAC Sublayer has the following functions:
 Channel access with CSMA-CA.
 High and normal priority.
 Segmentation of big packets.
 Segment acknowledgement and retransmission of lost segments.
 Network scan.
 Transmission robustness management.
The MAC layer requires that function MacEventHandler is called periodically, in order to allow the stack to work.
On the Atmel G3 implementation, MacEventHandler will be called by AdpEventHandler (see section 1.4), so end
user does not have to worry about this. In turn, it will call PhyEventHandler, to run periodic tasks of PHY layer.
The MAC layer uses the request/notification technique to communicate with ADP and PAL layers. Every request
has at least one corresponding notification. The notifications are implemented as callback functions. The user
(in Atmel implementation the user is the ADP layer) initializes the callback functions pointers while is initializing
the MAC layer. There are a few restrictions the user should be aware about:
1. The user should avoid blocking the MAC layer in the callbacks as they are running in the same thread
as the full stack
2. As soon as a callback returns the data is no longer available so the user should not store pointers to this
data for later processing
The MAC sublayer interface is defined in the following files:
 MacApi.h. This file contains the functions and callbacks definitions of the MAC sublayer.
 MacMib.h. This file defines the data types and functions used to access the MAC PIB.
 MacDefs.h. This file defines some basic MAC data types and constants.

1.4 ADP Layer (IETF RFC 4944)

The Adaptation Sublayer (ADP) has the following functions:
 Handles the device authentication and encryption key distribution
 IPv6 headers compression / decompression
 Fragmentation / reassembly of the IPv6 packets
 Controlling broadcast / multicast propagation
 Routing a message into the network

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 11 1
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
1
  Discovery and maintenance of the routes into the network
The ADP layer requires that function AdpEventHandler is called periodically, in order to allow the stack to work.
The end user application has to take care of this periodic call. The AdpEventHandler will in turn call
MacEventHandler which will propagate this call to lower layers.
The ADP layer uses the request/notification technique. Every request has at least one corresponding notification.
The notifications are implemented as callback functions. The end user has to initialize the callback functions
pointers while is initializing the ADP layer. There are a few restrictions the user should be aware about:
 The user application should not tamper the data transmitted by the ADP layer as callback parameters
 The user should avoid blocking the ADP layer in the callbacks as they are running in the same thread
as the full stack
 As soon as a callback returns the data is no longer available so the user should not rely on pointers to
this data for later processing
The user should not call directly any MAC primitive when the ADP layer is initialized. The ADP provides specific
functions for accessing the MAC MIB.
The ADP sublayer interface is defined in the following files:
 AdpApi.h. This files contains the functions and callbacks definitions of the ADP sublayer
 AdpApiTypes.h. This file defines the data types used by the functions and callbacks

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

12 Atmel
1 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
2
1.5 Serialization Layers. Universal Serial Interface (USI)
Serialization is available on PHY layer.
Serialization of PHY layer will act as the PHY API layer, but communicating with a Serial Port Service, instead
of the PAL. Thus will have the corresponding callback functions, to handle events coming from PHY layer, and
will have direct calls to frame transmission, and to read, write and modify parameters on PIB.
It is used in order to build applications over PHY layer which communicate with the PC tools provided by Atmel.

1.6 Hardware Abstraction Layer (HAL)

Apart from the G3-PLC stack, Atmel provides an open code of the Hardware Abstraction Layer (HAL).
This abstraction layer code can be found under Platform folder.

Note that the provided Platform source code is only an implementation example. Users should modify the code
according to their hardware and specifications.

There are different groups of functions, e.g. to initialize HW, write parameters in flash, power down detection,
timer interrupt management, etc.

1.7 User Application

Layers on top of ADP Layer are not directly related to G3 protocol, and so, not included in this G3-PLC FW Stack.
Users have to build their applications using the interface provided by ADP API (which is the one described in G3
Specification), where they can find functions to initialize stack, set callbacks, send data packets, start
management processes and access ADP and MAC information base.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 13 1
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
3
2 Understanding the firmware package
The following chapter describes the content of the Atmel G3-PLC firmware package, common asf modules and
drivers which are required for this G3-PLC firmware to work and explains some general guidelines how the
various software layers are structured.

2.1 G3-PLC package directory structure

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

14 Atmel
1 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
4
Workspace package is divided in 3 folders, common, sam and thirdparty. Common and sam contain generic
drivers and components for Atmel microcontrollers.
Thirdparty folder contains CMSIS folder, where ARM Cortex interface is located, dlms, where a lite version of a
dlms client and a dlms server are provided, freertos folder, where the porting of freertos to Atmel microcontrollers
can be found, and g3 folder, where all the G3 stack and example applications code is located.
Under g3 folder, there is basically one folder for each layer of the G3 stack, plus IPv6, plus applications (apart
from some auxiliary folders).
Two different apps folders can be found, one under phy/atpl250, where PHY example applications are located,
and one directly under the g3 folder, where example applications involving the whole stack can be found, apart
from the generic workspaces which contain all the previously mentioned projects.
Any of these apps folders contain the projects for the supported compiles, so user can open, inspect, and compile
them.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 15 1
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
5
3 Brief about ASF
The Atmel Software Framework (ASF) is a MCU software library providing a large collection of embedded
software for Atmel flash MCUs: megaAVR, AVR XMEGA, AVR UC3 and SAM devices.
For details on ASF please refer to Atmel Software Framework documentation:
 Atmel Software Framework - Website
 [PDF] Atmel AVR4029: Atmel Software Framework - Getting Started
 [PDF] Atmel AVR4030: Atmel Software Framework - Reference Manual

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

16 Atmel
1 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
6
4 Understanding the G3-PLC FW stack
The following chapter explains how the G3-PLC FW stack have to be used. This firmware stack has been
intended to harbor the application code developed by the user. So the user can integrate his application code in
the firmware package delivered by Atmel.
The basic procedure for performing this integration is:
 Configuring RTOS option:
– microcontroller mode
– RTOS (FreeRTOS)
 Initializing FW stack
 Developing user application requirements
 Modify the configuration files according to user needs

4.1 Operation modes (Operating System Support)

The user can choose between two different operation modes:
 Microcontroller operation mode
 RTOS operation mode
The operation mode is defined in conf_oss.h file under the following define sentence:

/* OS Support */
#define OSS_USE_FREERTOS

For configuring the FW stack to operate in RTOS mode please define OSS_USE_FREERTOS.
If OSS_USE_FREERTOS is not defined then the FW is executed in microcontroller operation
mode. (See chapter 4.4.8 OSS Layer configuration – conf_oss.h)

Please note that the default RTOS included in the stack is FreeRTOS.
Also note that the RTOS mode is provided as an example of integration of the stack inside an
OS with demonstration purposes only. It should not be taken as the starting point of a
development, and Atmel does not ensure the same performance and stability as the examples
running in microcontroller mode.

This compilation constant changes the way code is executed in file oss_if.c, which is the file in charge of
controlling the program flow. This file contains all the calls to initialization functions, calls to time control functions
and calls to periodic task handler functions. All this is done in a different way depending on the operation mode,
but the idea of controlling the program flow from this file is the same.

Regardless of the approach, user has to ensure that the G3 periodic task is called every 1ms
with the highest priority, no other user task should interrupt the G3 task execution. This
ensures that time restrictions defined by G3 spec are met.

4.2 Following provided example as a use guide of G3-PLC stack

To understand how the G3 PLC stack should be used, let’s follow one of the provided examples. We will use
DLMS_EMU_COORD_APP for this purpose.
The program entry point function is quite simple:

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 17 1
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
7
 void main(void)
{
/* Initialize OSS */
oss_init();

/* Configure OSS_IF */
oss_set_app_init(short_cycle_base_init);
oss_set_app_process(process_cycles_app);
oss_set_1ms_timer_cb(update_cycles_timer);

/* Start OSS */
oss_start();
}
Three clear tasks can be seen here:
 Initialization.
 Set User App function pointers.
 Start execution.
Let’s take a closer look at these 3 steps.

4.2.1 First step. Initialization

void oss_init(void)
{
/* Prepare the hardware */
platform_init_hw();
}
First of all, the stack initializes the hardware platform according to its needs.
In case user wants to use hardware different to that provided by Atmel, platform files may have to be changed
according to user needs. All these files are available as source code for this purpose. In case Atmel evaluation
boards are used, hardware will be correctly initialized and user does not need to take care of this.

4.2.2 Second step. Setting user function pointers

OSS file is in charge of controlling all program flow, as seen in section 4.1 Operation modes (Operating System
Support).
For this file to be able to call user application functions, some function pointers have to be set:
One for user application initialization function, using function oss_set_app_init.
One for user application periodic event handler, using function oss_set_app_process. The rate at which this
event handler will be called can be configured through the compilation constant OSS_APP_EXEC_RATE, which
can be found in oss_if.h file. Default value for this rate is every 1 millisecond.
One for user application time control, which will be called every 1 millisecond, using function
oss_set_1ms_timer_cb. Important Note, this function will be called inside a timer interrupt context, so user has
to avoid long processing time on it, this is intended for simple time control tasks such as incrementing a
millisecond counter variable.

4.2.3 Third step. Start program execution

This is the implementation of oss_start function in microcontroller mode, this mode will be used to explain the
different functions and processes involved in program execution. OS mode can be easily followed in the provided
code and it will not be explained here, as functionality is exactly the same but performing tasks in an RTOS way.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

18 Atmel
1 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
8
void oss_start(void)
{
/* Set up timer interrupt and user defined callback */
platform_set_ms_callback(&_oss_1ms_timer_handler);
platform_init_1ms_timer();
platform_led_cfg_blink_rate(OSS_LED_BLINK_RATE);
platform_cfg_call_process_rate(OSS_APP_EXEC_RATE);

#ifdef PLATFORM_ENABLE_POWER_DOWN_DETECTION /* Power down detection

initialization */
platform_init_power_down_det();
#endif /* #ifdef PLATFORM_ENABLE_POWER_DOWN_DETECTION */

/* Initialize eui64 */
platform_init_eui64(CONF_EXTENDED_ADDRESS);

#ifdef OSS_ENABLE_IPv6_STACK_SUPPORT
/* Initialize IPv6 stack */
netInit();
#endif

/* User-defined initialization */
if(pf_app_init_cb != NULL) {
pf_app_init_cb();
}

#if (NUM_PORTS != 0)
usi_init();
#endif

/* main loop */
while (1) {
/* Reset watchdog */
RESET_WATCHDOG

if (platform_flag_call_process()) {
/* User-defined initialization */
if(pf_app_process_cb != NULL) {
pf_app_process_cb();
}

#if (NUM_PORTS != 0)
usi_process();
#endif

/* G3 stack process */
#ifdef OSS_G3_ADP_MAC_SUPPORT
AdpEventHandler(); /* Internally calls MAC and
PHY Event handlers */
#endif

/* Handle TCP/IP events */

#ifdef OSS_ENABLE_IPv6_STACK_SUPPORT
netTask();
#endif

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 19 1
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
9
 }

/* LED blink */
platform_led_update();
}
}
This function perform some interesting tasks which will be explained in the next subsections.
4.2.3.1 Time Control initialization
/* Set up timer interrupt and user defined callback */
platform_set_ms_callback(&_oss_1ms_timer_handler);
platform_init_1ms_timer();
platform_led_cfg_blink_rate(OSS_LED_BLINK_RATE);
platform_cfg_call_process_rate(OSS_APP_EXEC_RATE);
First of all, mechanisms for time control are initialized. A callback function defined in oss_if.c file is configured to
be called every time that a HW interrupt raises (this HW interrupt is defined and handled in platform.c file), using
function platform_set_ms_callback. Then the HW interrupt itself is configured and enabled using function
platform_init_1ms_timer.
This way, we have a function in OSS that is called every 1ms, independently of the platform below (platform
functions have to be correctly implemented to ensure this). Such function will be in charge of managing the time
base for the G3 stack.
Next function, platform_led_cfg_blink_rate, configures the rate at which an activity led blinks in the board
periodically, just to indicate that program is running, the rate is defined by the constant OSS_LED_BLINK_RATE,
located in file conf_oss.h, and its value is indicated in milliseconds. This is an auxiliary function which does not
affect at all to G3 stack functionality.
Finally, function platform_cfg_call_process_rate is used to define the rate at which the user application and G3
stack event handlers are called. It is defined using the constant OSS_APP_EXEC_RATE located in file oss_if.h.
The reason this constant is not located in a configuration file is that this rate should not be changed by the user.
User can check the value of this constant in order to know the rate at which the periodic function defined to be
called in application (as seen in section 4.2.2 Second step. Setting user function pointers) will be called, but the
value should remain unchanged.
4.2.3.2 Power down detection
#ifdef PLATFORM_ENABLE_POWER_DOWN_DETECTION /* Power down detection
initialization */
platform_init_power_down_det();
#endif
G3 stack needs that some information is stored in non-volatile memory so it can be restored after a power down.
In order to do so, the stack keeps that information updated in a dedicated structure, but needs to know when it
is necessary to save it to non-volatile memory. For this purpose, a power down detection mechanism is
implemented in platform files. I user wants to use this power down detector, constant
PLATFORM_ENABLE_POWER_DOWN_DETECTION has to be defined, it is located in conf_platform.h file.
When this is defined, all needed hardware is initialized using function platform_init_power_down_det.
As everything in platform files, provided implementation is valid when using Atmel development boards. In case
user develops its own board, this implementation may have to be changed.
4.2.3.3 EUI64 initialization
/* Initialize eui64 */
platform_init_eui64(CONF_EXTENDED_ADDRESS);
Every device in a G3 network needs a unique EUI64 to be identified.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

20 Atmel
2 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
 This EUI64 (or extended address) is stored in the variable CONF_EXTENDED_ADDRESS, which has a default
value, the same for every device, so a mechanism to ensure that different devices take different EUI64s is
required.
Normally this is considered an application task, and thus the MAC_PIB_MANUF_EXTENDED_ADDRESS is
provided so user application can modify the EUI64 of a device according to its needs.
Anyway, platform files provide a mechanism so user can read the EUI64 of each device from its flash memory,
making it unique and persistent. The implementation reads data from a reserved area in flash memory and if a
certain sequence is found, the following bytes are taken as the EUI64, in case this sequence is not found, default
value for EUI64 is kept. For more details, check the implementation of function platform_init_eui64.
Mechanism to store expected sequence and EUI64 in flash memory is not provided, as it is expected to be done
when flashing the device.
As said before, this is just an example of persistent EUI64 implementation, but as other mechanisms in platform
files, it may be change by the user.
4.2.3.4 IPv6 stack support
#ifdef OSS_ENABLE_IPv6_STACK_SUPPORT
/* Initialize IPv6 stack */
netInit();
#endif
The G3 protocol is meant to use and IPv6 layer over it in most of applications. As this IPv6 is considered out of
the scope of the G3 stack though, it is not included in the provided G3 library.
An implementation of a third party of an IPv6 stack is provided in order to demonstrate the usage of DLMS over
it and the link between IPv6 and the G3 stack.
The usage of this IPv6 is optional in the sense that the user can build an application directly over the G3 stack
without IPv6 layer, but as mentioned before, this is not the usual case. The usage if this layer is depending on
the definition of the constant OSS_ENABLE_IPv6_STACK_SUPPORT, located in file conf_oss.h. In case of
provided example, IPv6 layer is needed, and thus this constant is defined by default.
4.2.3.5 User application initialization
/* User-defined initialization */
if(pf_app_init_cb != NULL) {
pf_app_init_cb();
}
As seen in section 4.2.2 Second step. Setting user function pointers, user can set a pointer to a function where
user application performs its initialization tasks.
When this pointer is set, the variable pf_app_init_cb points to that function, and thus it is called here, just after
G3 stack initialization and before executing the program main loop.
Important note: User application initialization has to perform at least one task, which is initializing the G3 stack
using the function AdpInitialize. This is not done directly by OSS because one of the parameters to set in the G3
stack initialization is the pointer to the callback functions that G3 stack will call when notifications have to be
reported from the stack to the application, and such callback functions have to be implemented by application.
This is why it is the application which must call the G3 stack initialization function.
For more information regarding AdpInitialize function, refer to section B.4.1 Initialization function.
4.2.3.6 USI initialization
#if (NUM_PORTS != 0)
usi_init();
#endif
In case Universal Serial Interface (USI) is used, it is initialized here using usi_init function.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 21 2
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
1
 This function is called depending in the value for the constant NUM_PORTS, located in file conf_usi.h.
The provided example does not make use of USI, so NUM_PORTS is set to 0 in its configuration file.
4.2.3.7 Main loop
After all initializations seen in previous sections, program enters in the main infinite loop. The following recursive
processes are performed in this main loop.
Reset Watchdog
On every main loop, watchdog timer is reloaded. Watchdog timer is used to avoid program to get stuck and stop
looping through these processes.
If user wants to avoid watchdog to be active, the constant CONF_BOARD_KEEP_WATCHDOG_AT_INIT,
located in conf_board.h file, has to be undefined.
Process call check
if (platform_flag_call_process()) {
The call of periodic functions, or event handlers, of different stack and app layers, is done depending on the
result value of the function platform_flag_call_process. As seen on section 4.2.3.1 Time Control initialization, a
call rate for event handlers is configured through the constant OSS_APP_EXEC_RATE which as stated there
is configured to 1 millisecond period and should not be changed.
Summarizing, this function will return true when called on a different millisecond from previous call, and thus
event handlers of different layers will be called.
User application event handler
/* User-defined initialization */
if(pf_app_process_cb != NULL) {
pf_app_process_cb();
}
In case user has set a function pointer to a function that should be called periodically as event handler (as seen
on section 4.2.2 Second step. Setting user function pointers), function pf_app_process_cb will point to it, and
thus it will be called here.
If no event handler is configured on user application, no function is called.
USI event handler
#if (NUM_PORTS != 0)
usi_process();
#endif
As seen on section 4.2.3.6 USI initialization, in case NUM_PORTS constant is set to a value different to 0
because USI is used, its event handler will be called here.
G3 Stack event handler
#ifdef OSS_G3_ADP_MAC_SUPPORT
AdpEventHandler();
#endif
When constant OSS_G3_ADP_MAC_SUPPORT, located in file conf_oss.h is defined, the G3 stack event
handler is called. The reason for not defining this constant, which seems that does not make much sense, is
when for example, an application is running directly over the PHY layer and the PHY event handler is called
directly from application event handler.
The function called is AdpEventHandler, which is the event handler for the ADP layer. This function internally
manages the call to the lower layers of the stack (MAC, PAL and PHY), so the user does not have to worry about
managing all these handlers.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

22 Atmel
2 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
2
 As stated before, this function has to be called every 1ms, and no other user task should interrupt the
AdpEventHandler execution to ensure time constraints defined in G3 are met.
For more information regarding AdpEventHandler function, refer to section B.4.2 Event handler function.
IPv6 event handler
#ifdef OSS_ENABLE_IPv6_STACK_SUPPORT
netTask();
#endif
As explained in section 4.2.3.4 IPv6 stack support, the provided example makes use of a third party IPv6 stack,
as constant OSS_ENABLE_IPv6_STACK_SUPPORT is defined, its event handler will be called here.
Activity LED blinking
platform_led_update();
Finally, the main loop checks whether the activity LED has to blink using function platform_led_update. The
blinking of the LED is decided depending on the constant OSS_LED_BLINK_RATE, as seen on section 4.2.3.1
Time Control initialization.

4.3 DATA LINK processes

Flow diagrams for different Data Link layer processes are showed in this chapter for helping to the user to
understand the flow of messages through the stack and the behavior of a G3-PLC network.

4.3.1 Network Discovery Request

The ADPM-DISCOVERY.request primitive allows the upper layer to request the ADPM to scan for networks
operating in its POS. The ADPM-DISCOVERY.confirm primitive is generated by the ADP layer upon completion
of a previous ADPM-DISCOVERY.request.

Figure 4-1. Network Discovery Request flow chart.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 23 2
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
3
4.3.2 Network Join Request
The ADPM-NETWORK-JOIN.request primitive allows the upper layer to join an existing network. The ADPM-
NETWORK-JOIN.confirm primitive is generated by the ADP layer to indicate the completion status of a previous
ADPM-NETWORK-JOIN.request.

Figure 4-2. Network Join Request flow chart.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

24 Atmel
2 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
4
4.3.3 Route/Path Discovery Request
The ADPM-ROUTE-DISCOVERY.request primitive allows the upper layer to initiate a route discovery. The
ADPM-ROUTE-DISCOVERY.confirm primitive allows the upper layer to be informed about a previous ADPM-
ROUTE-DISCOVERY.request primitive.

Figure 4-3. Route Discovery Request flow chart.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 25 2
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
5
 The ADPM-PATH-DISCOVERY.request primitive allows the upper layer to initiate a path discovery. The ADPM-
PATH-DISCOVERY.confirm primitive allows the upper layer to be informed of the completion of a path discovery
(ADPM-PATH-DISCOVERY.request).

Figure 4-4. Path Discovery Request flow chart.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

26 Atmel
2 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
6
4.3.4 Network Leave
The ADPM-NETWORK-LEAVE.request primitive allows a non-coordinator device to remove itself from the
network. The ADPM-NETWORK-LEAVE.confirm primitive allows the upper layer to be informed of the status of
its previous ADPM-NETWORK-LEAVE.request

Figure 4-5. Network Leave flow chart.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 27 2
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
7
4.3.5 Data Request
The ADPD-DATA.request primitive requests the transfer of an application PDU (i.e.: IPv6 packet) to another
device or multiple devices. The ADPD-DATA.confirm primitive reports the result of a previous ADPD-
DATA.request primitive. And the ADPD-DATA.indication primitive is used to transfer received data from the
adaptation sublayer to the upper layer.

Figure 4-6. ADP Data Request flow chart.

Figure 4-7. ADP Data Request flow chart. Retransmission due to ACK fail.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

28 Atmel
2 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
8
4.3.6 ADP Reset
The ADPM-RESET.request primitive performs a reset of the adaptation sublayer and allows the resetting of the
MIB attributes. The ADPM-RESET.confirm primitive allows the upper layer to be notified of the completion of an
ADPM-RESET.request primitive.

Figure 4-8. ADP Reset flow chart.

4.3.7 GET/SET MIBs

The ADPM-GET.request primitive allows the upper layer to get the value of an attribute from the ADP information
base. The ADPM-GET.confirm primitive allows the upper layer to be informed of the status of a previously issued
ADPM-GET.request primitive.
The ADPM-SET.request primitive allows the upper layer to set the value of an attribute in the ADP information
base. The ADPM-SET.confirm primitive allows the upper layer to be informed about a previous ADPM-
SET.request primitive.

Figure 4-9. ADP GET Request and ADP SET Request flow charts.

The ADPM-MAC.GET.request primitive allows the upper layer to get the value of an attribute from the MAC
information base. The upper layer cannot access directly the MAC layer while ADP is running. The ADPM-
MAC.GET.confirm primitive allows the upper layer to be informed of the status of a previously issued ADPM-
MAC.GET.request primitive.
The ADPM-MAC.SET.request primitive allows the upper layer to set the value of an attribute in the MAC
information base. The upper layer cannot access directly the MAC layer while ADP is running. The ADPM-
MAC.SET.confirm primitive allows the upper layer to be informed about a previous ADPM-MAC.SET.request
primitive.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 29 2
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
9
 Figure 4-10. ADPMAC GET Request and ADPMAC SET Request flow charts.

4.4 Configuration files

The stack contains a variety of configuration files, which allow some features to be active or not, or some
behaviours to be changed.
Each provided application contains a folder for each supported device and associated evaluation board. This
folder contains the projects for the corresponding device and board, and the configuration files for that projects.
Apart from particular device or board configuration files the following configuration files are available:
 conf_atpl360.h (Only in projects using ATPL360A)
 conf_board.h
 conf_bs.h
 conf_buart_if.h
 conf_busart_if.h
 conf_c0216CiZ.h (Only in projects using ATPL360AMB board)
 conf_clock.h
 conf_oss.h
 conf_platform.h
 conf_pplc_if.h
 conf_project.h
 conf_uart_serial.h
 conf_usi.h
 FreeRTOSConfig.h
The meaning of these configuration files is described in more detail in the following sections.

4.4.1 ATPL360 Configuration - conf_atpl360.h

Constants used for ATPL360 configuration.

4.4.2 Board Configuration - conf_board.h

Watchdog timer can be enabled/disabled here.
UARTs and SPIs used are defined here.
For some evaluation boards, a definition is used in order to configure pins to access an external flash memory.

4.4.3 Bootstrap Module configuration – conf_bs.h

Configuration of Bootstrap and Coordinator. PAN_ID, number of supported devices (must be aligned with the
used G3 library), and an address reserved for Coordinator and considered invalid for Devices.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

30 Atmel
3 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
4.4.4 PLC UART Buffered configuration - conf_buart_if.h
Configuration of HW timers and buffer sizes for the UARTs.

4.4.5 PLC USART Buffered configuration - conf_busart_if.h

Configuration of HW timers and buffer sizes for the USARTs.

4.4.6 ATPL360AMB LCD configuration - conf_c0216CiZ.h

Configuration of LCD used in ATPL360AMB boards.

4.4.7 Clock Configuration – conf_clock.h

Configuration of the clock source and clock tree of the microcontroller.

4.4.8 OSS Layer configuration – conf_oss.h

On this file, user can decide to run the program in microcontroller mode or use an OS (FreeRTOS is the one
supported in the provided examples). Defining OSS_USE_FREERTOS will cause the program to run in OS
mode. By default this is not defined, so microcontroller mode will be used.
This file also defines OSS_LED_BLINK_RATE, which sets the rate of the activity LED blinking. This may be used
to set a different rate to different applications to distinguish them when running on different boards.
The activation or deactivation of different layers is also decided here:
OSS_ENABLE_IPv6_STACK_SUPPORT adds an IPv6 layer to the running stack. See section 4.2.3.4 IPv6 stack
support for more information.
OSS_G3_ADP_MAC_SUPPORT makes ADP and MAC layers of the G3 stack to run in the current application.
As explained in a previous section, this may be confusing, because user may expect that these layers have to
run always, but this is left configurable to be able to run applications directly over the PHY layer (which would
not be strictly G3 applications though).

4.4.9 Platform configuration – conf_platform.h

This file contains HW configuration parameters related to Timers and to Power Down Detection.

4.4.10 PPLC Interface configuration – conf_ pplc_if.h

This file specifies the configuration of the hardwired interface between the microcontroller and the G3-PLC
modem:
 Configuration of SPI module
 Interruption signaling
 Reset signaling

4.4.11 Project configuration – conf_project.h

Configuration of work band and enable/disable embedded sniffer.
In case serialization is used for project, also contain on which port is each protocol serialized.
This file is where the user should include any compilation constant related to user application code. It is a generic
file local to the project that user may extend depending on its needs.

4.4.12 Serial USART Service configuration – conf_uart_serial.h

Definition of the console UART.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 31 3
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
1
4.4.13 Universal Serial Interface configuration – conf_usi.h
Configuration of number of Ports/Protocols managed by USI.

4.4.14 Generic FreeRTOS peripheral control functions configuration – FreeRTOSConfig.h

FreeRTOS configuration that the user can modify according to his needs.

Please take into account the requirements, handling and usage of the Atmel G3-PLC FW
Stack prior to changing the RTOS configuration. Please read carefully chapter 5 Operating
System Support.

4.5 Persistent Data Storage

G3-PLC Specification requires that some parameters of the G3 stack keep their current value even after a reset
/ power down of the equipment running the stack.
Such parameters are Frame Counters, used as a sort of absolute sequence numbers during the whole life of a
device inside a network, and thus used to validate the frames on the receiver side. This means that if these
Frame Counters are reset (or lose their current value), the subsequent transmitted frames will be ignored by the
receiver as they will not meet the expectations related to Frame Counters.

G3-PLC FW Stack does not manage this save/restore mechanism itself. It is up to Application
to manage this storage and recovery of the required data.

The data that needs to be persistently stored is the one contained in the following ADP and MAC IBs:
 MAC_PIB_FRAME_COUNTER
 ADP_IB_MANUF_DISCOVER_SEQUENCE_NUMBER
 ADP_IB_MANUF_BROADCAST_SEQUENCE_NUMBER

Application has to make sure that these IBs are read before the reset / power down occurs, and that the same
IBs are written with the previously read values just after G3 stack initialization.
In the provided Example Application DLMS Emulator (see 7.1.1), the user can find an implementation of this
mechanism, using a provided module called “Storage”.
To summarize what the example does, it stores the read values on GPBRs when some of them change, so the
values can be restored after a reset, and at the same time, it uses a functionality of the “Platform” module which
is able to detect an imminent Power down, in which case, the information is stored in non-volatile memory to be
restored at the next power up.

4.6 Firmware Update process

As the G3-PLC specification does not define a standard Firmware Upgrade process, the stack has to be
upgradeable using the DLMS mechanisms.
User Application will perform the memory management and process for Firmware Update process.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

32 Atmel
3 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
2
5 Operating System Support

5.1 Overview
User applications can run over an operating system, which means that the G3-PLC stack implementation needs
to support that.
The OSS intends to transform the microcontroller-mode operation into a task-mode operation typical of operating
systems. In order to do that, it creates and manages a single task where all active layers and interfaces are
included. The user does not need to take care of controlling how the G3-PLC stack is running and can create
their applications normally. The current implementation of the OSS is based on FreeRTOS but the user can
modify it appropriately to use any other RTOS.

5.2 G3-PLC process. Requirements, Handling and Usage of the G3-PLC FW stack
When RTOS is used, the user has to take into account the requirements of different tasks running, to configure
parameters such as the stack for each one of the tasks.
The implementation given takes into account the needed resources for provided example, but any modification
may have a direct impact on these needs, and thus FreeRTOS configuration file may need to be modified.

Please take into account that the provided RTOS support is just an example of integration of
the stack in an RTOS. It is functional, but Atmel does not ensure the same reliability and
performance as the microcontroller mode implementation, as the latter is the reference
implementation.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 33 3
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
3
6 Toolchain
The following sections describe the required tools and toolchain for the development and build process and how
the provided example applications can be built.

6.1 General prerequisites

The following tools and toolchains are used for building the applications from this FW package:
 Atmel Studio (see http://www.atmel.com/tools/ATMELSTUDIO.aspx)
 IAR™ Embedded Workbench (see http://www.iar.com/)
 Keil™. MDK-ARM Microcontroller Development Kit (see http://www.keil.com/arm/mdk.asp)

6.2 Building the applications

6.2.1 Using Atmel Studio

Each application can be rebuilt using the AS6 directly. Version to be used is 6.2 or 7.

6.2.2 Using IAR Embedded Workbench

Each application can be rebuilt using the IAR Embedded Workbench directly. Version to be used is 7.80.

6.2.3 Using Keil

Each application can be rebuilt using Keil uVision directly. Version to be used is 5.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

34 Atmel
3 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
4
7 Example applications
Please note that all provided application examples have been configured to work on our
evaluation boards. Every firmware project must define a board support package (BSP)
according to the hardware to be used.

Along with the G3-PLC FW stack, some application examples are provided in order to show how to use the stack.
Examples can be divided in 2 groups:
 ADP examples, using the whole stack (ADP + MAC + PHY), to evaluate Atmel’s G3 solution as a whole.
 PHY examples, using only PHY layer, in order to evaluate some low level parameters, or to be used
connected to a PC tool for demonstration purposes.
Both groups are detailed below.
Applications are provided for Cenelec, FCC and ARIB bands (project folders with suffixes “_cen” and “_fcc_arib”
in each example shall be used). Setting FCC or ARIB band in common projects is made by means of
conf_project.h file, as explained in section 4.4.11.

7.1 ADP examples

7.1.1 DLMS App

The DLMS App is an example that shows how the G3 API along with an IPv6 stack should be used from a typical
DLMS application. This application is provided for both Device and Coordinator, implementing a DLMS Client
and Server respectively. Coordinator will perform a continuous data collection to generate data traffic in the G3
network.
If more than one Device is used, different Extended Address has to be configured for each one, to do so, change
the value of the variable CONF_EXTENDED_ADDRESS[8] that can be found in file oss/oss_if.c before compiling
the project.
File dlms_app_coord.h contains some configuration constants which can be changed by the user depending on
the number of Devices connected and the number of hops required to reach Coordinator if complex setups are
used. These setup-dependent constants are:
 DLMS_APP_ENABLE_PATH_REQ. Enables path request to all devices from Coordinator. If enabled,
before each cycle, a path request round will be executed. Undefined by default. Note: as the structure
to hold path request is quite memory consuming, when this is enabled, the number of supported devices
may have to be lowered in order to fit in RAM memory.
 DLMS_APP_ENABLE_PING_CYCLE. Enables ping frames to devices before each cycle. Undefined by
default.
 TIME_OUT_DATA_MSG. Time in milliseconds to consider a data timeout when no response is received
from Device and continue with the next data request. Depending on setup, and especially when hops
and routes are required, the round trip time of a data request-response may be high. Recommended
value, based on times defined as default by G3 Spec, is to follow the rule [50 seconds * number of hops
in setup], e.g. 50 seconds for a flat setup with 1 hop, 250 seconds for a 5 hop setup, and so on. Default
value is 150 seconds.
 TIMER_WAITING_START. Time in milliseconds to wait until Application starts sending data requests to
nodes present in the network. Depending on DLMS_APP_WAIT_REG_NODES constant (explained
below), this time can be an absolute time starting when Coordinator is powered up, or can be dynamically
reloaded if network activity is detected. When this timer expires, DLMS traffic starts, taking into account
only the Devices present in the Network in that moment, so, in case DLMS_EMU_WAIT_REG_NODES
is not defined, this time has to be long enough to let all Devices perform correctly their bootstrap process.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 35 3
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
5
 Bootstrap process time per device is deeply dependent on the number of devices joining the network
(the more devices, the more collisions and thus the mode delay until next try) and also on the number of
hops needed to perform the join process (hops increase the time to reach coordinator and get a
response). A time of one minute per device will fit almost any setup (will be much more than needed in
simple setups, but just to give a general rule). Default value is 120 seconds.
 DLMS_APP_WAIT_REG_NODES. Each time bootstrap or routing activity is detected in the network, the
timer which waits for TIMER_WAITING_START is reloaded, so cycles will only start after
TIMER_WAITING_START time without bootstrap or routing traffic. This is useful as user does not need
to care about network topology to calculate the proper time to wait before cycles start. Defined by default.

7.1.2 Gateway App

This application implements a G3 Coordinator with IPv6 Routing capabilities. The idea is that this gateway can
be accessed via IPv6 and it will act as a bridge with the G3 network. This makes it possible, for example, to
perform pings to G3 nodes from an external Device, where such external device speaks only IPv6 and does not
even know there is a G3 network below.
This application is the one to be used in a board when G3 Manager PC tool is connected to such board.

7.1.3 ADP & MAC Serialization App

The ADP and MAC serialization is an application example that brings access to the ADP, MAC and Bootstrap
API through a serial connection. This application could be useful for users that want to make intensive test for
the stack or want to run the upper layers in other CPU.
The application allows to control the G3 PLC Stack at different levels, the user can make use of the ADP API
when SERIAL_MSG_ADP_INITIALIZE command is sent through the serial connection. In the same way MAC
API is available after a SERIAL_MSG_MAC_INITIALIZE command through the serial connection. A special
function command is available in order to initialize Bootstrap module and ADP at the same time, this command
is SERIAL_MSG_COORD_INITIALIZE, this command bring access to the API of bootstrap module as well as
ADP API except to LBP functions that will be redirected to the bootstrap module.

7.1.4 Conformance App

This application implements all functionalities required by a DUT in the official G3 Certification Process.
It is provided in order to illustrate the used about the Certification needs, and allows to perform testing in case
the official Certification tool is available.
It is provided for both Coordinator and Device.

7.2 PHY examples

7.2.1 PHY Tester

The PHY Tester Tool is an application example that demonstrates the complete performance of the Atmel G3
PHY Layer on PLC boards. This example requires a board and a PC tool, the Atmel PLC PHY Tester tool
(available in the Atmel website), which has to be installed in the user’s host PC to interface with the boards.
The PC tool configures the devices and performs the communication tests.
This example offers the serial interface configured through UART0 at 115200bps.

7.2.2 PHY Sniffer

The PHY Sniffer is an application example that uses the PHY layer to monitor data traffic in the G3 network and
then sends it via serial communications to a PC tool, the ATPL Multiprotocol Sniffer Tool (available in the Atmel

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

36 Atmel
3 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
6
 website), which has to be installed in the user’s host PC to interface with the board. This example requires only
one board – and obviously a G3 network to be monitored.
This example offers the serial interface configured through UART0 at 115200bps.

7.2.3 TX console
Due to PC timing, the Atmel PLC PHY Tester Tool may present limitations in those applications or tests that
require a very short time interval between consecutives frame transmissions. The PHY Test Console example
has been developed for those applications.
The PHY Test Console is an application example that demonstrates the complete performance of the Atmel G3
PHY Layer avoiding the limitations of timing in the PC host. Then, users can perform more specific PHY tests
(e.g. short time interval between consecutive frames).
This PHY Test Console application offers an interface to the user by means a command console. In this console,
users can configure several transmission parameters, such as modulation, frame data length and time interval
between frames. In the console it is also possible to test transmission/reception processes.
This example offers the serial interface configured through UART1 at 115200bps.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 37 3
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
7
8 Supported platforms
This chapter describes which hardware platforms are currently supported with the Atmel G3-PLC software
package. A platform usually comprises of three major components:
 An MCU
 A transceiver chip. This may be integrated into the MCU (i.e.:SAM4CP16C)
 A specific Board or even several boards that contain the MCU or the transceiver chip

8.1 Supported MCU families

Currently the supported families are SAM4C, SAME70 and SAMG55 platforms.
The dedicated code for each device of the family can be found in the corresponding subdirectories of the FW
package.

8.2 Supported transceivers

Currently the supported devices are SAM4CP16C, ATPL250A and ATPL360A.

8.3 Supported boards

The currently supported boards and combinations are given below:
 SAM4CP16C-MB
 ATPL250A-MB
 ATPL250A-BN
 ATPL250CH
 ATPL360A-MB

8.4 Platform porting

For details and description about platform porting please refer to Atmel Software Framework documentation and
Atmel Studio-help.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

38 Atmel
3 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
8
9 Protocol implementation conformance statement
This chapter lists the conformance of the Atmel G3-PLC implementation with the requirements and optional
features as defined by the G3-PLC specification document.
A Protocol Implementation Conformance Statement (i.e. PICS), as defined by ISO 9646 [2], is a declaration
listing the capabilities and options supported by an implementation. The PICS is based on a list of options and
values, defined in the G3 specification and in the Test Suites used by the certification process.
When an implementation is tested for certification, the implementer must provide the PICS corresponding to the
implementation capability.
The PICS values are integrated in the device certificate, in order to indicate the conditions of the certification in
term of implemented options.

9.1 Band-plan support

This PICS entry is used to describe the band-plan supported by the IUT.
If a physical device is able to support several band-plans, it will be tested once for each band-plan, setting the
following PICS value accordingly.
Current implementation supports Cenelec-A, ARIB and FCC bandplans.

9.2 Feature implementation statement

Atmel G3 PLC stack implements the following optional features:
Coherent Modulation.
Security profile F1 and F2.
Routing: LOADng implementation supporting Composite Metrics and Capacity Metrics.

9.3 Other features

Atmel provides a Bootstrap module with some basic PAN Coordinator features, such as creating the Network
and accepting all Network Join from the Devices.
This way, it is possible to build a network so data can be exchanged.
This is just a basic implementation for demonstration purposes, and it should not be taken as the reference to
build a complete PAN Coordinator.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 39 3
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
9
10 Abbreviations

ADP Adaptation Sublayer

ADPD Adaptation Sublayer Data Service

ADPIB Adaptation Sublayer Information Base

ADPM Adaptation Sublayer Management Service

API Application Programming Interface

APP Application

AS6 Atmel Studio 6

ASF Atmel Software Framework

FW Firmware

HAL Hardware Abstraction Layer

MAC Medium Access Control

MCPS MAC Common Part Sub-layer

MCU Microcontroller Unit

MIB MAC Information Base

MIC Message Integrity Code

MLME MAC Sub-layer Management Entity

MSDU MAC Service Data Unit

OSS Operating System Support

PAL PHY Abstraction Layer

PAN Personal Area Network

PDU Physical layer Data Unit

PIB PHY Information Base

PLME Physical Layer Management Entity

SPI Serial Peripheral Interface

TRX Transceiver

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

40 Atmel
4 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
11 References
1. Atmel Smart Energy: http://www.atmel.com/products/smart-energy/default.aspx
2. Atmel Power Line Communications: http://www.atmel.com/products/smart-energy/power-line-
communications/default.aspx
3. Atmel Design Support: http://www.atmel.com/design-support/
4. ITU G.9903: https://www.itu.int/rec/T-REC-G.9903/en
5. ITU G.9901: http://www.itu.int/rec/T-REC-G.9901/en
6. G3-PLC Alliance: http://www.g3-plc.com/
7. ATSAM4CP16C Evaluation Kit: http://www.atmel.com/tools/ATSAM4CP16C-EK.aspx
8. ATPL250A Evaluation Kit: http://www.atmel.com/tools/ATPL250A-EK.aspx
9. Atmel Software Framework: http://www.atmel.com/tools/avrsoftwareframework.aspx,
http://asf.atmel.com/docs/latest/
10. Atmel Studio: http://www.atmel.com/microsite/atmel_studio6/
11. Atmel documents for supported families and boards: asf.atmel.com/docs/latest

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 41 4
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
1
12 Evaluation License Agreement
IT IS IMPORTANT THAT YOU READ THIS AGREEMENT CAREFULLY AND COMPLETELY. This Evaluation
License Agreement (“Agreement”) is a legally binding agreement between your employer (“Licensee”) and Atmel
Corporation (“Atmel”). By clicking the “I Accept” button or by downloading, installing or using any of the software
available for download (“Licensed Software”), you are indicating that you are binding Licensee to the terms of
this Agreement, and that you are duly authorized by Licensee to do so. If you are not authorized to bind Licensee
to the terms of this Agreement, or if Licensee does not agree to be bound by all of the terms of this Agreement,
do not click the “I Accept” button and do not download, install or use any such software.
1. License Grant. Subject to the terms and conditions of this Agreement, Atmel grants Licensee a non-
exclusive, non-transferable, non-sublicensable, limited license to internally use the Licensed Software in
connection with the evaluation of an Atmel product.
2. Restrictions. Licensee will not, and will have no right to, (a) use, copy, reproduce, modify, create
derivative works of, sell, distribute, disclose or otherwise exploit any Licensed Software, except as expressly set
forth in Section 1, or (b) decompile or otherwise reverse engineer any Licensed Software that is not provided in
source code form, or otherwise derive or attempt to derive the source code of any such Licensed Software.
Licensee will not remove, obscure or alter any trademark, copyright or other proprietary rights and ownership
notices of Atmel or any of its licensors that appear in any Licensed Software, and Licensee will reproduce all
such trademarks and proprietary rights and ownership notices on all copies of Licensed Software made by
Licensee.
3. Ownership; Reserved Rights; License to Atmel. Atmel and its licensors will retain title to and ownership
of the Licensed Software, including, without limitation, all copyrights, patents, trade secrets and other intellectual
property rights in and to the Licensed Software. Nothing contained in this Agreement will be construed as
conferring upon Licensee or any third party (whether by implication, operation of law, estoppel or otherwise) any
right or license not expressly granted by Atmel to Licensee under this Agreement.
4. Term and Termination. This Agreement will remain in effect until terminated. Atmel or Licensee may
terminate this Agreement at any time with written notice to the other. This Agreement will automatically terminate
if Licensee fails to comply with the terms and conditions of this Agreement
5. Effect of Termination. Upon any termination of this Agreement, (a) all licenses granted to Licensee under
this Agreement will terminate, (b) Licensee will discontinue all use of the Licensed Software, (c) Licensee will
destroy all copies of the Licensed Software, and (d) the rights and obligations of the parties under Sections 3, 5,
6, 7, 8, 9 and 10 will survive such termination.
6. Warranty Disclaimer. THE LICENSED SOFTWARE IS PROVIDED TO LICENSEE “AS IS” AND “WITH
ALL FAULTS.” ATMEL DOES NOT MAKE, AND ATMEL HEREBY DISCLAIMS, ANY REPRESENTATIONS OR
WARRANTIES OF ANY KIND (WHETHER EXPRESS, IMPLIED, STATUTORY OR OTHERWISE) IN
CONNECTION WITH THE LICENSED SOFTWARE OR ANY OTHER ASPECT OF THIS AGREEMENT,
INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT OF THIRD PARTY RIGHTS, AND ANY
WARRANTIES THAT MAY ARISE FROM COURSE OF DEALING, COURSE OF PERFORMANCE OR USAGE
OF TRADE. Atmel will have no obligation under this Agreement to correct any bugs, defects or errors in the
Licensed Software.
7. Limitation of Liability. TO THE EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL
ATMEL BE LIABLE TO LICENSEE OR ANY THIRD PARTY (WHETHER SUCH LIABILITY IS BASED ON
CONTRACT, NEGLIGENCE, STRICT LIABILITY, OTHER TORT THEORY, CONTRIBUTION, BREACH OF
WARRANTY, OR OTHER LEGAL OR EQUITABLE THEORY) FOR ANY SPECIAL, INDIRECT, INCIDENTAL,
EXEMPLARY, PUNITIVE OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES FOR LOSS OF PROFITS,
LOSS OR INTERRUPTION OF BUSINESS, OR LOSS OF DATA, ARISING OUT OF OR RELATING TO THE

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

42 Atmel
4 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
2
LICENSED SOFTWARE OR ANY OTHER ASPECT OF THIS AGREEMENT, EVEN IF ATMEL HAS BEEN
ADVISED OF OR SHOULD HAVE KNOWN OF THE POSSIBILITY OF SUCH DAMAGES.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL ATMEL’S TOTAL
LIABILITY ARISING OUT OF OR RELATED TO THE LICENSED SOFTWARE OR ANY OTHER ASPECT OF
THIS AGREEMENT (WHETHER UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION,
BREACH OF WARRANTY, OR OTHER LEGAL OR EQUITABLE THEORY) EXCEED THE GREATER OF (A)
THE AGGREGATE OF ALL LICENSE FEES PAID BY LICENSEE TO ATMEL FOR THE LICENSED
SOFTWARE AND (B) ONE HUNDRED DOLLARS ($100).
8. Compliance with Laws; Export. Licensee will comply with the laws and regulations of the United States
and all other relevant jurisdictions in connection with its activities related to the Licensed Software. Without
limitation of the foregoing, Licensee acknowledges that certain laws and regulations of the United States and
other jurisdictions may pertain to the export and re-export of the Licensed Software, and Licensee will not export
or re-export any Licensed Software in any form without the appropriate governmental approvals, or otherwise in
violation of any such laws or regulations.
9. Governing Law; Dispute Resolution. This Agreement is to be construed in accordance with and governed
by the internal laws of the State of California (as permitted by Section 1646.5 of the California Civil Code or any
similar successor provision), without giving effect to any choice of law rule that would cause the application of
the laws of any jurisdiction other than the internal laws of the State of California to the rights and duties of the
parties. This Agreement will not be governed by the U.N. Convention on the Sale of Goods, the application of
which is expressly excluded. Except for actions for injunctive or other equitable relief, which may be brought in
any court of competent jurisdiction, all disputes arising out of or related to this Agreement will be subject to the
exclusive jurisdiction of the California state courts in Santa Clara County, California, or if there is exclusive federal
jurisdiction, the United States District Court for the Northern District of California, and the Parties hereby consent
to, and agree to submit to, the personal and exclusive jurisdiction and venue of such courts.
10. General. Licensee will not, and will have no right to, assign, delegate or otherwise transfer (whether
voluntarily, by operation of law or otherwise) this Agreement or any of its rights or obligations hereunder to any
third party without the prior written consent of Atmel, and any purported assignment, delegation or other transfer
without such consent will have no force or effect. Subject to the foregoing, this Agreement will be binding upon
and will inure to the benefit of the parties and their respective successors and permitted assigns. No failure of
either party to enforce any right under this Agreement will be deemed a waiver of such right or any other right
under this Agreement. Any waiver by a party of a breach of any provision of this Agreement by the other party
hereunder will not be deemed to be a waiver of any subsequent breach of such provision or a waiver of any
breach of any other provision of this Agreement. This Agreement may not be superseded, modified, or amended
except in a writing signed by an officer of each party. If any provision of this Agreement is determined to be
invalid, illegal or otherwise unenforceable, such provision will be enforced to the extent possible consistent with
the intent of the parties, and the remaining provisions of this Agreement will remain in full force and effect. This
Agreement will be fairly interpreted in accordance with its terms and without any strict construction in favor of or
against either party. This Agreement will constitute the entire agreement between the parties relating to the
subject matter hereof, and expressly supersedes and replaces all prior and contemporaneous agreements,
proposals, quotations, negotiations and communications, written or oral, between the parties relating to such
subject matter.
Atmel Corporation
1600 Technology Drive
San Jose, CA 95110
http://www.atmel.com

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 43 4
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
3
13 Revision History

Doc Rev. Date Comments

doc43081A 12/2014 Initial document release.
doc43081B 12/2014 Preliminary release.
doc43081C 02/2015 Added new MAC PIBs and reviewed existing ones.
doc43081D 03/2015 Added and modified ADP/MAC PIBs. Added PHY configuration parameters.
doc43081E 03/2015 Included User Periodic Update function.
doc43081F 04/2015 Added MAC PIBs and reordered existing ones.
doc43081G 07/2015 Clarification on ZC_DELAY parameter, Updated ADP API description, Added MAC PIBs.
doc43081H 08/2015 Filled Example applications description. Updated Operating System Support section.

General revision of document. Chapter 4 deeply reviewed to show the stack functionality
doc43081I 09/2015 following one of the provided examples. Removed USI chapter. Added package
directory structure to complete chapter 2.
doc43081J 11/2015 Added new MAC and ADP IBs. Changed ZC_Delay figure for better understanding.
doc43081K 11/2015 Added new MAC and ADP IBs.
doc43081L 02/2016 Added Appendix C – LBP module.

Added new MAC and ADP IBs. Unique frame counter affects
doc43081M 03/2016
MAC_PIB_FRAME_COUNTER and MAC_PIB_MANUF_DEVICE_TABLE definitions.
doc43081N 04/2016 Added new ADP API function AdpPREQIndication. Watermark removed.

Review Appendix A. Review and completed LBP Objects Specification and Access
(Appendix C) to clarify access type and sizes of objects. Added status codes in Get/Set
doc43081O 04/2016 functions. Added Persistent Data Storage chapter (4.5). Completed information of setup
dependent parameters in DLMS Emulator example chapter. Added documentation for
new ADP_IB_MANUF_KEEP_PARAMS_AFTER_KICK_LEAVE.
doc43081P 06/2016 Completed Appendix C with a brief explanation of provided LBP module.

Added new PHY Params available as MAC MIB. Added MAC and ADP MIBs. Added
doc43081Q 07/2016 new ADP Primitive to indicate when non-volatile parameters change. Added support to
SAME70 and to Keil Compiler.
doc43081R 09/2016 Removed references to old names of functions and PIBs.

Added section B.8 ADP Status Codes description. Available impedance parameters
doc43081S 09/2016
documented. Format changes after document revision.
doc43081T 12/2016 Added ADP_IB_MANUF_MAX_REPAIR_RESEND_ATTEMPTS.
doc43081U 01/2017 Added new ADP IBs description and new ADP API primitive.

Added description on G3_FAILED error code, to include new usage for

doc43081V 03/2017
ADPDiscoveryConfirm when not expected.
doc43081W 04/2017 Added ATPL360 support. Updated example applications provided.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

44 Atmel
4 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
4
Appendix A API of PHY and PAL Layers
The user can obtain in this Appendix the association between the names of the standard primitives of the API of
PAL layer and the names of the corresponding functions implemented in this FW stack.

A.1 PHY SAP

A.1.1 Initialization function

G3-PLC PHY Layer must be always initialized when the device stars the execution. The following function
initializes the physical parameters and configures the transceiver device:

void phy_init(uint8_t uc_serial_enable);

Params:

uc_serial_enable Enables PHY layer serialization when set to true.

This function performs the following actions:

 Sets the handlers for the phy interruption.
 Initializes the PPLC driver.
 And, if necessary, initializes a serial interface for the PHY layer by means of the input parameter.

A.1.2 Event Handler function

The following function is called every program cycle by the PalEventHandler() function (see A.2.2):

uint8_t phy_process(void);

First, this function checks all PHY events:

 PHY parameters reset and reconfiguration
 Perform a Noise Capture
 End of transmission of PLC message
 End of reception of PLC message
 Reed-Solomon event
And then, triggers the corresponding PHY callbacks.
The return value of this function indicates whether it should be call again immediately due to an urgent event is
about to occur, or otherwise it is secure to wait for the next program cycle to call it.

A.1.3 Phy Data Primitives

A.1.3.1 PHY-DATA.request
This function sends a frame using the PHY layer:

uint8_t phy_tx_frame(xPhyMsgTx_t *px_msg)

The received parameter structure is the following:

typedef struct _xPhyMsgTx_t {

uint8_t m_uc_buff_id;

uint8_t m_uc_tx_mode;

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 45 4
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
5
 uint8_t m_uc_tx_power;

enum mod_types e_mod_type;

enum mod_schemes e_mod_scheme;

uint8_t m_uc_pdc;

uint8_t m_auc_tone_map[TONE_MAP_SIZE];

uint8_t m_uc_2_rs_blocks;

uint8_t m_auc_preemphasis[NUM_SUBBANDS];

enum delimiter_types e_delimiter_type;

uint8_t *m_puc_data_buf;

uint16_t m_us_data_len;

uint32_t m_ul_tx_time;

} xPhyMsgTx_t;

Fields of the structure:

m_uc_buff_id Buffer identifier

m_uc_tx_mode Transmission Mode (forced, delayed, ...) (Related Constants explained below)

m_uc_tx_power Power to transmit [0 = Full gain, 1 = (Full gain - 3dB), 2 = (Full gain - 6dB) and so
on]

e_mod_type Modulation type (Related Constants explained below)

e_mod_scheme Modulation scheme (Related Constants explained below)

m_uc_pdc Phase Detector Counter. Calculated and filled internally by PHY layer

m_auc_tone_map Tone Map to use on transmission (Related Constants explained below)

uc_2_rs_blocks Flag to indicate whether 2 RS blocks have to be used (only used in FCC
bandplan)

m_auc_preemphasis Preemphasis for transmission. Same as m_uc_tx_power but for each subband
(Related Constants explained below)

e_delimiter_type DT field to be used in header (Related Constants explained below)

m_puc_data_buf Pointer to data buffer

m_us_data_len Length of the data buffer

m_ul_tx_time Instant when transmission has to start referred to 1us PHY counter (Absolute
value, not relative). Only used when m_uc_tx_mode is Delayed transmission

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

46 Atmel
4 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
6
Related Constants affecting above parameters:
/* TX Mode flags */
/* TX Mode: Not Forced Not Delayed transmission, Carrier Sense before
transmission, transmission stars immediately after request */
#define TX_MODE_NOT_FORCED_NOT_DELAYED_TX 0x00
/* TX Mode: Forced transmission, Noo Carrier Sense before transmission,
transmission stars immediately after request */
#define TX_MODE_FORCED_TX 0x01
/* TX Mode: Delayed transmission, Carrier Sense before transmission,
transmission in a specified instant in time */
#define TX_MODE_DELAYED_TX 0x02
/* TX Mode: Forced and Delayed transmission, No Carrier Sense,
transmission in a specified instant in time */
#define TX_MODE_FORCED_AND_DELAYED_TX 0x03

/* Modulation types */
enum mod_types {
MOD_TYPE_BPSK = 0,
MOD_TYPE_QPSK = 1,
MOD_TYPE_8PSK = 2,
MOD_TYPE_QAM = 3,
MOD_TYPE_BPSK_ROBO = 4
};

/* Modulation schemes */
enum mod_schemes {
MOD_SCHEME_DIFFERENTIAL = 0,
MOD_SCHEME_COHERENT = 1
};

/* Frame Delimiter Types */

enum delimiter_types {
DT_SOF_NO_RESP = 0, /* Data frame requiring ACK */
DT_SOF_RESP = 1, /* Data frame Not requiring ACK */
DT_ACK = 2, /* Positive ACK */
DT_NACK = 3 /* Negative ACK */
};

/* Tone Map size for Cenelec-A bandplan */

#define TONE_MAP_SIZE_CENELEC 1
/* Tone Map size for FCC and ARIB bandplans */
#define TONE_MAP_SIZE_FCC_ARIB 3

#if defined(CONF_CENELEC_A)
#define TONE_MAP_SIZE TONE_MAP_SIZE_CENELEC
#else
#define TONE_MAP_SIZE TONE_MAP_SIZE_FCC_ARIB
#endif

/* Number of subbands for each bandplan */

#define NUM_SUBBANDS_CENELEC_A 6
#define NUM_SUBBANDS_FCC 24
#define NUM_SUBBANDS_ARIB 18

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 47 4
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
7
 #if defined(CONF_CENELEC_A)
#define NUM_SUBBANDS NUM_SUBBANDS_CENELEC_A
#elif defined(CONF_FCC)
#define NUM_SUBBANDS NUM_SUBBANDS_FCC
#elif defined(CONF_ARIB)
#define NUM_SUBBANDS NUM_SUBBANDS_ARIB
#endif

The function returns a transmission result value.

/* TX Result values */
enum tx_result_values {
PHY_TX_RESULT_PROCESS = 0, /* already in process */
PHY_TX_RESULT_SUCCESS = 1, /* end successfully */
PHY_TX_RESULT_INV_LENGTH = 2, /* invalid length error */
PHY_TX_RESULT_BUSY_CH = 3, /* busy channel error */
PHY_TX_RESULT_BUSY_TX = 4, /* busy in transmission error */
PHY_TX_RESULT_BUSY_RX = 5, /* busy in reception error */
PHY_TX_RESULT_INV_SCHEME = 6, /* invalid modulation scheme */
PHY_TX_RESULT_TIMEOUT = 7, /* timeout error */
PHY_TX_RESULT_INV_TONEMAP = 8, /* invalid tone map error */
PHY_TX_RESULT_NO_TX = 255 /* No transmission ongoing */
};

A.1.3.2 PHY-DATA.confirm
This data confirm callback executes the function set by the upper layer at the initialization of the PAL layer (See
A.2.1). The pointer to the function is set in

typedef void (*phy_pd_data_confirm)(xPhyMsgTxResult_t *px_tx_result);

The result is reported into the following structure:

typedef struct _xPhyMsgTxResult_t {

uint8_t m_uc_id_buffer;

enum tx_result_values e_tx_result;

uint32_t m_ul_rms_calc;

uint32_t m_ul_end_tx_time;

} xPhyMsgTxResult_t;

Fields of the structure:

m_uc_id_buffer Buffer to which result refers to

e_tx_result Tx Result (Constants listed in previous section)

m_ul_rms_calc RMS_CALC value after transmission. Allows to estimate tx power injected

m_ul_end_tx_time Instant when frame transmission ended referred to 1us PHY counter

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

48 Atmel
4 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
8
A.1.3.3 PHY-DATA.indication
This primitive is used to transfer received data from the PHY sublayer to the upper layer.

typedef void (*phy_pd_data_indication)(xPhyMsgRx_t *px_msg);

The information is reported into the following structure:

typedef struct _xPhyMsgRx_t {

uint8_t m_uc_buff_id;

enum mod_types e_mod_type;

enum mod_schemes e_mod_scheme;

uint8_t m_auc_tone_map[TONE_MAP_SIZE];

uint16_t m_us_evm_header;

uint16_t m_us_evm_payload;

uint16_t m_us_rssi;

uint16_t m_us_agc_factor;

uint8_t m_uc_zct_diff;

enum delimiter_types e_delimiter_type;

uint8_t m_uc_rs_corrected_errors;

uint8_t *m_puc_data_buf;

uint16_t m_us_data_len;

uint32_t m_ul_rx_time;

uint32_t m_ul_frame_duration;

} xPhyMsgRx_t;

Fields of the structure:

m_uc_buff_id Buffer identifier

e_mod_type Modulation type of the last received frame. Related Constants defined in
section A.1.3.1

e_mod_scheme Modulation scheme of the last received frame. Related Constants defined
in section A.1.3.1

m_auc_tone_map Tone Map in received frame. Related Constants defined in section A.1.3.1

m_us_evm_header EVM on header reception

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 49 4
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
9
 m_us_evm_payload EVM on payload reception

m_us_rssi Reception RSSI

m_us_agc_factor AGC factor

m_uc_zct_diff Phase difference with transmitting node

e_delimiter_type DT field coming in header. Related Constants defined in section A.1.3.1

m_uc_rs_corrected_errors Errors corrected by RS (errors == 0xff means could not correct)

m_puc_data_buf Pointer to data buffer containing received frame

m_us_data_len Length of received frame

m_ul_rx_time Instant when frame was received (end of frame) referred to 1us PHY
counter

m_ul_frame_duration Frame duration in us (Preamble + FCH + Payload)

A.1.4 Configuring PHY layer parameters

A.1.4.1 Bandplan selection
During the compilation, the G3-PLC bandplan must be defined (i.e.: CENELEC, FCC or ARIB) according to user
needs.
In atpl250db_conf.h there are three constant options for configuring the bandplan:

#if defined (CONF_BAND_CENELEC_A)

#define CONF_CENELEC_A

#elif defined (CONF_BAND_FCC)

#define CONF_FCC

#elif defined (CONF_BAND_ARIB)

#define CONF_ARIB

#else /* Default */

#define CONF_CENELEC_A

#endif

One of the 3 constants CONF_BAND_XXX has to be defined in order to PHY layer is correctly configured.
In the provided examples, this definition can be found in file conf_project.h.
A.1.4.2 ZC offset configuration
PHY layer calculates the electrical phase difference between transmitter and receiver for a given frame. To do
so, both devices have to be able to read the Zero Cross time of the mains.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

50 Atmel
5 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
 ATPL250 has a dedicated input pin in order to be connected to a signal which provides such mains zero cross.
Due to design reasons, the signal entering ATPL250 may not be fully synchronized with the real mains zero
cross.
To handle this, a configuration parameter is available in atpl250db_conf.h to set the delay, in µs, between mains
zero cross and the signal provided to ATPL250. The delay has to be measured between the highest point of the
mains signal and the middle of the positive pulse provided to G3 modem (see Figure A-1).

#define CONF_ZC_OFFSET_CORRECTION (uint32_t)0

Default value of this parameter is 0 (no delay).

If, for instance, signal to ATPL250 is delayed 16 ms from mains zero cross, this parameter has to be configured
like this:

#define CONF_ZC_OFFSET_CORRECTION (uint32_t)16000

Figure A-1. ZC_Delay calculation

A.1.4.3 Setting PHY Callbacks

As the different layers of the implementation are well separated, the way in which they interface is by means of
callbacks. That means that, at the very beginning of the execution, upper layers must communicate to their
immediate lower layer which function should be executed when a PLC transmission/reception has been
performed.
In case of this implementation of the G3-PLC PHY layer, this is done by means of phy_set_callbacks function:

void phy_set_callbacks(struct TPhyCallbacks *p_callbacks);

The structure used as input of phy_set_callbacks function contains two fields which are pointers to the functions
to be executed after a PLC transmission or reception:

static struct TPhyCallbacks g_pal_phy_callbacks = {

pal_cb_phy_data_confirm,
pal_cb_phy_data_indication
};

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 51 5
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
1
 User will need to redefine these callback pointers just in case of using a different FW from the MAC layer provided
by Atmel on top of the PAL layer.

A.1.5 Phy Management Primitives

A.1.5.1 PHY_SET.request

uint8_t phy_set_cfg_param(uint16_t us_id, void *p_val, uint16_t us_len);

The input parameters are the following:

us_id PIB ID (see atpl250.h file)

*p_val Pointer to parameter value to set

us_len Length of parameter

The function returns 0 if there is no error, otherwise returns Error Type (see atpl250.h).
A.1.5.2 PHY_GET.request

uint8_t phy_get_cfg_param(uint16_t us_id, void *p_val, uint16_t us_len);

The input parameters are the following:

us_id PIB ID (see atpl250.h file)

*p_val Pointer to parameter value to read

us_len Length of parameter

The function returns 0 if there is no error, otherwise returns Error Type (see atpl250.h).
A.1.5.3 PHY_RESET.request
It is possible to force a reset of PHY layer during program execution, calling the function:

void phy_reset_request (void)

This function performs the following actions:

 Resets all PHY layer variables and state machines.
 Initializes the PPLC driver.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

52 Atmel
5 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
2
A.2 PAL SAP

A.2.1 Initialization function

This function is called at the very beginning of the execution of the program:

void PalInitialize(struct TPalNotifications *pNotifications, uint8_t u8Band);

This function performs the setting of the PHY callbacks and initializes the PHY layer.

A.2.2 Event handler function

This function is called every program cycle by MacLowEventHandler() (See B.1.2):

void PalEventHandler(void);

This function calls phy_process() function (See A.1.2).

A.3 PAL Primitives

Please note that the semantics of the PHY primitives cover the requirements of the G3-PLC PHY specs and
provide more information. Note also that there are two Management Primitives not included into the spec which
are PLME_RESET.request and GET_TIME. For further details, please refer to pal.h header file.

A.3.1 Data Primitives

DATA PRIMITIVE Atmel Function

PD-DATA.request void PhyPdDataRequest(struct TPdDataRequest *pParameters);

PD-DATA.confirm typedef void(*PhyPdDataConfirm)(struct TPdDataConfirm *pParameters);

PD-DATA.indication typedef void(*PhyPdDataIndication)(struct TPdDataIndication *pParameters);

PD-ACK.request void PhyPdAckRequest(struct TPdAckRequest *pParameters);

PD-ACK.confirm typedef void(*PhyPdAckConfirm)(struct TPdAckConfirm *pParameters);

PD-ACK.indication typedef void(*PhyPdAckIndication)(struct TPdAckIndication *pParameters);

A.3.2 Management Primitives

MANAGEMENT PRIMITIVE Atmel Function

PLME_SET.request void PhyPlmeSetRequest(struct TPlmeSetRequest *pParameters);

PLME_SET.confirm typedef void(*PhyPlmeSetConfirm)(struct TPlmeSetConfirm *pParameters);

PLME_GET.request void PhyPlmeGetRequest(struct TPlmeGetRequest *pParameters);

PLME_GET.confirm typedef void(*PhyPlmeGetConfirm)(struct TPlmeGetConfirm *pParameters);

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 53 5
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
3
 PLME_SET_TRX_STATE.request void PhyPlmeSetTrxStateRequest(struct TPlmeSetTrxStateRequest
*pParameters);

PLME_SET_TRX_STATE.confirm typedef void(*PhyPlmeSetTrxStateConfirm)(struct

TPlmeSetTrxStateConfirm *pParameters);

PLME_CS.request void PhyPlmeCsRequest(struct TPlmeCsRequest *pParameters);

PLME_CS.confirm typedef void(*PhyPlmeCsConfirm)(struct TPlmeCsConfirm *pParameters);

PLME_RESET.request void PhyPlmeResetRequest(void);

GET_TIME uint32_t PhyGetTime(void);

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

54 Atmel
5 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
4
Appendix B API of DATA LINK Layer
The user can obtain in this Appendix the association between the names of the standard primitives of the API of
DATA LINK layer and the names of the corresponding functions implemented in this FW stack.

B.1 MAC SAP

All this functions and the structures used are defined in the file MacApi.h.

B.1.1 Initialization function

The MacInitialize function is used to initialize the MAC and layers below.

void MacInitialize(struct TMacNotifications *pNotifications, uint8_t u8Band)

Parameters:

*pNotifications Structure with callbacks used to notify MAC specific events (if NULL the layer is
deinitialized)

u8Band Frequency band. This has to match the hardware. Use one of the constants:
BAND_CENELEC_A
BAND_CENELEC_B
BAND_FCC
BAND_ARIB.

B.1.2 Event handler function

The MacEventHandler function should be called periodically, with a high frequency, in order to allow the stack to
run. This function will call also the event handler of the layers below.

void MacEventHandler(void)

B.2 MAC Primitives

B.2.1 Mac Data Primitives

DATA PRIMITIVE Atmel Function

MCPS-DATA.request void MacMcpsDataRequest(struct TMcpsDataRequest *pParameters)

MCPS-DATA.confirm void (*MacMcpsDataConfirm)(struct TMcpsDataConfirm *Parameters)

MCPS-DATA.indication void (*MacMcpsDataIndication)(struct TMcpsDataIndication *pDataIndication)

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 55 5
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
5
B.2.2 Mac Management Primitives

MANAGEMENT PRIMITIVE Atmel Function

MLME-GET.request void MacMlmeGetRequest(struct TMlmeGetRequest *pParameters)

MLME-GET.confirm void (*MacMlmeGetConfirm)(struct TMlmeGetConfirm *pParameters)

MLME-SET.request void MacMlmeSetRequest(struct TMlmeSetRequest *pParameters)

MLME-SET.confirm void (*MacMlmeSetConfirm)(struct TMlmeSetConfirm *pParameters)

MLME-RESET.request void MacMlmeResetRequest(struct TMlmeResetRequest *pParameters)

MLME-RESET.confirm void (*MacMlmeResetConfirm)(struct TMlmeResetConfirm *pParameters)

MLME-SCAN.request void MacMlmeScanRequest(struct TMlmeScanRequest *pParameters)

MLME-BEACON-NOTIFY.indication void (*MacMlmeBeaconNotify)(struct TMlmeBeaconNotifyIndication

*pParameters)

MLME-SCAN.confirm typedef void (*MacMlmeScanConfirm)(struct TMlmeScanConfirm

*pParameters)

MLME-START.request void MacMlmeStartRequest(struct TMlmeStartRequest *pParameters)

MLME-START.confirm void (*MacMlmeStartConfirm)(struct TMlmeStartConfirm *pParameters)

MLME-COMM-STATUS.indication typedef void (*MacMlmeCommStatusIndication)(struct

TMlmeCommStatusIndication *pParameters)

B.3 MIB Objects Specification and Access

The default endianness of all MIB is little endian, in other case it will be explicitly specified.

B.3.1 MAC_PIB _ACK_WAIT_DURATION (0x00000040)

Duration of acknowledgement period in microseconds.
Access: Read-only.
Value Range: 0-65535.
Default Value: aSymbolTime x (aRIFS + aCIFS) + aAckTime.

B.3.2 MAC_PIB_BSN (0x00000049)

Beacon frame sequence number.
Access: R/W.
Value Range: 0-255.
Default Value: random.

B.3.3 MAC_PIB_DSN (0x0000004C)

Data frame sequence number.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

56 Atmel
5 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
6
 Access: R/W.
Value Range: 0-255.
Default Value: random.

B.3.4 MAC_PIB_MAX_BE (0x00000047)

Maximum value of back-off exponent. It should always be greater than macMinBE.
Access: R/W.
Value Range: 0–20.
Default Value: 8.

B.3.5 MAC_PIB_MAX_CSMA_BACKOFFS (0x0000004E)

Maximum number of back-off attempts.
Access: R/W.
Value Range: 0-255.
Default Value: 50.

B.3.6 MAC_PIB_MAX_FRAME_RETRIES (0x00000059)

Maximum number of retransmission.
Access: R/W.
Value Range: 0-10.
Default Value: 5.

B.3.7 MAC_PIB_MIN_BE (0x0000004F)

Minimum value of back-off exponent.
Access: R/W.
Value Range: 0–20.
Default Value: 3.

B.3.8 MAC_PIB_PAN_ID (0x00000050)

PAN ID of the network.
Access: R/W.
Value Range: 0-65535.
Default Value: 65535.

B.3.9 MAC_PIB_SECURITY_ENABLED (0x0000005D)

Security enabled.
Access: Read-only.
Value Range: 0-1.
Default Value: 1.

B.3.10 MAC_PIB_SHORT_ADDRESS (0x00000053)

Device short address.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 57 5
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
7
 Access: R/W.
Value Range: 0-65535.
Default Value: 65535.

B.3.11 MAC_PIB_PROMISCUOUS_MODE (0x00000051)

Promiscuous mode enabled.
Access: R/W.
Value Range: 0-1.
Default Value: 0.

B.3.12 MAC_PIB_TIMESTAMP_SUPPORTED (0x0000005C)

MAC frame time stamp support enabled.
Access: Read-only.
Value Range: 0-1.
Default Value: 1

B.3.13 MAC_PIB_KEY_TABLE (0x00000071)

This attribute holds GMK keys required for MAC layer ciphering. The attribute can hold two 16-byte keys. The
row index corresponds to the key identifier value. For security reasons, the key entries cannot be read, only
written or deleted. This table is stored across power fail.
Access: Write only.
Number of entries: 2.
Entry format:

struct TMacSecurityKey

bool m_bValid;

uint8_t m_au8Key[MAC_SECURITY_KEY_LENGTH]; // 16 bytes

};

Default Value: empty table.

Add Entry: Call Set function with index [0-1], length = 16, value = 16-byte key value. Valid flag automatically set.
Delete Entry: Call Set function with index [0-1], length = 0: Key value and Valid flag automatically cleared.

B.3.14 MAC_PIB_FRAME_COUNTER (0x00000077)

The outgoing frame counter for this device. This value is stored across power fail.
Access: R/W.
Value Range: 0-4294967295.
Default Value: 0.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

58 Atmel
5 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
8
B.3.15 MAC_PIB_HIGH_PRIORITY_WINDOW_SIZE (0x00000100)
The high priority contention window size, in number of slots.
Access: R/W.
Value Range: 1-7:
Default Value: 7.

B.3.16 MAC_PIB_TX_DATA_PACKET_COUNT (0x00000101)

Statistic counter of successfully transmitted unicast MSDUs.
Access: R/W.
Value Range: 0-4294967295.
Default Value: 0.

B.3.17 MAC_PIB_RX_DATA_PACKET_COUNT (0x00000102)

Statistic counter of successfully received unicast MSDUs.
Access: R/W.
Value Range: 0-4294967295.
Default Value: 0.

B.3.18 MAC_PIB_TX_CMD_PACKET_COUNT (0x00000103)

Statistic counter of successfully transmitted command packets.
Access: R/W.
Value Range: 0-4294967295.
Default Value: 0.

B.3.19 MAC_PIB_RX_CMD_PACKET_COUNT (0x00000104)

Statistic counter of successfully received command packets.
Access: R/W.
Value Range: 0-4294967295.
Default Value: 0.

B.3.20 MAC_PIB_CSMA_FAIL_COUNT (0x00000105)

Counts the number of times the CSMA back-offs reach macMaxCSMABackoffs.
Access: R/W.
Value Range: 0-4294967295.
Default Value: 0.

B.3.21 MAC_PIB_CSMA_NO_ACK_COUNT (0x00000106)

Counts the number of times an ACK is not received while transmitting a unicast data frame (The loss of ACK is
attributed to collisions).
Access: R/W.
Value Range: 0-4294967295.
Default Value: 0.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 59 5
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
9
B.3.22 MAC_PIB_RX_DATA_BROADCAST_COUNT (0x00000107)
Statistic counter of successfully received broadcast frames.
Access: R/W.
Value Range: 0-4294967295.
Default Value: 0.

B.3.23 MAC_PIB_TX_DATA_BROADCAST_COUNT (0x00000108)

Statistic counter of the number of broadcast frames sent.
Access: R/W.
Value Range: 0-4294967295.
Default Value: 0.

B.3.24 MAC_PIB_BAD_CRC_COUNT (0x00000109)

Statistic counter of the number of frames received with bad CRC.
Access: R/W.
Value Range: 0-4294967295.
Default Value: 0.

B.3.25 MAC_PIB_NEIGHBOUR_TABLE (0x0000010A)

The neighbour table.
Access: R/W.
Number of entries: 75.
Entry format:

struct TNeighbourEntry {

TShortAddress m_nShortAddress; // 2 bytes

struct TPhyToneMap m_ToneMap; // 3 bytes (only first used in Cenelec)

uint8_t m_nModulationType : 3;

uint8_t m_nTxGain : 4;

uint8_t m_nTxRes : 1;

struct TMacTxCoef m_TxCoef; // 6 bytes

uint8_t m_nModulationScheme : 1;

uint8_t m_nPhaseDifferential : 3;

uint8_t m_u8Lqi;

uint16_t m_u16TmrValidTime; // TMResponse parameters validity time

uint16_t m_u16NeighbourValidTime; // Entry validity time

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

60 Atmel
6 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
 };

Short Modulation Not Phase Modulation Tmr Neighbour

Tone Map TxRes TxGain TxCoef Lqi
Address Type Used Differential Scheme ValidTime ValidTime

2 bytes 3 bytes 1 byte 6 bytes 1 byte 1 byte 2 bytes 2 bytes

1 bit 4 bits 3 bits 4 bits 3 bits 1 bit

Default Value: empty table.

Get Entry: Call Get function with index [0-74], returned value will have the format described above.
Add Entry: Call Set function with index [0-74], index will be ignored and new entry will be placed on index 0,
length = 18 (see Entry format above), value = Entry of format described above.

B.3.26 MAC_PIB_FREQ_NOTCHING (0x0000010B)

S-FSK 63 and 74 kHz frequency notching. This attribute is ignored, use MAC_PIB_TONE_MASK instead.
Access: R/W.
Value Range: 0-1.
Default Value: 0.

B.3.27 MAC_PIB_CSMA_FAIRNESS_LIMIT (0x0000010C)

Channel access fairness limit. Specifies after how many failed back-off attempts, back-off exponent is set to
minBE. Should be at least (2×(macMaxBE-macMinBE)).
Access: R/W.
Value Range: 0-255.
Default Value: 15.

B.3.28 MAC_PIB_TMR_TTL (0x0000010D)

Maximum time to live of tone map parameters entry in the neighbor table, in minutes.
Access: R/W.
Value Range: 0-255.
Default Value: 2.

B.3.29 MAC_PIB_NEIGHBOUR_TABLE_ENTRY_TTL (0x0000010E)

Maximum time to live for an entry in the neighbor table, in minutes.
Access: R/W.
Value Range: 0-255.
Default Value: 255.

B.3.30 MAC_PIB_RC_COORD (0x0000010F)

Route cost to coordinator to be used in the beacon payload as RC_COORD.
Access: R/W.
Value Range: 0-65535.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 61 6
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
1
 Default Value: 65535.

B.3.31 MAC_PIB_TONE_MASK (0x00000110)

Defines the tone mask to use during symbol formation. It is represented using one bit per carrier. Holds up to 72
carriers (for FCC) so its size is 9 bytes. Bits set indicate carrier used, bits cleared indicate carrier masked.
Depending on band used, a different number of bits are taken into account.
This PIB is a 9 byte array coded little endian (LSB first). In Cenelec-A band, the carriers are placed like this:
Byte 0 Byte 1 Byte 2 Byte 3 Byte 4 Byte 5 Byte 6 Byte 7 Byte 8
b7 b6 b5 b4 b3 b2 b1 b0 b7 b6 b5 b4 b3 b2 b1 b0 … … b7 b6 b5 b4 b3 b2 b1 b0
Carrier 30
Carrier 29
Carrier 28
Carrier 27
Carrier 26
Carrier 25
Carrier 24
Carrier 23
Carrier 38
Carrier 37
Carrier 36
Carrier 35
Carrier 34
Carrier 33
Carrier 32
Carrier 31

Carrier 58
Carrier 57
Carrier 56
Carrier 55
Not Used
Not Used
Not Used
Not Used

Not Used

Not Used

Not Used

Not Used
…

…
Access: R/W.
Value Range: 0x00-0xFF for each of 9 bytes.
Default Value: All bytes set to 0xFF (All carriers are enabled).

B.3.32 MAC_PIB_BEACON_RANDOMIZATION_WINDOW_LENGTH (0x00000111)

Duration time in seconds for beacon randomization.
Access: R/W.
Value Range: 1-254.
Default Value: 12.

B.3.33 MAC_PIB_A (0x00000112)

This parameter controls the adaptive CW linear decrease.
Access: R/W.
Value Range: 3-20.
Default Value: 8.

B.3.34 MAC_PIB_K (0x00000113)

Rate adaptation factor for channel access fairness limit.
Access: R/W.
Value Range: 1-macCSMAFairnessLimit.
Default Value: 5.

B.3.35 MAC_PIB_MIN_CW_ATTEMPTS (0x00000114)

Number of consecutive attempts while using minimum CW.
Access: R/W.
Value Range: 0-255
Default Value: 10.

B.3.36 MAC_PIB_CENELEC_LEGACY_MODE (0x00000115)

This read only attribute indicates the capability of the node. This means that, when set to 1, the following
configuration is used:

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

62 Atmel
6 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
2
  Full block interleaving.
 Interleaver parameters ni and nj are swapped when I(i,j) = 0.
Access: Read-only.
Value Range: 0-1.
Default Value: 1.

B.3.37 MAC_PIB_FCC_LEGACY_MODE (0x00000116)

This read only attribute indicates the capability of the device. This means that, when set to 1, the following
configuration is used:
 Coherent FCH modulation.
 Full block interleaving.
 Interleaver parameters ni and nj are swapped when I(i,j) = 0.
 Two RS blocks capability.
Access: Read-only.
Value Range: 0-1.
Default Value: 1.

B.3.38 MAC_PIB_MANUF_DEVICE_TABLE (0x80000000)

The device table.
Access: Read only.
Number of entries: 128.
Entry format:
- 2 byte - PAN ID
- 2 byte - short address or 0xFFFF if no short address is used
- 8 byte - extended address. (little endian encoding)
- 4 byte - frame counter
Default Value: empty table.
Get Entry: Call Get function with index [0-127], returned value will have the format described above.

B.3.39 MAC_PIB_MANUF_EXTENDED_ADDRESS (0x80000001)

Extended address of the node. Format EUI64. (little endian encoding)
Access: R/W.
Value Range: 0-255 for each of 8 bytes.
Default value: All bytes set to 0.

B.3.40 MAC_PIB_MANUF_NEIGHBOUR_TABLE_ELEMENT (0x80000002)

This object has the same content as the neighbor table, but the index is the short address of the node.
Access: Read-only.

B.3.41 MAC_PIB_MANUF_BAND_INFORMATION (0x80000003)

This read only object returns information about the band:

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 63 6
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
3
 Entry format:

struct TBandInformation {

uint8_t m_u8Band;

uint8_t m_u8Tones;

uint8_t m_u8Carriers;

uint8_t m_u8TonesInCarrier;

uint8_t m_u8FlBand;

uint16_t m_u16FlMax;

uint8_t m_u8MaxRsBlocks;

uint8_t m_u8TxCoefBits;

};

 1 byte – band
 1 byte – number of tones
 1 byte – number of carriers
 1 byte – tones in a carrier
 1 byte – FLBand
 1 byte – reserved
 2 byte – FLmax
 1 byte – maximal number of RS blocks
 1 byte – number of bits in one entry of the TXCOEF table
Access: Read-only.

B.3.42 MAC_PIB_MANUF_COORD_SHORT_ADDRESS (0x08000004)

Short address of the coordinator.
Access: Read-only.
Value Range: 0-65535.
Default Value: 0.

B.3.43 MAC_PIB_MANUF_MAX_MAC_PAYLOAD_SIZE (0x08000005)

Maximal length of an MSDU.
Access: Read-only.
Value Range: 0-65535.
Default value: 400.

B.3.44 MAC_PIB_MANUF_SECURITY_RESET (0x08000006)

Resets the device table, should be used after a new key was activated.
Access: Write Only.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

64 Atmel
6 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
4
B.3.45 MAC_PIB_MANUF_FORCED_MOD_SCHEME (0x08000007)
Forces Payload Modulation scheme to Differential or Coherent mode for every transmitted frame, instead of
using Neighbour Table info.
Access: R/W.
Value Range: 0-2.
0 – Use Neighbour table info.
1 – Force Differential scheme.
2 – Force Coherent scheme.
Default value: 0.

B.3.46 MAC_PIB_MANUF_FORCED_MOD_TYPE (0x08000008)

Forces Payload Modulation type to any of the available modes for every transmitted frame, instead of using
Neighbour Table info.
Access: R/W.
Value Range: 0-4.
0 – Use Neighbour table info.
1 – Force ROBO.
2 – Force BPSK.
3 – Force QPSK.
4 – Force 8PSK.
Default value: 0.

B.3.47 MAC_PIB_MANUF_FORCED_TONEMAP (0x08000009)

Forces Payload Tone Map to any value for every transmitted frame, instead of using Neighbour Table info.
Access: R/W.
Entry format:

struct TPhyToneMap {

uint8_t m_au8Tm[3];

};

A value of “all zeros” means Tone Map is not forced and Neighbour Table info will be used.
Default value: [0x00, 0x00, 0x00].
Note: For Cenelec Band only first element of the array is used, as Tone Map length is 6 bits.

B.3.48 MAC_PIB_MANUF_FORCED_MOD_SCHEME_ON_TMRESPONSE (0x0800000A)

Forces Modulation scheme bit to Differential or Coherent mode on Tone Map Response message, instead of
using internal G3 stack info.
Access: R/W.
Value Range: 0-2.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 65 6
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
5
 0 – Use internal G3 stack info.
1 – Force Differential scheme.
2 – Force Coherent scheme.
Default value: 0.

B.3.49 MAC_PIB_MANUF_FORCED_MOD_TYPE_ON_TMRESPONSE (0x0800000B)

Forces Modulation type bits to any of the available modes on Tone Map Response message, instead of using
internal G3 stack info.
Access: R/W.
Value Range: 0-4.
0 – Use internal G3 stack info.
1 – Force ROBO.
2 – Force BPSK.
3 – Force QPSK.
4 – Force 8PSK.
Default value: 0.

B.3.50 MAC_PIB_MANUF_FORCED_TONEMAP_ON_TMRESPONSE (0x0800000C)

Forces Tone Map field to any value on Tone Map Response message, instead of using internal G3 stack info.
Access: R/W.
Entry format:

struct TPhyToneMap {

uint8_t m_au8Tm[3];

};

A value of “all zeros” means Tone Map field is not forced and internal G3 stack info will be used.
Default value: [0x00, 0x00, 0x00].
Note: For Cenelec Band only first element of the array is used, as Tone Map length is 6 bits.

B.3.51 MAC_PIB_MANUF_LAST_RX_MOD_SCHEME (0x0800000D)

Gets Modulation scheme of the last received data frame.
Access: Read only.
Value Range: 0-1.
0 – Differential scheme.
1 – Coherent scheme.
Default value: 0.

B.3.52 MAC_PIB_MANUF_LAST_RX_MOD_TYPE (0x0800000E)

Gets Modulation type of the last received data frame.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

66 Atmel
6 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
6
 Access: Read only.
Value Range: 0-3.
0 – ROBO.
1 – BPSK.
2 – QPSK.
3 – 8PSK.
Default value: 0.

B.3.53 MAC_PIB_MANUF_LBP_FRAME_RECEIVED (0x0800000F)

Flag indicating whether LBP frames are being received since last time MIB was set to 0. This PIB is intended to
be used for collision avoidance during bootstrap phase.
Access: R/W.
Value Range: 0-1.
Default value: 0.

B.3.54 MAC_PIB_MANUF_LNG_FRAME_RECEIVED (0x08000010)

Flag indicating whether LOADng frames are being received since last time MIB was set to 0. This PIB is intended
to be used for collision avoidance during bootstrap phase.
Access: R/W.
Value Range: 0-1.
Default value: 0.

B.3.55 MAC_PIB_MANUF_BCN_FRAME_RECEIVED (0x08000011)

Flag indicating whether Beacon frames are being received since last time MIB was set to 0. This PIB is intended
to be used for collision avoidance during bootstrap phase.
Access: R/W.
Value Range: 0-1.
Default value: 0.

B.3.56 MAC_PIB_MANUF_NEIGHBOUR_TABLE_COUNT (0x08000012)

Gets number of valid elements in the Neighbour Table.
Access: Read only.
Value Range: 0-65535.
Default value: 0.

B.3.57 MAC_PIB_MANUF_PHY_PARAM (0x08000020)

Gives access to some PHY layer parameters and statistics. It is treated as a table, where index determines which
parameter to access. Available parameters and their corresponding indexes are the following:

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 67 6
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
7
 PHY_PARAM_VERSION, index 0x010C.
Description: Retrieves PHY layer version number. 32 bits.
Access: Read only.
Default Value: N/A.
PHY_PARAM_TX_TOTAL, index 0x0110.
Description: Correctly transmitted frame count. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_TX_TOTAL_BYTES, index 0x0114.
Description: Transmitted bytes count. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_TX_TOTAL_ERRORS, index 0x0118.
Description: Transmission errors count. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_BAD_BUSY_TX, index 0x011C.
Description: Transmission failure due to already in transmission. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_TX_BAD_BUSY_CHANNEL, index 0x0120.
Description: Transmission failure due to busy channel. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_TX_BAD_LEN, index 0x0124.
Description: Bad length in message (too short - too long). 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_TX_BAD_FORMAT, index 0x0128.
Description: Message to transmit in bad format. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_TX_TIMEOUT, index 0x012C.
Description: Timeout error in transmission. 32 bits.
Access: Read only.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

68 Atmel
6 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
8
 Default Value: 0.
PHY_PARAM_RX_TOTAL, index 0x0130.
Description: Correctly received messages count. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_RX_TOTAL_BYTES, index 0x0134.
Description: Received bytes count. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_RX_RS_ERRORS, index 0x0138.
Description: Reception RS errors count. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_RX_EXCEPTIONS, index 0x013C.
Description: Reception Exceptions count. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_RX_BAD_LEN, index 0x0140.
Description: Bad length in message (too short - too long). 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_RX_BAD_CRC_FCH, index 0x0144.
Description: Bad CRC in received FCH. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_RX_FALSE_POSITIVE, index 0x0148.
Description: FCH CRC correct but invalid protocol. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_RX_BAD_FORMAT, index 0x014C.
Description: Received message in bad format. 32 bits.
Access: Read only.
Default Value: 0.
PHY_PARAM_ENABLE_AUTO_NOISE_CAPTURE, index 0x0166.
Description: Noise autodetection and adaptation. 8 bits.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 69 6
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
9
 Access: R/W.
Default Value: 1.
PHY_PARAM_TIME_BETWEEN_NOISE_CAPTURES, index 0x0158.
Description: Time between noise captures (in ms). 32 bits.
Access: R/W.
Default Value: 60000.
PHY_PARAM_CFG_AUTODETECT_BRANCH, index 0x0161.
Description: Automatic Impedance detection by PHY layer. 8 bits treated as Boolean.
Access: R/W.
Default Value: 1.
PHY_PARAM_CFG_IMPEDANCE, index 0x0162.
Description: Impedance value to set in case Autodetect is disabled. 8 bits.
Access: R/W.
Default Value: 0 (Hi impedance).
PHY_PARAM_RRC_NOTCH_ACTIVE, index 0x0163.
Description: Indicate if notch filter is active or not. 8 bits.
Access: R/W.
Default Value: 0.
PHY_PARAM_RRC_NOTCH_INDEX, index 0x0164.
Description: Index of the notch filter. 8 bits.
Access: R/W.
Default Value: 0.
PHY_PARAM_DELAY_NOISE_CAPTURE_AFTER_RX, index 0x0167.
Description: Next noise capture is delayed if a frame is correctly received. 8 bits.
Access: R/W.
Default Value: 1.
PHY_PARAM_PLC_DISABLE, index 0x016A.
Description: Disable PLC Tx/Rx. 8 bits.
Access: R/W.
Default Value: 0.
PHY_PARAM_NOISE_PEAK_POWER, index 0x016B.
Description: Returns Detected Noise Peak Power on last Noise Capture, in case a Peak was detected
(PHY_PARAM_RRC_NOTCH_ACTIVE == 1). If no Peak was detected, it returns the Noise average in
band measured on last Noise Capture. 8 bits.
Access: R/W.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

70 Atmel
7 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
 Default Value: 0.
PHY_PARAM_LAST_MSG_LQI, index 0x016C.
Description: Returns LQI value calculated for last received frame. 8 bits.
Access: R/W.
Default Value: 0.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 71 7
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
1
B.4 ADP SAP
All this functions and the structures used are defined in the file AdpApi.h.

B.4.1 Initialization function

Use this function to initialize the ADP layer. The ADP layer should be initialized before doing any other operation
of ADP Layer.

void AdpInitialize(struct TAdpNotifications *pNotifications, enum TAdpBand band);

Parameters:

pNotifications Structure with callbacks used to notify ADP specific events (if NULL the layer is
deinitialized)

band Working band (should be inline with the hardware)

struct TAdpNotifications {

AdpDataConfirm fnctAdpDataConfirm;

AdpDataIndication fnctAdpDataIndication;

AdpDiscoveryConfirm fnctAdpDiscoveryConfirm;

AdpDiscoveryIndication fnctAdpDiscoveryIndication;

AdpNetworkStartConfirm fnctAdpNetworkStartConfirm;

AdpNetworkJoinConfirm fnctAdpNetworkJoinConfirm;

AdpNetworkLeaveIndication fnctAdpNetworkLeaveIndication;

AdpNetworkLeaveConfirm fnctAdpNetworkLeaveConfirm;

AdpResetConfirm fnctAdpResetConfirm;

AdpSetConfirm fnctAdpSetConfirm;

AdpMacSetConfirm fnctAdpMacSetConfirm;

AdpGetConfirm fnctAdpGetConfirm;

AdpMacGetConfirm fnctAdpMacGetConfirm;

AdpLbpConfirm fnctAdpLbpConfirm;

AdpLbpIndication fnctAdpLbpIndication;

AdpRouteDiscoveryConfirm fnctAdpRouteDiscoveryConfirm;

AdpPathDiscoveryConfirm fnctAdpPathDiscoveryConfirm;

AdpNetworkStatusIndication fnctAdpNetworkStatusIndication;

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

72 Atmel
7 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
2
 AdpBufferIndication fnctAdpBufferIndication;

AdpPREQIndication fnctAdpPREQIndication;

AdpUpdNonVolatileDataIndication fnctAdpUpdNonVolatileDataIndication;

AdpBrokenRouteIndication fnctAdpBrokenRouteIndication;

};

enum TAdpBand {

ADP_BAND_CENELEC_A = 0, ADP_BAND_CENELEC_B = 1, ADP_BAND_FCC = 2, ADP_BAND_ARIB =

3

};

B.4.2 Event handler function

Event handler of the ADP layer. It should be called from the main loop. This function calls the MacEventHandler.

bool AdpEventHandler(void);

B.5 ADP Data Primitives

The ADPD is used to transport the NSDU to other devices on the network. Atmel implementation support all
standard data primitives specified in G3-PLC Spec. The following chapters enumerate the ADPD functions.

B.5.1 ADPD-DATA.request
The ADPD-DATA.request primitive requests the transfer of an application PDU (i.e.: IPv6 packet) to another
device or multiple devices.

void AdpDataRequest(uint16_t u16NsduLength, const uint8_t *pNsdu, uint8_t u8NsduHandle, bool

bDiscoverRoute, uint8_t u8QualityOfService);

Parameters:

u16NsduLength The size of the NSDU, in bytes. [Valid range: 0 – 1280].

pNsdu The NSDU to send.

u8NsduHandle The handle of the NSDU to transmit. This parameter is used to identify in the
AdpDataConfirm primitive which request it is concerned with. It can be randomly
chosen by the application layer.

bDiscoverRoute If TRUE, a route discovery procedure will be performed prior to sending the frame
if a route to the destination is not available in the routing table. If FALSE, no route
discovery is performed.

u8QualityOfService The requested quality of service (QoS) of the frame to send. Allowed values are:
[0x00 = normal priority; 0x01 = high priority].

When the execution of the DataRequest is finished the callback AdpDataConfirm is called to inform the user
about the status of the operation.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 73 7
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
3
B.5.2 ADPD-DATA.confirm
The ADPD-DATA.confirm primitive reports the result of a previous ADPD-DATA.request primitive.

typedef void (*AdpDataConfirm)(struct TAdpDataConfirm *pDataConfirm);

The result is reported into the following structure:

struct TAdpDataConfirm {
uint8_t m_u8Status;
uint8_t m_u8NsduHandle;
};

Fields of the structure:

u8Status The status code of a previous ADPD-DATA.request identified by its NsduHandle.

u8NsduHandle The handle of the NSDU confirmed by this primitive.

B.5.3 ADPD-DATA.indication
The ADPD-DATA.indication primitive is used to transfer received data from the adaptation sublayer to the upper
layer.
When user data is received by the modem, the callback AdpDataIndication is called:

typedef void (*AdpDataIndication)(struct TAdpDataIndication *pDataIndication);

The information is reported into the following structure:

struct TAdpDataIndication {

uint16_t m_u16NsduLength;

const uint8_t *m_pNsdu;

uint8_t m_u8LinkQualityIndicator;

};

Fields of the structure:

u8Status The size of the NSDU, in bytes.

u8NsduHandle The received NSDU.

m_u8LinkQualityIndicator The value of the link quality during the receipt of the frame.

B.6 ADP Management Service Primitives

The ADPM allows the transport of command frames used for network maintenance. The following chapters
enumerate the ADPM functions.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

74 Atmel
7 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
4
B.6.1 ADPM-DISCOVERY.request
The ADPM-DISCOVERY.request primitive allows the upper layer to request the ADPM to scan for networks
operating in its POS.

void AdpDiscoveryRequest(uint8_t u8Duration);

Parameter:

u8Duration The number of seconds the scan shall last.

B.6.2 ADPM-DISCOVERY.indication
The ADPM-Discovery.indication primitive is generated by the ADP layer upon Beacon reception. This primitive
will be generated as many times as number of Beacons are received, thus it is an Application task to decide
which PAN to join, depending on the info received on each of the indications.

typedef void (*AdpDiscoveryIndication)(struct TAdpPanDescriptor *pPanDescriptor);

The information is reported into the following structure:

struct TAdpPanDescriptor {

uint16_t m_u16PanId;

uint8_t m_u8LinkQuality;

uint16_t m_u16LbaAddress;

uint16_t m_u16RcCoord;

};

Fields of the structure:

u16PanId PANId where Beacon comes from.

u8LinkQuality Quality of Beacon reception.

m_ u16LbaAddress Short address of device sending the Beacon.

m_u16RcCoord Route Cost to Coordinator reported by Device sending the Beacon.

B.6.3 ADPM-DISCOVERY.confirm
The ADPM-DISCOVERY.confirm primitive is generated by the ADP layer upon completion of a previous ADPM-
DISCOVERY.request.

typedef void (*AdpDiscoveryConfirm)(uint8_t m_u8Status);

Parameter:

m_u8Status Result of the associated DISCOVERY.request.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 75 7
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
5
B.6.4 ADPM-NETWORK-START.request
The ADPM-NETWORK-START.request primitive allows the upper layer to request the starting of a new network.
It shall only be invoked by a device designated as the PAN coordinator during the factory process.

void AdpNetworkStartRequest(uint16_t u16PanId);

Parameter:

u16PanId The PANId of the network to create; determined at the application level [Valid
range: 0x0000 - 0xFFFF].

B.6.5 ADPM-NETWORK-START.confirm
The ADPM-NETWORK-START.confirm primitive reports the status of an ADPM-NETWORK-START.request

typedef void (*AdpNetworkStartConfirm)(struct TAdpNetworkStartConfirm *pNetworkStartConfirm);

Structure:

struct TAdpNetworkStartConfirm {
uint8_t m_u8Status;
};

Parameter:

m_u8Status The status of the scan request.

B.6.6 ADPM-NETWORK-JOIN.request
The ADPM-NETWORK-JOIN.request primitive allows the upper layer to join an existing network.

void AdpNetworkJoinRequest(uint16_t u16PanId, uint16_t u16LbaAddress);

Parameters:

u16PanId The 16-bit PAN identifier of the network to join.

u16LbaAddress The 16-bit short address of the device acting as a LoWPAN bootstrap agent as
defined in Annex E of G3 Spec.

B.6.7 ADPM-NETWORK-JOIN.confirm
The ADPM-NETWORK-JOIN.confirm primitive is generated by the ADP layer to indicate the completion status
of a previous ADPM-NETWORK-JOIN.request.

typedef void (*AdpNetworkJoinConfirm)(struct TAdpNetworkJoinConfirm *pNetworkJoinConfirm);

Structure:

struct TAdpNetworkJoinConfirm {
uint8_t m_u8Status;
uint16_t m_u16NetworkAddress;

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

76 Atmel
7 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
6
 uint16_t m_u16PanId;
};

Fields:

m_u8Status The status of the Join request.

m_u16NetworkAddress The 16-bit network address that was allocated to the device. If the allocation
fails, this address is equal to 0xFFFF.

m_u16PanId The 16-bit address of the PAN of which the device is now a member.

B.6.8 ADPM-NETWORK-JOIN.indication
Not implemented.

B.6.9 ADPM-NETWORK-LEAVE.request
The ADPM-NETWORK-LEAVE.request primitive allows a non-coordinator device to remove itself from the
network.

void AdpNetworkLeaveRequest(void);

B.6.10 ADPM-NETWORK-LEAVE.indication
ADPM-NETWORK-LEAVE.indication primitive is generated by the ADP layer of a non-coordinator device to
inform the upper layer that it has been unregistered from the network by the coordinator.

typedef void (*AdpNetworkLeaveIndication)(void);

B.6.11 ADPM-NETWORK-LEAVE.confirm
The ADPM-NETWORK-LEAVE.confirm primitive allows the upper layer to be informed of the status of its
previous ADPM-NETWORK-LEAVE.request.
m_u8Status The status of the request.

typedef void (*AdpNetworkLeaveConfirm)(struct TAdpNetworkLeaveConfirm *pLeaveConfirm);

Structure:

struct TAdpNetworkLeaveConfirm {
uint8_t m_u8Status;
};

Field:

m_u8Status The status of the request.

B.6.12 ADPM-RESET.request
The ADPM-RESET.request primitive performs a reset of the adaptation sublayer and allows the resetting of the
MIB attributes.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 77 7
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
7
 void AdpResetRequest(void);

B.6.13 ADPM-RESET.confirm
The ADPM-RESET.confirm primitive allows the upper layer to be notified of the completion of an ADPM-
RESET.request primitive.

typedef void (*AdpResetConfirm)(struct TAdpResetConfirm *pResetConfirm);

Structure:

struct TAdpResetConfirm {
uint8_t m_u8Status;
};

Field:

m_u8Status The status of the request.

B.6.14 ADPM-GET.request
The ADPM-GET.request primitive allows the upper layer to get the value of an attribute from the ADP information
base.

void AdpGetRequest(uint32_t u32AttributeId, uint16_t u16AttributeIndex);

Parameters:

u32AttributeId The identifier of the ADP IB attribute to read.

u16AttributeIndex The index within the table of the specified IB attribute to read. This parameter
is valid only for IB attributes that are tables.

A synchronous implementation of this function is also available, thus no confirm is generated, instead a pointer
to confirm structure has to be provided.

void AdpGetRequestSync (uint32_t u32AttributeId, uint16_t u16AttributeIndex, struct TAdpGetConfirm

*pGetConfirm);

Parameters:

u32AttributeId The identifier of the ADP IB attribute to read.

u16AttributeIndex The index within the table of the specified IB attribute to read. This parameter
is valid only for IB attributes that are tables.

pGetConfirm Pointer to confirm structure to get the result. See structure definition in Confirm
primitive definition below.

B.6.15 ADPM-GET.confirm
The ADPM-GET.confirm primitive allows the upper layer to be informed of the status of a previously issued
ADPM-GET.request primitive.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

78 Atmel
7 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
8
 typedef void (*AdpGetConfirm)(struct TAdpGetConfirm *pGetConfirm);

Structure:

struct TAdpGetConfirm {
uint8_t m_u8Status;
uint32_t m_u32AttributeId;
uint16_t m_u16AttributeIndex;
uint8_t m_u8AttributeLength;
uint8_t m_au8AttributeValue[64];
};

Fields:

m_u8Status The status of the request.

m_u32AttributeId The identifier of the IB attribute read.

m_u16AttributeIndex The index within the table of the specified IB attribute to read. This parameter
is valid only for IB attributes that are tables.

m_u8AttributeLength The length of the value of the attribute read from the IB.

m_au8AttributeValue The value of the attribute read from the IB.

Possible values of m_u8Status parameter are:

G3_SUCCESS Value 0x00

G3_INVALID_PARAMETER Value 0xA8

G3_INVALID_INDEX Value 0xA7

G3_UNSUPPORTED_ATTRIBUTE Value 0xB1

B.6.16 ADPM-MAC.GET.request
The ADPM-MAC.GET.request primitive allows the upper layer to get the value of an attribute from the MAC
information base. The upper layer cannot access directly the MAC layer while ADP is running.

void AdpMacGetRequest(uint32_t u32AttributeId, uint16_t u16AttributeIndex);

Parameters:

u32AttributeId The identifier of the MAC IB attribute to read.

u16AttributeIndex The index within the table of the specified IB attribute to read. This parameter
is valid only for IB attributes that are tables.

A synchronous implementation of this function is also available, thus no confirm is generated, instead a pointer
to confirm structure has to be provided.

void AdpMacGetRequestSync (uint32_t u32AttributeId, uint16_t u16AttributeIndex, struct TAdpMacGetConfirm

*pGetConfirm);

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 79 7
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
9
 Parameters:

u32AttributeId The identifier of the ADP IB attribute to read.

u16AttributeIndex The index within the table of the specified IB attribute to read. This parameter
is valid only for IB attributes that are tables.

pGetConfirm Pointer to confirm structure to get the result. See structure definition in Confirm
primitive definition below.

B.6.17 ADPM-MAC.GET.confirm
The ADPM-MAC.GET.confirm primitive allows the upper layer to be informed of the status of a previously issued
ADPM-MAC.GET.request primitive.

typedef void (*AdpMacGetConfirm)(struct TAdpMacGetConfirm *pGetConfirm);

Structure:

struct TAdpMacGetConfirm {
uint8_t m_u8Status;
uint32_t m_u32AttributeId;
uint16_t m_u16AttributeIndex;
uint8_t m_u8AttributeLength;
uint8_t m_au8AttributeValue[MAC_PIB_MAX_VALUE_LENGTH];
};

Fields:

m_u8Status The status of the request.

m_u32AttributeId The identifier of the IB attribute read.

m_u16AttributeIndex The index within the table of the specified IB attribute read.

m_u8AttributeLength The length of the value of the attribute read from the IB.

m_au8AttributeValue The value of the attribute read from the IB.

Possible values of m_u8Status parameter are:

MAC_STATUS_SUCCESS Value 0x00

MAC_STATUS_UNSUPPORTED_ATTRIBUTE Value 0xF4

MAC_STATUS_INVALID_INDEX Value 0xF9

MAC_STATUS_UNAVAILABLE_KEY Value 0xF3

MAC_STATUS_DENIED Value 0xE2

MAC_STATUS_INVALID_PARAMETER Value 0xE8

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

80 Atmel
8 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
B.6.18 ADPM-SET.request
The ADPM-SET.request primitive allows the upper layer to set the value of an attribute in the ADP information
base.

void AdpSetRequest(uint32_t u32AttributeId, uint16_t u16AttributeIndex, uint8_t u8AttributeLength, const

uint8_t *pu8AttributeValue);

Parameters:

u32AttributeId The identifier of the ADP IB attribute set.

u16AttributeIndex The index within the table of the specified IB attribute.

u8AttributeLength The length of the value of the attribute to set.

pu8AttributeValue Pointer to the value of the attribute to set.

A synchronous implementation of this function is also available, thus no confirm is generated, instead a pointer
to confirm structure has to be provided.

void AdpSetRequestSync (uint32_t u32AttributeId, uint16_t u16AttributeIndex, uint8_t u8AttributeLength, const

uint8_t *pu8AttributeValue, struct TAdpSetConfirm *pSetConfirm);

Parameters:

u32AttributeId The identifier of the ADP IB attribute set.

u16AttributeIndex The index within the table of the specified IB attribute.

u8AttributeLength The length of the value of the attribute to set.

pu8AttributeValue Pointer to the value of the attribute to set.

pSetConfirm Pointer to confirm structure to get the result. See structure definition in Confirm
primitive definition below.

B.6.19 ADPM-SET.confirm
The ADPM-SET.confirm primitive allows the upper layer to be informed about a previous ADPM-SET.request
primitive.

typedef void (*AdpSetConfirm)(struct TAdpSetConfirm *pSetConfirm);

Structure:

struct TAdpSetConfirm {
uint8_t m_u8Status;
uint32_t m_u32AttributeId;
uint16_t m_u16AttributeIndex;
};

Fields:

m_u8Status The status of the scan request.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 81 8
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
1
 m_u32AttributeId The identifier of the IB attribute set.

m_u16AttributeIndex The index within the table of the specified IB attribute.

Possible values of m_u8Status parameter are:

G3_SUCCESS Value 0x00

G3_INVALID_PARAMETER Value 0xA8

G3_INVALID_INDEX Value 0xA7

G3_UNSUPPORTED_ATTRIBUTE Value 0xB1

G3_READ_ONLY Value 0xB0

G3_FAILED Value 0xA2

B.6.20 ADPM-MAC.SET.request
The ADPM-MAC.SET.request primitive allows the upper layer to set the value of an attribute in the MAC
information base. The upper layer cannot access directly the MAC layer while ADP is running.

void AdpMacSetRequest(uint32_t u32AttributeId, uint16_t u16AttributeIndex, uint8_t u8AttributeLength, const

uint8_t *pu8AttributeValue);

Parameters:

u32AttributeId The identifier of the ADP IB attribute set.

u16AttributeIndex The index within the table of the specified IB attribute.

u8AttributeLength The length of the value of the attribute to set.

pu8AttributeValue The value of the attribute to set.

A synchronous implementation of this function is also available, thus no confirm is generated, instead a pointer
to confirm structure has to be provided.

void AdpMacSetRequestSync (uint32_t u32AttributeId, uint16_t u16AttributeIndex, uint8_t u8AttributeLength,

const uint8_t *pu8AttributeValue, struct TAdpMacSetConfirm*pSetConfirm);

Parameters:

u32AttributeId The identifier of the ADP IB attribute set.

u16AttributeIndex The index within the table of the specified IB attribute.

u8AttributeLength The length of the value of the attribute to set.

pu8AttributeValue Pointer to the value of the attribute to set.

pSetConfirm Pointer to confirm structure to get the result. See structure definition in Confirm
primitive definition below.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

82 Atmel
8 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
2
B.6.21 ADPM-MAC.SET.confirm
The ADPM-MAC.SET.confirm primitive allows the upper layer to be informed about a previous ADPM-
MAC.SET.request primitive.

typedef void (*AdpMacSetConfirm)(struct TAdpMacSetConfirm *pSetConfirm);

Structure:

struct TAdpMacSetConfirm {
uint8_t m_u8Status;
uint32_t m_u32AttributeId;
uint16_t m_u16AttributeIndex;
};

Fields:

m_u8Status The status of the request.

m_u32AttributeId The identifier of the IB attribute set.

m_u16AttributeIndex The index within the table of the specified IB attribute.

Possible values of m_u8Status parameter are:

MAC_STATUS_SUCCESS Value 0x00

MAC_STATUS_UNSUPPORTED_ATTRIBUTE Value 0xF4

MAC_STATUS_INVALID_INDEX Value 0xF9

MAC_STATUS_READ_ONLY Value 0xFB

MAC_STATUS_INVALID_PARAMETER Value 0xE8

B.6.22 ADPM-NETWORK-STATUS.indication
The ADPM-NETWORK-STATUS.indication primitive allows the next higher layer of a PAN coordinator or a
coordinator to be notified when a particular event occurs on the PAN.

typedef void (*AdpNetworkStatusIndication)(struct TAdpNetworkStatusIndication *pNetworkStatusIndication);

Structure:

struct TAdpNetworkStatusIndication {
uint16_t m_u16PanId;
struct TAdpAddress m_SrcDeviceAddress;
struct TAdpAddress m_DstDeviceAddress;
uint8_t m_u8Status;
uint8_t m_u8SecurityLevel;
uint8_t m_u8KeyIndex;
};

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 83 8
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
3
B.6.23 ADPM-BUFFER.indication
The ADPM-BUFFER.indication primitive allows the upper layer to get info about the availability of buffers to hold
a data transmission.

typedef void (*AdpBufferIndication)(struct TAdpBufferIndication *pBufferIndication);

Structure:

struct TAdpBufferIndication {

bool m_bBufferReady;

};

The parameter m_bBufferReady indicates whether there are buffers available or not. This primitive is generated
by ADP layer when a data transmission takes the last available buffer, indicating that there are no more free
buffers, and is also generated when, after no buffers are available, one of them becomes free for a new
transmission.

B.6.24 ADPM-PREQ.indication
The AdpPREQIndication primitive allows the next higher layer to be notified when a PREQ frame is received in
unicast mode with Originator Address equal to Coordinator Address and with Destination Address equal to
Device Address.

typedef void (*AdpPREQIndication)(void);

This primitive is generated by ADP layer in order to indicate upper layer that the device has been addressed by
means of a PREQ frame.

B.6.25 ADPM-UPD_NON_VOLATILE_DATA.indication
The AdpUpdNonVolatileDataIndication primitive allows the next higher layer to be notified when any of the
parameters to be saved/restored before/after a reset changes, this way, upper layer can maintain a record of
these parameters always updated.

typedef void (*AdpUpdNonVolatileDataIndication)(void);

It is up to the upper layer how to handle the change of these parameters, and their storage if necessary.

B.6.26 ADPM-BROKEN_ROUTE.indication
The AdpBrokenRouteIndication primitive is used to indicate the upper layer that a route has just broken due to
no ACK reception for the frame being transmitted, this way, upper layer knows that a Route Repair process will
be triggered to find an alternative route to send such frame, or even cancel the Route Repair mechanism by
using ADP_IB_MANUF_TRIGGER_REPAIR_ON_ROUTE_BROKEN parameter (please note this Repair
cancellation is out of spec).

typedef void (*AdpBrokenRouteIndication)(struct TAdpBrokenRouteIndication *pBrokenRouteIndication);

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

84 Atmel
8 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
4
 Structure:

struct TAdpBrokenRouteIndication{

uint16_t m_u16SrcAddr;

uint16_t m_u16DestAddr;

uint16_t m_u16NextHopAddr;

uint16_t m_u16NsduLength;

uint8_t *m_pNsdu;

};

Field:

m_u16SrcAddr Originator address of the frame which caused the Route break.

m_u16DestAddr Final destination address of the frame which caused the Route break.

m_u16NextHopAddr Next hop in Route to be deleted. In case there is no Route to delete, reported
value is 0xFFFF.

m_u16NsduLength Length of the frame which caused the Route break.

*m_pNsdu Pointer to frame which caused the Route break.

B.6.27 ADPM-ROUTE-DISCOVERY.request
The ADPM-ROUTE-DISCOVERY.request primitive allows the upper layer to initiate a route discovery.

void AdpRouteDiscoveryRequest(uint16_t u16DstAddr, uint8_t u8MaxHops);

Parameters:

u16DstAddr The short unicast destination address of the route discovery.

u8MaxHops This parameter indicates the maximum number of hops allowed for the route
discovery [Valid range: 0x01 - 0x0E].

B.6.28 ADPM-ROUTE-DISCOVERY.confirm
The ADPM-ROUTE-DISCOVERY.confirm primitive allows the upper layer to be informed about a previous
ADPM-ROUTE-DISCOVERY.request primitive.

typedef void (*AdpRouteDiscoveryConfirm)(struct TAdpRouteDiscoveryConfirm *pRouteDiscoveryConfirm);

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 85 8
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
5
 Structure:

struct TAdpRouteDiscoveryConfirm {

uint8_t m_u8Status;

};

Field:

m_u8Status The status of the route discovery.

B.6.29 ADPM-PATH-DISCOVERY.request
The ADPM-PATH-DISCOVERY.request primitive allows the upper layer to initiate a path discovery.

void AdpPathDiscoveryRequest(uint16_t u16DstAddr, uint8_t u8MetricType);

Parameters:

u16DstAddr The short unicast destination address of the path discovery.

u8MetricType The metric type to be used for the path discovery. (Range: 0x00 - 0x0F).

B.6.30 ADPM-PATH-DISCOVERY.confirm
The ADPM-PATH-DISCOVERY.confirm primitive allows the upper layer to be informed of the completion of a
path discovery (ADPM-PATH-DISCOVERY.request).

typedef void (*AdpPathDiscoveryConfirm)(struct TAdpPathDiscoveryConfirm *pPathDiscoveryConfirm);

Structure:

struct TAdpPathDiscoveryConfirm {
uint8_t m_u8Status;
uint16_t m_u16DstAddr;
uint16_t m_u16OrigAddr;
uint8_t m_u8MetricType;
uint8_t m_u8ForwardHopsCount;
uint8_t m_u8ReverseHopsCount;
struct THopDescriptor m_aForwardPath[16];
struct THopDescriptor m_aReversePath[16];
};

Fields:

m_u8Status The status of the path discovery. (status can be INCOMPLETE and the
other parameters contain the discovered path).

m_u16DstAddr The short unicast destination address of the path discovery.

m_u16Originator The originator of the path reply.

m_u8PathMetricType Path metric type.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

86 Atmel
8 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
6
 m_u8HopsCount Number of path hops.

m_pau16HopAddressTable Table with the address of each hop (according to m_u8HopsCount).

m_pau16HopAddressTable Table with msn field of each hop (according to m_u8HopsCount).

m_pau8LinkCostTable Table with cost information related to each hop (according to

m_u8HopsCount).

B.6.31 ADPM-LBP.request
The ADPM-LBP.request primitive allows the upper layer of the client to send the LBP message to the server
modem.

void AdpLbpRequest(const struct TAdpAddress *pDstAddr, uint16_t u16NsduLength, uint8_t *pNsdu, uint8_t
u8NsduHandle, uint8_t u8MaxHops, bool bDiscoveryRoute, uint8_t u8QualityOfService, bool bSecurityEnable);

Parameters:

pDstAddr 16-bit address of LBA or LBD or 64 bit address (extended address of LBD).

u16NsduLength The size of the NSDU, in bytes.

pNsdu The NSDU to send.

u8NsduHandle The handle of the NSDU to transmit. This parameter is used to identify in the
AdpLbpConfirm primitive which request is concerned. It can be randomly
chosen by the application layer.

u8MaxHops The number of times the frame will be repeated by network routers.

bDiscoveryRoute If TRUE, a route discovery procedure will be performed prior to sending the
frame if a route to the destination is not available in the routing table. If FALSE,
no route discovery is performed.

u8QualityOfService The requested quality of service (QoS) of the frame to send. Allowed values
are:
0x00 = standard priority
0x01 = high priority

bSecurityEnable If TRUE, this parameter enables the MAC layer security for sending the frame.

B.6.32 ADPM-LBP.confirm
The ADPM-LBP.confirm primitive reports the result of a previous ADPM-LBP.request primitive.

typedef void (*AdpLbpConfirm)(struct TAdpLbpConfirm *pLbpConfirm);

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 87 8
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
7
 Structure:

struct TAdpLbpConfirm {
uint8_t m_u8Status;
uint8_t m_u8NsduHandle;
};

Fields:

m_u8Status The status code of a previous AdpLbpRequest identified by its NsduHandle.

m_u8NsduHandle The handle of the NSDU confirmed by this primitive.

B.6.33 ADPM-LBP.indication
The ADPM-LBP.indication primitive is used to transfer a received LBP frame from the ADP layer to the upper
layer.

typedef void (*AdpLbpIndication)(struct TAdpLbpIndication *pLbpIndication);

Structure:

struct TAdpLbpIndication {
uint16_t m_u16SrcAddr;
uint16_t m_u16NsduLength;
uint8_t *m_pNsdu;
uint8_t m_u8LinkQualityIndicator;
bool m_bSecurityEnabled;
};

Fields:

m_SrcAddr 16 bits final destination address.

m_u16NsduLength The size of the NSDU, in bytes; Range: 0 – 1280.

m_pNsdu The NSDU received.

m_bSecurityEnabled TRUE if the frame was received with a security level greater or equal to
adpSecurityLevel, FALSE otherwise.

B.7 ADPIB Objects Specification and Access

Atmel G3-PLC stacks supports all the information base (IB) attributes of the Adaptation Sublayer defined in the
G3-PLC spec -Table 9-27. The default endianness of all ADPIB is little endian, in other case it will be explicitly
specified.
In addition, there are some Atmel proprietary IB attributes of the Adaptation Sublayer with extra functionalities.
All of them are described here.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

88 Atmel
8 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
8
B.7.1 ADP_IB_SECURITY_LEVEL = 0x00000000
This attribute indicates the minimum security level to be used for incoming and outgoing adaptation frames.
Messages not respecting this level are dropped. The size of the attribute is 1 byte. Default value: 5 (ENC-MIC-
32).

B.7.2 ADP_IB_PREFIX_TABLE = 0x00000001

This attribute contains the list of prefixes defined on this PAN. It is assumed that the link local IPv6 address exists
independently and is not affected by the prefixes defined in the prefix table.
This attribute is a table of 2 elements.
Each element is encoded as following:
 Byte 0: indicates the prefix length in bits
 Byte 1: indicates the "on-link flag" (0 = not set, 1 = set)
 Byte 2: indicates the "autonomous address-configuration flag" (0 = not set, 1 = set)
 Bytes 3 - 6: indicate the valid lifetime in seconds
 Bytes 7 - 10: indicate the preferred lifetime in seconds
 Bytes 11 - 26 (variable length): indicate the prefix value
If the attribute length is set to 0, the context is deleted.

B.7.3 ADP_IB_BROADCAST_LOG_TABLE_ENTRY_TTL = 0x00000002

This attribute indicates the maximum time to live of an adpBroadcastLogTable entry (in minutes). The size of the
attribute is 2 bytes. The value of the attribute is a 16 bits integer encoded little endian (LSB first). (e.g. 0x0200 =
2 minutes). Default value 2 minutes.

B.7.4 ADP_IB_METRIC_TYPE = 0x00000003

This attribute defines the metric type to be used for routing purposes. The size of the attribute is 1 byte. Default
value: 0x0F.

Possible values for this IB are:

 0x00: TYPE_HOP_COUNT
 0x0E: TYPE_METRIC_CAPACITY
 0x0F: TYPE_METRIC_COMPOSITE

B.7.5 ADP_IB_LOW_LQI_VALUE = 0x00000004

The low LQI value defines the LQI value, used in metric computation, below which a link to a neighbour is
considered as an unreliable link. The size of the attribute is 1 byte. Default value: 0x00.

B.7.6 ADP_IB_HIGH_LQI_VALUE = 0x00000005

The high LQI value defines the LQI value, used in metric computation, above which a link to a neighbour is
considered as a reliable link. The size of the attribute is 1 byte. Default value: 0xFF.

B.7.7 ADP_IB_RREP_WAIT = 0x00000006

An RREP shall be generated after a delay of adpRREPWait seconds after either the arrival of the first RREQ or
the transmission of the latest RREP. The size of the attribute is 1 byte. Default value: 4.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 89 8
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
9
B.7.8 ADP_IB_CONTEXT_INFORMATION_TABLE = 0x00000007
This attribute contains the context information associated to each CID extension field. This attribute is a table of
16 elements. The CID field from ICMPv6 / 6CO message indicates the index in the table.

Each element is encoded as following:

 Bytes 0 - 1: indicate the valid time in minutes. The value is a 16 bits integer encoded little endian (LSB
first).
 Byte 2: indicates the validity of the CID for compression purposes (corresponds to C field from the IC-
MPv6 / 6CO message). A value of 0 means false, 1 means true.
 Byte 3: indicates the context length in bits.
 Bytes 4 - 19 (variable length): indicate the context value.

If the attribute length is set to 0 the context is deleted.

B.7.9 ADP_IB_COORD_SHORT_ADDRESS = 0x00000008

This attribute defines the short address of the coordinator. The size of the attribute is 2 bytes. The value is a 16
bits integer encoded little endian (LSB first). Default value: 0x0000.

B.7.10 ADP_IB_RLC_ENABLED = 0x00000009

This attribute controls the sending of RLCREQ frame by the device. The size of the attribute is 1. The value 0
indicates mechanism is disabled, value 1 mechanism enabled. Default value is 0.

B.7.11 ADP_IB_ADD_REV_LINK_COST = 0x0000000A

This attribute represents an additional cost to take into account a possible asymmetry in the link. The size of the
attribute is 1 byte. Default value 0.

B.7.12 ADP_IB_BROADCAST_LOG_TABLE = 0x0000000B

This attribute contains the broadcast log table. This attribute is Read-only. The table contains 20 elements. Each
element is 5 bytes length:

 Bytes 0 - 1: indicate the source address of the broadcast packet (the address of the broadcast initiator).
The address is encoded little endian (LSB first)
 Byte 2: indicates the sequence number
 Bytes 3 - 4: indicate the remaining time in minutes until when this entry in the broadcast log table is
considered valid (encoded little endian, LSB first)

B.7.13 ADP_IB_ROUTING_TABLE = 0x0000000C

This attribute contains the routing table. The routing table contains 150 elements. Each element has 9 bytes (all
integers are encoded little endian, LSB first):

 Bytes 0 - 1: indicate the destination address

 Bytes 2 - 3: indicate the next hop address
 Bytes 4 - 5: indicate the route cost
 Byte 6, bits 0 - 3: indicate the weak links count
 Byte 6, bits 4 - 7: indicate the hop count
 Bytes 7 - 8: indicate the time this entry is valid in minutes
This attribute can also be written for testing purposes.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

90 Atmel
9 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
B.7.14 ADP_IB_UNICAST_RREQ_GEN_ENABLE = 0x0000000D
This attribute controls the unicast RREQ generation. The length of the attribute is 1 byte. Value 0 indicates the
mechanism is disabled, value 1 the mechanism is enabled. Default value: 1 (enabled).

B.7.15 ADP_IB_GROUP_TABLE = 0x0000000E

This attribute contains the group addresses to which the device belongs. The table size is 16. Note that the "All
nodes address", group 0x8001 is predefined and it doesn't need to be added to this attribute.

The length of each element is 2 bytes, defining the group address encoded little endian (lsb first). If the attribute
element is set with the length 0, the group is deleted.

When reading the element, an extra byte is added which indicates if the entry is valid or not: 0 means invalid, 1
means valid.

B.7.16 ADP_IB_MAX_HOPS = 0x0000000F

This attribute defines the maximum number of hops to be used by the routing algorithm. The length of the attribute
is 1 byte. Default value 8.

B.7.17 ADP_IB_DEVICE_TYPE= 0x00000010

This attribute defines the type of device connected to the modem. The length of the attribute is 1 byte.

 0: PAN device
 1: PAN coordinator
 2: Not defined (Default)

B.7.18 ADP_IB_NET_TRAVERSAL_TIME = 0x00000011

This attribute defines the maximum time that a packet is expected to take to reach any node from any node in
seconds. The length of the attribute is 1 byte. Default value 20.

B.7.19 ADP_IB_ROUTING_TABLE_ENTRY_TTL = 0x00000012

This attribute defines the maximum time-to-live of a routing table entry (in minutes). The length of the attribute is
2 bytes. The value is encoded little endian (lsb first). Default value 60.

B.7.20 ADP_IB_KR = 0x00000013

This attribute defines a weight factor for robust mode to calculate link cost. The length of the attribute is 1 byte.
Default value 0.

B.7.21 ADP_IB_KM = 0x00000014

This attribute defines a weight factor for modulation to calculate link cost. The length of the attribute is 1 byte.
Default value 0.

B.7.22 ADP_IB_KC = 0x00000015

This attribute defines a weight factor for number of active tones to calculate link cost. The length of the attribute
is 1 byte. Default value 0.

B.7.23 ADP_IB_KQ = 0x00000016

This attribute defines a weight factor for LQI to calculate route cost. The length of the attribute is 1 byte. Default
value 10 for CENELEC bandplans, 40 for FCC bandplan.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 91 9
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
1
B.7.24 ADP_IB_KH = 0x00000017
This attribute defines a weight factor for hop to calculate link cost. The length of the attribute is 1 byte. Default
value 4 for CENELEC bandplans, 2 for FCC bandplan.

B.7.25 ADP_IB_RREQ_RETRIES = 0x00000018

This attribute defines the number of RREQ retransmission in case of RREP reception time out. The length of the
attribute is 1 byte. Default value 0.

B.7.26 ADP_IB_RREQ_RERR_WAIT = 0x00000019

This attribute defines the time in seconds to wait between two consecutive RREQ or RRER generations. The
length is 1 byte. Default value 30.

B.7.27 ADP_IB_WEAK_LQI_VALUE = 0x0000001A

This attribute indicates the weak link value which defines the LQI value below which a link to a neighbour is
considered as a weak link. The length is 1 byte. Default value 52 (SNR of 3 dB).

B.7.28 ADP_IB_KRT = 0x0000001B

This attribute indicates a weight factor for the number of active routes in the routing table to calculate link cost.
The length is 1 byte. Default value 0.

B.7.29 ADP_IB_SOFT_VERSION = 0x0000001C

This attribute indicates the software version. This is a read only attribute. The length of the attribute is 6:

 Byte 0: major version number

 Byte 1: minor version number
 Byte 2: revision number
 Byte 3: version date: year (since 2000)
 Byte 4: version date: month
 Byte 5: version date: day

B.7.30 ADP_IB_SNIFFER_MODE = 0x0000001D

Sniffer mode activation/deactivation. The length of the attribute is 1 byte.
 0: Disabled (Default)
 1: Enabled
Note: This attribute is not supported in the current version of the stack.

B.7.31 ADP_IB_BLACKLIST_TABLE = 0x0000001E

This attribute contains the list of the blacklisted neighbours. The size of table is 20. Each element has 4 bytes
length:

 Bytes 0 - 1: the short address of the blacklisted neighbour

 Bytes 2 - 3: the remaining time in minutes while this entry is valid

B.7.32 ADP_IB_BLACKLIST_TABLE_ENTRY_TTL = 0x0000001F

This attribute indicates the maximum time-to-live of a blacklisted neighbour entry (in minutes). The length of the
attribute is 2 bytes. The value is encoded little endian (lsb first). Default value 10.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

92 Atmel
9 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
2
B.7.33 ADP_IB_MAX_JOIN_WAIT_TIME = 0x00000020
This attribute indicates the network join timeout in seconds for LBD. The size of the attribute is 2 bytes. The value
is encoded little endian (lsb first). Default value 20.

B.7.34 ADP_IB_PATH_DISCOVERY_TIME = 0x00000021

This attribute indicates the timeout for path discovery in seconds. The size of the attribute is 1 byte. Default value
40.

B.7.35 ADP_IB_ACTIVE_KEY_INDEX = 0x00000022

This attribute indicates the index of the active GMK to be used for data transmission. This is a read only attribute.
The size of the attribute is 1 byte. Default value 0.

This attribute has a Boolean value:

 FALSE (Default).
 TRUE: default routing.

B.7.36 ADP_IB_DISABLE_DEFAULT_ROUTING = 0x000000F0

This attribute indicates if LOADng protocol should be used or not. The size of the attribute is 1 byte. If 0x01 (true),
the default routing (LOADng) is disabled. If 0x00 (false), the default routing (LOADng) is enabled. Default value:
0x00.

B.7.37 ADP_IB_MANUF_REASSEMBY_TIMER = 0x800000C0

This manufacturer attribute can be used to specify the reassembly timer (the maximum delay between the
reception of two fragments from a message at ADP level). The size of the attribute is 2 bytes. The value is
encoded little endian. Default value is 60 seconds.

B.7.38 ADP_IB_MANUF_IPV6_HEADER_COMPRESSION = 0x800000C1

This manufacturer attribute can be used to enable / disable de compression of the IPv6 headers. This applies
only on the messages sent using the DataRequest service. The size of the attribute is 1 byte. The value 0
indicates the compression is disabled. Value 1 indicates the compression is enabled. Default value 1.

B.7.39 ADP_IB_MANUF_EAP_PRESHARED_KEY = 0x800000C2

This manufacturer attribute specifies the network authentication key. This is a write only attribute. The size of the
attribute is 16 bytes.

B.7.40 ADP_IB_MANUF_EAP_NETWORK_ACCESS_IDENTIFIER = 0x800000C3

This manufacturer attribute specifies the network access identifier used during the EAP process. The size of a
maximum of 36 bytes. Default value points to the extended address of the device.

B.7.41 ADP_IB_MANUF_BROADCAST_SEQUENCE_NUMBER = 0x800000C4

This manufacturer attribute can be used to get/set the broadcast sequence number. The size of the attribute is
1 byte.

B.7.42 ADP_IB_MANUF_REGISTER_DEVICE = 0x800000C5

This manufacturer attribute can be used to force the registration of a device into the network. This is a write only
attribute. The length of the attribute is 28 bytes:

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 93 9
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
3
  Bytes 0 - 7: indicate the extended address of the device( encoded big endian)
 Bytes 8 - 9: indicate the pan id (encoded little endian)
 Bytes 10 - 11: indicate the short address (encoded little endian)
 Bytes 12 - 27: indicate the GMK key

B.7.43 ADP_IB_MANUF_DATAGRAM_TAG = 0x800000C6

This manufacturer attribute can be used to specify the datagram tag to be used for the fragmented transfers.
The size of the attribute is 2 bytes. The value is encoded little endian. Default value is 0 which means the
datagram will be randomly chosen.

B.7.44 ADP_IB_MANUF_RANDP = 0x800000C7

This manufacturer attribute can be used to specify the value of the RandP parameter used during the bootstrap.
The size of the attribute is 16 bytes. The default value is all bytes 0 which means the RandP will be chosen
randomly.

B.7.45 ADP_IB_MANUF_ROUTING_TABLE_COUNT = 0x800000C8

This read only manufacturer attribute can be used to get the number of active entries in the routing table. The
size of the attribute is 4 bytes. The value represents a 32 bits integer encoded little endian (lsb first).

B.7.46 ADP_IB_MANUF_DISCOVER_SEQUENCE_NUMBER = 0x800000C9

This manufacturer attribute can be used to get/set the discover sequence number. The size of the attribute is 2
bytes. The value is encoded little endian.

B.7.47 ADP_IB_MANUF_FORCED_NO_ACK_REQUEST = 0x800000CA

This manufacturer attribute can be used to force that all frames are sent with No Ack request. The size of the
attribute is 1 byte. Default value is 0, which means that the ACK request is decided by G3 mechanisms. Any
other value forces that all frames are sent without Ack request.

B.7.48 ADP_IB_MANUF_LQI_TO_COORD = 0x800000CB

This manufacturer attribute retrieves LQI of the link which is the next hop in the route to Coordinator. This link
can be to Coordinator itself if Coordinator is a neighbour, or to other device in case a route is needed to reach it.

The size of the attribute is 1 byte. Default value is 0, which means that coordinator is not a neighbour and there
is no route to reach it (typically before start exchanging any data with it).

B.7.49 ADP_IB_MANUF_BROADCAST_ROUTE_ALL = 0x800000CC

This manufacturer attribute can be used to activate specific ErDF mode where all the broadcast messages are
propagated (in respect with broadcast sequence number and number of hops) even if the modem is not the
destination of the message.
The normal comportment is to drop broadcast messages which are not sent to the device.
The size of the attribute is 1 byte, interpreted as Boolean.

B.7.50 ADP_IB_MANUF_KEEP_PARAMS_AFTER_KICK_LEAVE = 0x800000CD

This manufacturer attribute enables automatic preservation of some parameters after a reset caused by a
Kick/Leave process. Default value for this parameter is false.
Parameters that are currently saved and restored when this IB is set to true are:
 ADP_IB_MANUF_BROADCAST_SEQUENCE_NUMBER

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

94 Atmel
9 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
4
  ADP_IB_MANUF_DISCOVER_SEQUENCE_NUMBER
 MAC_PIB_FRAME_COUNTER
The size of the attribute is 1 byte, interpreted as Boolean.

B.7.51 ADP_IB_MANUF_ADP_MAC_INTERNAL_VERSION = 0x800000CE

This attribute indicates the internal ADP/MAC version. This is a read only attribute. The length of the attribute is
6:

 Byte 0: major version number

 Byte 1: minor version number
 Byte 2: revision number
 Byte 3: version date: year (since 2000)
 Byte 4: version date: month
 Byte 5: version date: day

B.7.52 ADP_IB_MANUF_CIRCULAR_ROUTES_DETECTED = 0x800000CF

This manufacturer attribute can be used to get the number of Circular Routes (Routing Loops) detected and
corrected by Device. The size of the attribute is 2 bytes.

B.7.53 ADP_IB_MANUF_LAST_CIRCULAR_ROUTE_ADDRESS = 0x800000D0

This manufacturer attribute can be used to get the next hop address involved in the last Routing Loop detected
and corrected, it is provided for statistical purposes. The size of the attribute is 2 bytes.

B.7.54 ADP_IB_MANUF_IPV6_ULA_DEST_SHORT_ADDRESS = 0x800000D1

This manufacturer attribute is intended to be used in a G3 Gateway implementation, it allows upper layers to set
the destination short address of the next data frame to be transmitted, which will be derived from an ULA address.
This allows the ULA / Short address translation to be managed by the Gateway application, out of G3 stack
scope. The size of the attribute is 2 bytes.

B.7.55 ADP_IB_MANUF_MAX_REPAIR_RESEND_ATTEMPTS = 0x800000D2

This manufacturer attribute sets the number of attempts of transmission for a frame when repair has been
performed. The concept “attempt” refers to the whole cycle of transmission fail and repair successful. The aim of
this attribute is to avoid and infinite loop of transmission fail + repair successful, limiting this cycle to a number of
iteration. Default value is 5 and attribute size is 1 byte.

B.7.56 ADP_IB_MANUF_TRIGGER_REPAIR_ON_ROUTE_BROKEN = 0x800000D3

This manufacturer attribute allows controlling the stack behaviour after a Route is broken due to No Ack reception
after sending a frame. Default behaviour is to automatically trigger a Route Repair mechanism (thus default IB
value is True), but user can change this to silently discard the frame after fail, not triggering the Route Repair,
please note that this behaviour is out of G3 spec, and may lead to interoperability issues. Attribute size is 1 byte.

B.8 ADP Status codes description

The list of status codes, and a brief description of each one, reported by ADP is the following:

B.8.1 G3_SUCCESS (0x00)

Returned when the last requested operation succeeded, may it be a Data Request, a Get or Set request, etc.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 95 9
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
5
B.8.2 G3_INVALID_REQUEST (0xA1)
This value is reported in the following situations:
 Discover Route is not allowed from Data request and there is no route available for destination.
Suggested action: Allow Route Discovery on Data Request call, or call AdpRouteDiscoveryRequest
primitive before Data Request.
 Data Request is called before Device has joined a network. Suggested action: Wait for Bootstrap process
to complete before calling Data Request.
 AdpNetworkJoinRequest is called when device is already part of a network. Suggested action: Call
AdpNetworkLeaveRequest and wait for the end of this process before trying to join a network again.
 AdpNetworkLeaveRequest is called when Device is not part of a network. Suggested action: Assume
Device is not part of a network, even before Leave Request was called.

B.8.3 G3_FAILED (0xA2)

This value is reported in the following situations:
 When setting ADP_IB_MANUF_REGISTER_DEVICE and the information is correctly set at ADP layer,
but not at MAC level. Suggested action: Reset G3 stack and configure MAC and ADP layers again.
 Data Request is correctly handled by ADP layer, but MAC layer has no resources in such moment to
handle it. Suggested action: wait a random time in Application level to let MAC layer free some resources
and try sending again.
 On PAN Coordinator, AdpNetworkStartConfirm returns this value when AdpNetworkStartRequest is not
able to request information from MAC layer (short and extended addresses), or when short address at
MAC layer does not match value in ADP_IB_COORD_SHORT_ADDRESS. Suggested action: Reset
G3 stack and configure MAC and ADP layers again.
 On Device, AdpNetworkJoinConfirm returns this value when AdpNetworkJoinRequest is not able to
request information from MAC layer (extended address and PAN ID). Suggested action: Reset G3 stack
and configure MAC and ADP layers again.
 On Device, AdpNetworkJoinConfirm returns this value when setting MAC parameters during Joining
process fails in some intermediate state while exchanging data with coordinator. Suggested action:
Reset G3 stack and configure MAC and ADP layers again. Then start the network Join process again.
 On Device, AdpDiscoveryConfirm returns this value when a Scan Confirm is received from MAC layer,
but ADP layer was not expecting it. Suggested action: Ignore Confirm and start Discovery process again
if necessary.

B.8.4 G3_INVALID_IPV6_FRAME (0xA3)

This value is returned when the buffer passed to AdpDataRequest for sending, does not contain a valid IPv6
frame. Suggested action: Check the correctness of headers at IP level and try sending again.

B.8.5 G3_NOT_PERMITED (0xA4)

This value is returned when a Device is not accepted in the network it is trying to join. It may be due to a DECLINE
frame reception or to a lack or wrong reception of the ACCEPTED frame. Suggested action: Check correctness
of values used in network Join, or try to join another network in case Device is banned in the current one.

B.8.6 G3_ROUTE_ERROR (0xA5)

This value is returned in the following situations:

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

96 Atmel
9 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
6
  When AdpPathDiscoveryRequest primitive is called, and there is no Route for intended destination.
Suggested action: Call first AdpRouteDiscoveryRequest to create the route, and the call
AdpPathDiscoveryRequest to get the path.
 When AdpDataRequest is called for a destination to which there is no Route, allowing Route Discovery,
and such discovery fails to find a route. Suggested action: Wait for a route to be available (or explicitly
look for it using AdpRouteDiscoveryRequest primitive), and the retry sending data.

B.8.7 G3_TIMEOUT (0xA6)

This value is returned in the following situations:
 When a Join process is not completed after the timeout specified in ADP_IB_MAX_JOIN_WAIT_TIME
parameter. Suggested action: Increase timeout.
 When a Path Discover process is not completed after the timeout specified in
ADP_IB_PATH_DISCOVERY_TIME parameter. Suggested action: Increase timeout.

B.8.8 G3_INVALID_INDEX (0xA7)

This value is returned when trying to Set/Get an ADP IB object with an index out of range of the requested object.
Suggested action: Check object range and verify the requested index.

B.8.9 G3_INVALID_PARAMETER (0xA8)

This value is returned when trying to Set an ADP IB object with a length different from the expected. Suggested
action: Check IB length is according to Set request.
Note: A particular case is ADP_IB_SNIFFER_MODE, which is not implemented and this value is returned when
trying to Get/Set it.

B.8.10 G3_NO_BEACON (0xA9)

Not used in the current stack.

B.8.11 G3_READ_ONLY (0xB0)

This value is returned when trying to Set an ADP IB object which cannot be written. Suggested action: Check IB
access rights.

B.8.12 G3_UNSUPPORTED_ATTRIBUTE (0xB1)

This value is returned when trying to Set/Get an ADP IB object with an ID which is not part of the available set.
Suggested action: Check available IDs and verify the requested one.

B.8.13 G3_INCOMPLETE_PATH (0xB2)

This value is returned when the Path returned after an AdpPathDiscoveryRequest has not the complete
information, because a problem was encountered at some point of the path. Suggested action: Call first
AdpRouteDiscoveryRequest to create the route, and the call AdpPathDiscoveryRequest to get the path.

B.8.14 G3_BUSY (0xB3)

This value is returned in the following situations:
When AdpDiscoveryRequest primitive is called when a previous Discovery process is already in progress.
Suggested action: Wait for previous Discovery process to finish (reception of corresponding
AdpDiscoveryConfirm) to request a new one.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 97 9
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
7
B.8.15 G3_NO_BUFFERS (0xB4)
This value is returned when AdpDataRequest primitive is called, but the stack has no free resources to handle
it. It can be due to all transmission buffers are being used, or because a Route Discovery is needed before data
sending, and there are no resources to perform the Discovery (other Discovery process running are using the
resources). Suggested action: wait a random time in Application level to let stack free some resources and try
sending again.

B.8.16 G3_ERROR_INTERNAL (0xFF)

This value is returned in the following situations:
 When trying to Set a MAC IB using a length greater than the attribute length. Suggested action: Check
attribute length is according to set length.
 When trying to get a MAC IB and its length is greater than the container to return it. Suggested action:
Report this issue, as it is a stack internal error that has to be fixed in the library.

B.8.17 MAC layer status codes

All MAC layer status codes are handled by ADP layer and shall not be reported to application except for
MAC_STATUS_NO_ACK (0xE9), which can be reported in case ACK is not received and Route Discovery is
not allowed when calling AdpDataRequest. If Discovery is allowed, a route will be created and data sent, or in
case route is not found, a G3_ROUTE_ERROR will be reported.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

98 Atmel
9 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
8
Appendix C LBP module
This module is only present in the G3 coordinator projects. In this Appendix the API of the implementation of the
coordinator functionality defined by the G3 standard to perform the bootstrapping procedure with joining devices
(LoWPAN Boostrapping Protocol, LBP) is presented and described.

C.1 Functional description

The bootstrap module (also referred to as LBP) implements the functionality of responding to joining devices, in
order to perform the network joining procedure (bootstrap) with them. It also maintains a list of devices that have
joined the network, and manages the short address assigned to each one of them.
The module also offers the possibility to perform a re-keying procedure, by which the GMK is changed as defined
in the G3 specification [4].
Finally, a primitive to start a coordinator-initiated kick is also offered by LBP, as well as a callback to process
device-initiated kicks (which originate a leave indication).

C.2 API listing

C.2.1 Bootstrap module initialization

The LBP initialization function sets up all the variables and structures needed for this functionality. It must be
called at system start.
Its prototype is:

void bs_init (void)

Parameters:

None

C.2.2 Re-keying
In order to launch a re-keying procedure, the following function must be called:

void bs_lbp_launch_rekeying (void)

Parameters:

None

See [4] for details about the procedure, and C.3.6 and C.3.7 to set the current and new GMK.

C.2.3 Joined devices table access

The table of devices that have joined the network can be accessed, as well as their number.
The number of devices that have successfully joined the network is returned by the following function:

uint16_t bs_lbp_get_lbds_counter (void)

Parameters:

None

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 99 9
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
9
 And the table entries can be accessed through the function:

uint16_t bs_lbp_get_lbds_address (uint16_t i)

Parameters:

uint16_t i Index of the entry to access

The function returns the short address assigned to the device stored in that entry of the table. The short
addresses are assigned sequentially to the devices, in order of arrival, starting from the value defined in
LBP_IB_INITIAL_SHORT_ADDRESS (see C.3.3 below).

Or through the function:

bool bs_lbp_get_lbds_ex_address (uint16_t us_short_address, uint8_t *puc_extended_address)

Parameters:

uint16_t us_short_address Short address of the entry to access

uint8_t *puc_extended_address Pointer to which extended address will be copied to

The function returns true in case the requested entry exists, and false otherwise.

C.2.4 Kick
As described in the G3 specification [4], the kick procedure can be initiated by the device or by the coordinator.
For the coordinator to start a kick procedure, the following function must be used:

void bs_lbp_kick_device (uint16_t us_short_address)

Parameters:

uint16_t us_short_address Short address of the device to be kicked

C.2.5 PIB access

BS module offers a set of PIBs which can be read and/or write using the following functions:

void bs_lbp_get_param (uint32_t ul_attribute_id, uint16_t us_attribute_idx, struct

t_bs_lbp_get_param_confirm *p_get_confirm)

Parameters:

uint32_t ul_attribute_id ID of attribute to be read

uint16_t us_attribute_idx Index to read (in case it is a list)

struct Pointer to Confirm structure where result will be returned

t_bs_lbp_get_param_confirm
*p_get_confirm

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

100 Atmel
1 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
0
 void bs_lbp_set_param (uint32_t ul_attribute_id, uint16_t us_attribute_idx, uint8_t uc_attribute_len, const
uint8_t *puc_attribute_value, struct t_bs_lbp_set_param_confirm *p_set_confirm)

Parameters:

uint32_t ul_attribute_id ID of attribute to be written

uint16_t us_attribute_idx Index to write (in case it is a list)

uint8_t uc_attribute_len Length of attribute to be written

const uint8_t *puc_attribute_value Value to be written

struct t_bs_lbp_set_param_confirm Pointer to Confirm structure where result will be returned

*p_set_confirm

C.2.6 Callback integration with upper and lower layers

When initializing the underlying ADP layer, all G3 stack callbacks have to be defined and set as parameter. In
provided implementation, functions to handle LBP callbacks (LbpConfirm and LbpIndication) are implemented in
the LBP module, so the upper layer which is in charge of initializing G3 stack, needs to know the pointers to
these functions in advance, before calling ADPInitialize function. An example of usage can be found in provided
example application for Coordinator (described in section 7.1.1).
To get the LBP callbacks, the following function is used:

TBootstrapAdpNotifications* bs_get_not_handlers (void)

Parameters:

None

The callbacks are returned in the structure pointed by TBootstrapAdpNotifications *, defined like this:
typedef struct {
AdpLbpConfirm fnctAdpLbpConfirm;
AdpLbpIndication fnctAdpLbpIndication;
}TBootstrapAdpNotifications;

LBP module also offers the possibility to upper layer of setting callbacks in order to be notified when a Device
Joins or Leaves the Networtk, by means of the functions:

void bs_lbp_leave_ind_set_cb(pf_app_leave_ind_cb_t pf_handler)

Parameters:

pf_app_leave_ind_cb_t pf_handler Pointer to function which will be called when a Device Leaves the
Network

void bs_lbp_join_ind_set_cb(pf_app_join_ind_cb_t pf_handler)

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 101 1
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
1
 Parameters:

pf_app_join_ind_cb_t pf_handler Pointer to function which will be called when a Device Joins the
Network

C.3 LBP Objects Specification and Access

In addition to the ones defined in the G3 specification [4] and the MAC- and ADP-specific ones (B.3, B.7), the
LBP defines and manages the IB attributes listed here. The default endianness of all LBP IBs is little endian, in
other case it will be explicitly specified.

C.3.1 LBP_IB_IDS = 0x00000000

This object represents the Network Access Identifier of the EAP server. Its size depends on the used band (8
bytes for CENELEC and FCC, and 34 bytes for ARIB).
Access is Write Only.

C.3.2 LBP_IB_DEVICE_LIST = 0x00000001

This IB provides access to the joined devices list. It allows to add an entry in this list, providing a pair short
address – extended address, and to read one of the entries. If the entry to be written is already occupied by a
valid entry, an error is returned.
Provided value when set has to be an array of size 10 bytes, where 2 first bytes are Short Address, and the
following 8 bytes are Extended Address. Returned value when get follows this same format. The encoding of the
extended address is big endian and short address is encoded in little endian to be coherent with ADP encodings.
The maximum number of entries in the table of joined devices is 500 for the Lite Coordinator and 2000 in the full
one.
Access is Read/Write.

C.3.3 LBP_IB_INITIAL_SHORT_ADDRESS = 0x00000002

This IB provides access to the configurable initial short address that the coordinator uses to assign to the joining
devices. Its size is 2 bytes.
If there are already joined devices, this parameter can no longer be changed, and an error is returned if this is
attempted.
Access is Read/Write.

C.3.4 LBP_IB_ADD_DEVICE_TO_BLACKLIST = 0x00000003

This IB allows to add an extended address to the LBP blacklist. By doing so, this address will be banned from
joining the network for the configured blacklist permanence time [4]. This IB’s size is 8 bytes. The encoding of
the extended address must be big endian.
Access is Write Only.

C.3.5 LBP_IB_PSK = 0x00000004

With this IB, the PSK of the LBP procedure can be specified. Its size is 16 bytes.
Access is Write Only.

C.3.6 LBP_IB_GMK = 0x00000005

With this IB, the GMK of the LBP procedure can be specified. Its size is 16 bytes.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

102 Atmel
1 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
2
 Access is Write Only.

C.3.7 LBP_IB_REKEY_GMK = 0x00000006

With this IB, the destination GMK of the LBP re-keying procedure can be specified. Its size is 16 bytes.
Access is Write Only.

C.4 Brief of provided LBP Module example

Atmel provides an example implementation of LBP module to be used in G3 PAN Coordinator in order to accept
Devices willing to join the Network, and therefore make them accessible to upper layers for data exchange.

C.4.1 Initialization function

When upper layer calls LBP initialization function, the following steps are performed:
 Short address is set to 0 as Coordinator.
 Initial address to give to Devices joining the network is set to 1.
 LBD blacklist and LBD device list are cleared.
 IdS parameter is initialized to constant values provided in the LBP module.
 GMK key is set.
All these values are available as either constants or initialized variables in the same LBP module and can be
changed by the user to fit specific needs.

C.4.2 LBD Device list

An LBD Device list is managed by the LBP module. This list has a number of elements defined by the constant
MAX_LBDS, each element represents a Device which has joined the network, and the information contained in
the list entry is the EUI64 of the joined Device. The short address of the device is given by the result of the
following operation: (index in list) + g_current_context.initialShortAddr, where this initial short address is
initialized to 1 by default, but can be changed to fit user needs, either changing the default value or by means of
setting the LBP_IB_INITIAL_SHORT_ADDRESS parameter.
In the provided implementation, LBP module assigns short addresses sequentially, starting with
g_current_context.initialShortAddr and adding 1 each time a device wants to join the network. In case a Device
bootstraps more than once, a new short address is given, even if it was already present in the network before,
and the old entry is removed from the list. In case the end of the list is reached, the algorithm looks for removed
entries to reuse them. If the list is full, no more Devices are accepted in the network.

C.4.3 LBD Blacklist

A Blacklist of devices is implemented in the module. When a Device is present the blacklist, it is not accepted
when it tries to join the network. Entries can be added to blacklist from upper layers using
LBP_IB_ADD_DEVICE_TO_BLACKLIST.

C.4.4 Processing of LBP frames

An implementation of LBP frames is provided in the module following specification of IETF RFC 3748 and
extended in G3 spec. The processing of frames is available in the module. The encoding/decoding is internal to
Atmel G3 library as it needs crypto functionality internally implemented.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel G3-PLC FW Stack User Guide 103 1
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
3
C.4.5 Rekeying
The rekeying functionality is implemented in the module, changing the GMK of the network from the value defined
in g_au8CurrGMK to the value defined in variable g_au8RekeyGMK. This process can only be performed in one
direction, and upon reset, the GMK used will be g_au8CurrGMK in any case.
A more complex rekeying process and GMK management is left to the user.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

104 Atmel
1 G3-PLC FW Stack User Guide
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
4
Atmel Corporation 1600 Technology Drive, San Jose, CA 95110 USA T: (+1)(408) 441.0311 F: (+1)(408) 436.4200 │ www.atmel.com

© 2016 Atmel Corporation. / Rev.:Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17.

Atmel Confidential: For Release Only Under Non-Disclosure Agreement (NDA)

Atmel®, Atmel logo and combinations thereof, Enabling Unlimited Possibilities®, and others are registered trademarks or trademarks of Atmel Corporation in U.S. and
other countries. ARM®, ARM Connected® logo, and others are the registered trademarks or trademarks of ARM Ltd. Other terms and product names may be
trademarks of others.

DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, b y estoppel or otherwise, to any intellectual property right
is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF S ALES LOCATED ON THE
ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON -INFRINGEMENT. IN NO EVENT
SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENT AL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES
FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT , EVEN IF ATMEL
HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this
document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information
contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, auto motive applications. Atmel products are not intended,
authorized, or warranted for use as components in applications intended to support or sustain life.

SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in conne ction with any applications where
the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without an Atmel officer's specific written consent.
Safety-Critical Applications include, without limitation, life support devicesAtmel Confidential:
and systems, equipmen For
t or Release Only
systems for the Under
operationNon-Disclosure Agreement
of nuclear facilities and weapons (NDA)
systems. Atmel
products are not designed nor intended for use in military or aerospace applications or environments unless specifically desi gnated by Atmel as military-grade. Atmel products are not
designed nor intended for use in automotive applications unless specifically designated by Atmel as automotive -grade. Atmel G3-PLC FW Stack User Guide 105 1
Atmel-43081W-ATPL-G3-PLC_Firmware_Stack-User Guide_6-Apr-17
0
5