Page 1
MKW01 Simple Media Access
Controller (SMAC)
Reference Manual
Document Number: MKW01SMACRM
Rev. 0.0
3/2015
Page 2
How to Reach Us:
Home Page:
www.freescale.com
E-mail:
support@freescale.com
Information in this document is provided solely to enable system and software implementers to use
Freescale Semiconductor products. There are no express or implied copyright licenses granted
hereunder to design or fabricate any integrated circuits or integrated circuits based on the information
in this document.
Freescale Semiconductor reserves the right to make changes without further notice to any products
herein. Freescale Semiconductor makes no warranty, representation or guarantee regarding the
suitability of its products for any particular purpose, nor does Freescale Semiconductor assume any
liability arising out of the application or use of any product or circuit, and specifically disclaims any
and all liability, inclu ding without limitation consequential or incidental damages. “Typ ical” parameters
that may be provided in Freescale Semiconductor data sheets and/or specifications can and do vary
in different applications and actual performance may vary over time. All operating parameters,
including “Typicals”, must be validat ed for each customer application by customer’s technical
experts. Freescale Semiconductor does not convey any license under its patent rights nor the rights
of others. Freescale Semiconductor products are not designed, intended, or authorized for use as
components in systems intended for surgical implant into the body, or other applications intended to
support or sustain life, or for any other application in which the failure of the Freescale Semiconductor
product could create a situation where personal injury or death may occur. Should Buyer purchase
or use Freescale Semiconductor products for any such unintended or unauthorized application,
Buyer shall indemnify and hold Freescale Semiconductor and its officers, employees, subsidiaries,
affiliates, and distributors harmless against all claims, costs, damages, and expenses, and
reasonable attorney fees arising out of, directly or indirectly, any claim of personal injury or death
associated with such unintended or unauthorized use, even if such claim alleges that Freescale
Semiconductor was negligent regarding the design or manufacture of the part.
Freescale™ and the Freescale logo are trademarks of Freescale Semiconductor, Inc. All other
product or service names are the property of their respective owners.
© Freescale Semiconductor, Inc. 2013, 2014. All rights reserved.
Page 3
Chapter 1.
MKW01 SMAC Introduction
1.1. MKW01 SMAC-based Demonstration Applications ..............................................................6
1.2. Platform Requirements ............................................................................................................7
1.3. MCU Resources Used by SMAC ............................................................................................7
1.4. SMAC Basic Initialization .......................................................................................................7
Chapter 2.
Software Architecture
2.1. Block Diagram .........................................................................................................................9
2.2. MKW01 SMAC Data Types and Structures ..........................................................................10
2.2.1 Fundamental Data Types ................................................................................................. 10
2.2.2 rxPacket_t ........................................................................................................................ 10
2.2.3 smacHeader_t................................................................................................................... 11
2.2.4 rxStatus_t ......................................................................................................................... 12
2.2.5 smacPdu_t........................................................................................................................ 12
2.2.6 txPacket_t......................................................................................................................... 12
2.2.7 channels_t ........................................................................................................................ 13
2.2.8 smacErrors_t.................................................................................................................... 14
2.2.9 txContextConfig_t ........................................................................................................... 15
2.2.10 smacTestMode_t............................................................................................................ 15
2.2.11 packetConfig_t............................................................................................................... 15
2.2.12 smacRFModes_t ............................................................................................................ 16
2.2.13 smacEncryptionKeyIV_t ............................................................................................... 16
2.3. MKW01 SMAC to Application Messaging ...........................................................................17
Chapter 3.
Primitives
3.1. MCPSDataRequest ................................................................................................................21
3.2. MLMETXDisableRequest .....................................................................................................22
3.3. MLMEConfigureTxContext ..................................................................................................23
3.4. MLMERXEnableRequest ......................................................................................................24
3.5. MLMERXDisableRequest .....................................................................................................25
3.6. MLMELinkQuality ................................................................................................................26
3.7. MLMESetChannelRequest ....................................................................................................26
3.8. MLMEGetChannelRequest ...................................................................................................27
3.9. MLMEPAOutputAdjust .........................................................................................................27
3.10. MLMEPhySoftReset ............................................................................................................28
3.11. MLMEScanRequest .............................................................................................................28
3.12. MLMECcaRequest ..............................................................................................................29
MKW01 Simple Media Acces s Controller (SMAC), Rev. 0.0
Freescale Semiconduc tor 1
Page 4
3.13. MLMESetPreambleLength ..................................................................................................30
3.14. MLMESetSyncWordSize ....................................................................................................30
3.15. MLMESetSyncWordValue ..................................................................................................30
3.16. MLMEPacketConfig ............................................................................................................31
3.17. MLMESetAdditionalRFOffset ............................................................................................31
3.18. MLMEGetAdditionalRFOffset ............................................................................................32
3.19. SMACSetShortSrcAddress ..................................................................................................32
3.20. SMACSetPanID ...................................................................................................................33
3.21. SMACFillHeader .................................................................................................................34
3.22. SMAC_SetIVKey ................................................................................................................34
3.23. Smac_RegisterSapHandlers .................................................................................................35
MKW01 Simple Media Acces s Controller (SMAC), Rev. 0.0
2 Freescale Semiconduct or
Page 5
About This Book
This manual provides a detailed description of the Freescale MKW01 Simple Media Access Controller
(MKW01 SMAC). This software is designed for use specifically with the MKW01 platform. The MKW01
is a highly-integrated, cost-effective, system-in-package (SiP), sub-1 GHz wireless node solution with an
FSK, GFSK, MSK, or OOK modulation-capable transceiver and low-power, ARM Cortex M0+ 32-bit
microcontroller . The highly integrated RF transceiver operates over a wide frequency range including 315
MHz, 433 MHz, 470 MHz, 868 MHz, 915 MHz, 928 MHz, and 955 MHz in the license-free Industrial,
Scientific, and Medical (ISM) frequency bands.
The MKW01 SMAC software is pre-defined to operate in the 470–510 MHz , 863–870 MHz, 902–928
MHz and 920–928 MHz bands.
Audience
This document is intended for application developers working on custom wireless applications that
employ the MKW01. The latest version of the Freescale MKW01 SMAC is available in the Freescale
website.
Organization
This document is organized into four chapters and one appendix.
Chapter 1 MKW01 SMAC Introduction — This chapter introduces MKW01 SMAC
features and functionality.
Chapter 2 Software Architecture — This chapter describes MKW01 SMAC software
architecture.
Chapter 3 Primitives — This chapter provides a detailed description of MKW01 SMAC
primitives.
Revision History
The following table summarizes revisions to this document since the previous release.
Revision History
Location Revision
MKW01SMACRM This is the first release of the RTOS
and KSDK enabled SMAC manual.
Conventions
This document uses the following notational conventions:
• Courier monospaced type indicate commands, command parameters, code examples,
expressions, datatypes, and directives.
• Italic type indicates replaceable command parameters.
• All source code examples are in C.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 3
Page 6
Definitions, Acronyms, and Abbreviations
The following list defines the acronyms and abbreviations used in this document.
MKW01 MKW01 Platforms (FRDM-KW01, MRB-KW01, USB-KW01)
GUI Graphical User Interface
MAC Medium Access Control
MCU MicroController Unit
NVM Non-Volatile Memory
PC Personal Computer
TERM Serial Port Terminal Application
XCVR Transceiver
PCB Printed Circuit Board
OTA Over the air.
SAP Service Access Point
ACK Acknowledge
AA Automatic ACK
LBT Listen Before Talk
RX Receive(r)
TX Transmit(ter)
CCA Clear Channel Assessment
ED Energy Detect
References
The following sources were referenced to produce this book:
1. Freescale MKW01 Reference Manual (MKW01xxRM.pdf)
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
4 Freescale Semiconduct or
Page 7
Chapter 1
MKW01 SMAC Introduction
The Freescale MKW01 Simple Media Access Controller (MKW01 SMAC) is a simple ANSI C based
codebase available as sample source code. The MKW01 SMAC is used for developing proprietary RF
transceiver applications using Freescale’s MKW01 sub-1 GHz transceiver plus microcontroller. The
MKW01 is a system-in-package (SIP) device that includes an ARM Cortex M0+ based microcontroller
and a sub-GHz ISM band radio front-end device in an LGA-56 package. Features of the MKW01 include:
• MCU has a 32-bit ARM Cortex M0+ CPU with a full set of peripheral functions
• MCU has 128KB flash and 16KB SRAM
• Full featured, programmable sub-1 GHz transceiver that supports FSK, GFSK, MSK, GMSK, and
OOK modulations schemes.
• The MKW01 has internal and external connections between the MCU and transceiver:
— The MCU communicates with the transceiver through an internally connected SPI port.
— Several transceiver status bits are also i nternally or ext ernally connecte d to MCU GPIO and are capable
of generating interrupt requests.
NOTE
It is highly recommended the SMAC user be familiar with the MKW01
device. Additional details can be found in the device data sheet (MKW01)
and the MKW01 Reference Manual (MKW01xxRM).
The MKW01 SMAC is a small codebase that provides simple communication and test applications based
on drivers, (802.15.4 compliant) PHY and framework utilities available as source code. This environment
is useful for hardware and RF debug, hardware standards certification, and developing proprietary
applications. The MKW01 SMAC is provided as part of the Example Application Demos available for
MKW01 and also as a standalone set of files.
To use any of the existing applications available in MKW01 SMAC, users must download and open the
available Application Demos in the corresponding development environment (IDE).
SMAC features include:
• Compact footprint:
— Between 2 to 3KB of flash required, depending on configuration used.
— Less than 500 bytes RAM, depending on configuration used.
• Very low power, proprietary, bidirectional RF communication link.
• The MKW01 radio allows checking the preamble and the synchronization word, which reduces
software overhead and memory footprint.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 1-5
Page 8
MKW01 SMAC Introduction
• Broadcast communication
• Unicast communication — MKW01 SMAC includes a Node Address 16-bit field. This allows
SMAC to perform unicast transmissions. To change the address of a node, modify this constant:
gNodeAddress_c inside the SMAC_Config.h file, or call SMACSetShortSrcAddress(uint16_t
nwShortAddress).
The address is set to 0xBEAD by default. Some of the Demo Applications
will allow the user to change this address at runtime.
• Change of current PAN. The SMAC packet uses a short 802.15.4 compliant header with a
hard-coded configuration for frame control which allows the user to switch between PANs. The
PAN address has also 16 bits (gDefaultPanID_c). This address can be modified both by changing
the default value from SMAC_Config.h file or by calling SMACSetPanID(uint16_t
nwShortPanID.
• There are no blocking functions within the MKW01 SMAC.
• Flexible enough to conf igure packet hea der (preamble siz e, synchronizati on word size, and sy nchronization
word value)
• Pre-defined settings at four different bands to initialize the SMAC protocol. The currently
supported operating frequency bands are:
— 863 – 870 MHz (Europe)
— 902 – 928 MHz (US)
— 920 – 928 MHz (Japan)
— 470 – 510 MHz (China)
• Easy-to-use sample applications included.
• Light-weight, custom LBT algorithm.
• Light-weight, custom, AA mechanism which is transparent to the user after enabling the feature.
• Encryption using Advanced Encryption Standard in Cipher Block Chaining mode, with
configurable initial vector and key.
• Configurable number of retries and backoff interval.
• Inter-layer communication using SAPs.
• The MKW01 SMAC also filters packets that have correct addressing information (pass address
filtering) but are not in the expected format (short addressing, no security, data frame).
1.1 MKW01 SMAC-based Demonstration Applications
The following is a list of MKW01 SMAC-based demonstration applications:
• PC-based Connectivity T est Application which requires a TERM. This application allows the user
to perform basic communication tests and several advanced XCVR tests.
• PC-based Wireless Messenger Application which requires a TERM and is presented in the form of
a messenger-like application. This demo application highlights the “Listen Before Talk” and
“Automatic ACK” mechanisms, allowing the user to enable, disable and configure them at
runtime.
• PC-based Wireless UART Application which requires either a TERM or an application capable of
reading/writing from/to a serial port. This application is used as a wireless UART bridge bet w een
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
1-6 Freescale Semiconduct or
Page 9
MKW01 SMAC Introduction
two or more (one to many) MKW01 platforms. It can be configured to use the previously
mentioned mechanisms, but the configuration must be done at compile time.
• PC-based Low Power Demo Application which requires a TERM. This application aids the user in
enabling low power modes on the MKW01 platforms.
1.2 Platform Requirements
The SMAC can be used with any customer target application or board, however, Freescale provides several
development platform (modular reference board, freedom board and usb dongle) designs with leds,
pushbuttons and other modules included.
1.3 MCU Resources Used by SMAC
As stated, the MKW01 contains an MCU and a transceiver in a single package. The SMAC does not use
MCU resources directly. All accesses to the MCU resources are performed using the framework, drivers
and PHY.
1.4 SMAC Basic Initialization
Before transmitting, receiving, or performing any other SMAC operation described in this manual, the
system protocol must be initiali ze d to configure the transce iver with c o rre ct functi onal set tings and t o se t
SMAC's state machine to known states. To initialize the SMAC, perform the following tasks in order:
1. Initialize MCU interrupts and peripherals. This initialization is included in every demo in the
hardware_init(void) function, available as source code.
— Initialize LED, Keyboard, Serial Manager, Timers Manager, Memory Manager, drivers
depending on application needs.
MEM_Init();
TMR_Init();
LED_Init();
SerialManager_Init();
— Initalize PHY layer.
Phy_Init();
2. Initialize SMAC, to set the SMAC state machine to default, configure addressing with default
values, initialize the RNG used for the first sequence number value and the random backoff.
InitSmac();
3. Set the SAP handlers so that SMAC can noti fy the application on asynchronous events on both data
and management layers.
void Smac_RegisterSapHandlers(
SMAC_APP_MCPS_SapHandler_t pSMAC_APP_MCPS_SapHandler,
SMAC_APP_MLME_SapHandler_t pSMAC_APP_MLME_SapHandler,
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 1-7
Page 10
MKW01 SMAC Introduction
instanceId_t smacInstanceId
)
4. Reserve the RAM memory space needed by SMAC to alloca te th e rec ei ved and tran smitt ed OTA
messages by declaring the buffers that must be of the size gMaxSmacSDULength_c + sizeof(packet
type):
uint8_t RxDataBuffer[gMaxSmacSDULength_c + sizeof(rxPacket_t)];
rxPacket_t *RxPacket;
uint8_t TxDataBuffer[gMaxSmacSDULength_c + sizeof(txPacket_t)];
txPacket_t *TxPacket;
RxPacket = (rxPacket_t*)RxDataBuffer;
TxPacket = (txPacket_t*)TxDataBuffer;
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
1-8 Freescale Semiconduct or
Page 11
Chapter 2
Software Architecture
This chapter describes the MKW01 SMAC software architecture. All of the SMAC source code is always
included in the application. SMAC is primarily a set of utility functions or building blocks that users can
use to build simple communication applications.
2.1 Block Diag ram
Figure 2-1 shows a simplified MKW01 SMAC based stack block diagram.
An application programming interface (API) is imple mented in the MKW01 SMAC as a C header file (.h)
that allows access to the code. The code includes the API to specific functions. Thus, the application
interface with the SMAC is accomplished by including the SMAC_Interface.h file, which makes reference
to the required functions within the SMAC and provides the application with desired functionality.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 2-9
Figure 2-1. SMAC System Decomposition
Page 12
Software Architecture
NOTE
MKW01 SMAC projects support only the MKW01-based target boards
designated in the files.
2.2 MKW01 SMAC Data Types and Structures
The MKW01 SMAC fundamental data types and defined structures are discussed in the following
sections.
2.2.1 Fundamental Data Types
The following list shows the fundamental data types and the naming convention used in the MKW01
SMAC:
uint8_t Unsigned 8-bit definition
uint16_t Unsigned 16-bit definition
uint32_t Unsigned 32-bit definition
int8_t Signed 8-bit definition
int16_t Signed 16-bit definition
int32_t Signed 32-bit definition
These data types are used in the MKW01 SMAC project as well as in the applications projects. They are
defined in the EmbeddedTypes.h file.
2.2.2 rxPacket_t
This structure defines the variable used for MKW01 SMAC received data buffer:
typedef struct rxPacket_tag{
uint8_t u8MaxDataLength;
rxStatus_t rxStatus;
uint8_t u8DataLength;
smacHeader_t smacHeader;
smacPdu_t smacPdu;
}rxPacket_t;
Members
u8MaxDataLength Max number of bytes to be received.
rxStatus Indicates the reception state. See rxStatus_t data type for more detail.
u8DataLength Number of received bytes.
smacPdu The MKW01 SMAC protocol data unit.
smacHeader SMAC structure that defines the header used. Freescale recommends that the user
does not modify this structure directly, but through the associated functions.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
2-10 Freescale Semiconduct or
Page 13
Software Architec t ure
Usage
This data type is used by an application in the following manner:
1. Declare a b uffer t o store a pa cket to be r eceived OTA. Freescale r ecommends the size of th is buffer
to be at least as long as the biggest packet to be received by the application.
2. Declare a pointer of the type rxPacket_t.
3. Initialize the pointer to point to the buffer declared at the first step.
4. Initialize the u8MaxDataLength member of the packet structure. The SMAC will filter all the
received packets having a payload size bigger than u8MaxDataLength.
5. Use the pointer as the argument when calling MLMERXEnableRequest:
uint8_t RxDataBuffer[gMaxSmacSDULength_c + sizeof(rxPacket_t)];
rxPacket_t *RxPacket;
RxPacket = (rxPacket_t*)RxDataBuffer;
RxPacket->u8MaxDataLength = gMaxSmacSDULength_c;
RxEnableResult = MLMERXEnableRequest(RxPacket, 0);
You can use a variable of the type smacErrors_t to store the result of executing
MLMERXEnableRequest function.
2.2.3 smacHeader_t
This structure defines the variable used for MKW01 SMAC header:
typedef PACKED_STRUCT rxPacket_tag{
uint16_t frameControl;
uint8_t seqNo;
uint16_t panId;
uint16_t destAddr;
uint16_t srcAddr;
}rxPacket_t;
Members
frameControl Frame control configuration. The value is set each time SMACFillHeader is called
and should not be changed.
seqNo The Sequence number is updated each time a data request is performed.
panId The value of the source and destination PAN address. It is recommended to be
changed through the associated function.
destAddr The short destination address.
srcAddr The short source address.
Usage
Freescale recommends that the user does not access this structure directly but through the associated
functions.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 2-11
Page 14
Software Architecture
2.2.4 rxStatus_t
This enumeration lists all the possible reception states:
typedef enum rxStatus_tag
{
rxInitStatus,
rxProcessingReceptionStatus_c,
rxSuccessStatus_c,
rxTimeOutStatus_c,
rxAbortedStatus_c,
rxMaxStatus_c
} rxStatus_t;
Members
rxInitStatus The RTOS based MKW01 SMAC does not use this.
rxProcessingReceptionStatus_c This state is set when the MKW01 SMAC is in the middle of rec eiving
a packet.
rxSuccessStatus_c This is one of the possible finish conditions for a received packet that
was successfully received and could be checked by the indication
functions.
rxTimeOutS tatus_c This is another of the possible finish conditions for a timeout conditi on
and could be checked by the indication functions.
rxAbortedStatus_c This status is set when SMAC drops a packet (on SMAC specific
criteria) validated by PHY and the enter reception request was
performed with a timeout.
rxMaxStatus_c This element indicates the total number of possible reception states.
2.2.5 smacPdu_t
This type defines the SMAC’s basic protocol data unit:
typedef struct smacPdu_tag{
uint8_t smacPdu[1];
}smacPdu_t;
Members
smacPdu[1]. Starting position of the buffer where TX or RX data is stored.
2.2.6 txPacket_t
This structure defines the type of variable to be transmitted by the MKW01 SMAC. It is located in the
SMAC_Interface.h file and is defined as follows:
typedef struct txPacket_tag
{
uint8_t u8DataLength;
smacHeader_t smacHeader;
smacPdu_t smacPdu;
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
2-12 Freescale Semiconduct or
Page 15
Software Architec t ure
}txPacket_t;
Members
u8DataLength The number of bytes to transmit.
smacHeader SMAC structure that defines the header used. Freescale recommends that the user
does not modify this structure directly, but through the associated functions.
smacPdu The MKW01 SMAC protocol data unit.
Usage
This data type is used by an application in the following manner:
1. Declare a buffer to store the packet to be transmitted OTA. Freescale recommends the size of this
buffer is at least as long as the biggest packet to be transmitted by the application.
2. Declare a pointer of the type txPacket_t.
3. Initialize the pointer to point to the buffer declared at the first step.
4. Copy the desired data into the payload.
5. Set u8DataLength to the size (in bytes) of the payload.
6. Use the pointer as the argument when calling MCPSDataRequest.
uint8_t TxDataBuffer[gMaxSmacSDULength_c + sizeof(txPacket_t)];
txPacket_t *TxPacket;
...
TxPacket = (txPacket_t*)TxDataBuffer;
SMACFillHeader(&(TxPacket->smacHeader), 0xFFFF);
FLib_MemCpy(TxPacket->smacPdu.smacPdu, dataToBeSentBuffer, payloadSizeBytes);
TxPacket->u8DataLength = payloadSizeBytes;
DataRequestResult = MCPSDataRequest(TxPacket);
You can use a variable of the type smacErrors_t to store the result of executing MCPSDataRequest
function.
2.2.7 channels_t
Definition for RF channels. The number of channel varies in each defined operating band for sub-1 GHz
stacks and is fixed for the 2.4 GHz. First logical channel in all bands is 0 for sub-1GHz and 11 for 2.4 GHz.
It is defined as follows:
typedef enum channels_tag
{
#include "SMAC_Channels.h"
} channels_t;
Each application derives the minimun and maximum channel values from the enumeration above. SMAC
only keeps an enumeration of all the possible channel numbers.
Members
None
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 2-13
Page 16
Software Architecture
2.2.8 smacErrors_t
This enumeration is used as the set of possible return values on most of the MKW01 SMAC API functions
and is located in the SMAC_Interface.h. Also, some of the messages sent by SMAC t o the application use
this enumeration as a status.
typedef enum smacErrors_tag{
gErrorNoError_c = 0,
gErrorBusy_c,
gErrorChannelBusy_c,
gErrorNoAck_c,
gErrorOutOfRange_c,
gErrorNoResourcesAvailable_c,
gErrorNoValidCondition_c,
gErrorCorrupted_c,
gErrorMaxError_c
} smacErrors_t;
Members
gErrorNoError_c The MKW01 SMAC accepts the request and processes it. This return
value does not necessarily mean that the action requested was
successfully executed. It means only that it was accepted for processing
by the MKW01 SMAC. This value is also used as a return status in the
SMAC to application SAPs. For example, if a packet has been
succesfully sent, the message will have a data confirm field with this
status. Also, this value is returned in the CCA confirm message if the
scanned channel is found idle.
gErrorBusy_c This constant is returned when the MKW01 SMAC layer is not in an idle
state, and it cannot perform the requested action.
gErrorChannelBusy_c The custom “Listen Before Talk” algorithm detected a busy channel
more times than the configured number of retries. Also, a CCA confirm
message can have this value if the channel is found busy.
gErrorNoAck_c The custom “Automatic Ack” mechanism detected that no
acknowledgement packet has been received more times than the
configured number of retries.
gErrorOutOfRange_c A certain parameter configured by the application is not in the valid
range.
gErrorNoValidCondition_c Returned when requesting an action on an invalid environment.
Requesting MKW01 SMAC operations when MKW01 SMAC has not
been initialized or requesting to disable RX when SMAC was not in a
receiving or idle state, or setting a number of retries without enabling the
“LBT and AA” features.
gErrorCorrupted_c Not implemented in the RTOS based SMAC.
gErrorMaxError_c This constant indicates the total number of returned constants.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
2-14 Freescale Semiconduct or
Page 17
Software Architec t ure
2.2.9 txContextConfig_t
typedef struct txContextConfig_tag
{
bool_t ccaBeforeTx;
bool_t autoAck;
uint8_t retryCountCCAFail;
uint8_t retryCountAckFail;
}txContextConfig_t;
Members
ccaBeforeTx bool_t value to enable/disable the “LBT” mechanism.
autoAck bool_t value to enable/disable the “AA” mechanism.
retryCountCCAFail This value specifies the number of times the MKW01 SMAC will
attempt to re-transmitt a packet if “LBT” is enabled and channel is found
busy.
retryCountAckFail This value specifies the number of times the MKW01 SMAC will
attempt to re-transmitt a packet if “AA” is enabled and no
acknowledgement message is received in the expected time frame.
2.2.10 smacTestMode_t
typedef enum smacTestMode_tag
{
gTestModeForceIdle_c = 0,
gTestModeContinuousTxModulated_c,
gTestModeContinuousTxUnmodulated_c,
gTestModePRBS9_c,
gTestModeContinuousRxBER_c,
gMaxTestMode_c
} smacTestMode_t;
This enumeration is used only in the Connectivity Test Application, to select the type of test to be
performed. Keep in mind that all the decisions are taken at application level and this enumeration is used
only as a reference for designing the test modes.
2.2.11 packetConfig_t
typedef struct packetConfig_tag
{
uint16_t u16PreambleSize;
uint8_t u8SyncWordSize;
uint8_t* pu8SyncWord;
} packetConfig_t;
Members
u16PreambleSize The preamble size.
u8syncWordSize The size of the synchronization word.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 2-15
Page 18
Software Architecture
pu8SyncWord Pointer to an array containing the value of the synchronization word.
Usage
Declare a variable of pa cketConfig_t type. Fill the re quired information and call MLMEPacke tConfig with
a pointer to the structure. Optionally, you can store the return value in a smacErrors_t variable.
Please consult the reference manual for valid lengths of preamble and synchronization word.
2.2.12 smacRFModes_t
typedef enum smacRFModes_tag
{
gRFMode1_c = gPhyMode1_c,
gRFMode2_c = gPhyMode2_c,
gRFMode3_c = gPhyMode3_c,
gRFMode4_c = gPhyMode4_c,
gRFMode5_c = gPhyMode1ARIB_c, /*ARIB mode 1*/
gRFMode6_c = gPhyMode2ARIB_c, /*ARIB mode 2*/
gRFMaxMode_c
} smacRFModes_t;
Members
gRFModeX_c With X from 1 to 4 corresponds to PHY modes 1 to 4. User must check that the
frequency band used supports the mode to be used.
gRFMode5_c This is PHY mode 1 in case the user wants to use the Japan frequency band with
ARIB mode 1.
gRFMode6_c This is PHY mode 2 in case the user wants to use the Japan frequency band with
ARIB mode 2.
Usage
Call MLMESetPhyMode with the desired enumeration member. Optionally store the return value in a
smacErrors_t variable.
2.2.13 smacEncryptionKeyIV_t
typedef struct smacEncryptionKeyIV_tag
{
uint8_t IV[16];
uint8_t KEY[16];
}smacEncryptionKeyIV_t;
Members
IV The initial vector used by the CBC mode of AES.
KEY The encryption / decryption key used by the CBC mode of AES.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
2-16 Freescale Semiconduct or
Page 19
Software Architec t ure
Usage
This data type is used internally by SMAC. Call SMAC_SetIVKey with two 16 byte buffer pointers as
parameters to change the SMAC initial vector and encryption key settings.
2.3 MKW01 SMAC to Application Messaging
The R TOS based SMAC communicates with the application layer in two ways: directly, through the return
value of the functions, if the request is synchronous (change channel, output power, etc) and indirectly,
through SAPs for asynchronous events (data confirm, ED/CCA confirm, data indication, timeout
indication). Both SAPs (data and management) pass information to the application using a messaging
system. The data structures used by this system are described below.
typedef enum smacMessageDefs_tag
{
gMcpsDataCnf_c,
gMcpsDataInd_c,
gMlmeCcaCnf_c,
gMlmeEdCnf_c,
gMlmeTimeoutInd_c,
gMlme_UnexpectedRadioResetInd_c,
}smacMessageDefs_t;
The above enumeration summarizes the types of messages passed through SAPs. As mentioned earlier,
there are data confirm, data indication (data layer), CCA confirm, ED confirm, timeout indication and
unexpected radio reset indication (management layer) messages. Each message type is accompanied by
corresponding message data. The main structures that build the message data are described below.
Table 2-1. Message Types and Associated Data Structures
Index Message Type
1 gMcpsDataCnf_c smacDataCnf_t Contains a smacErrors_t ele me nt. See
2 gMcpsDataInd_c smacDataInd_t u8LastRxRssi
3 gMlmeCcaCnf_c smacCcaCnf_t Contains a smacErrors_t element. See
Associated Data
Structures
Description
Section 2.2.8, “smacErrors_t”
value indicating th e RSSI obtai ned during
the reception
pRxPacket
pointer to the packet passed as
parameter to MLMERXEnableRequest.
Section 2.2.8, “smacErrors_t”
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 2-17
Page 20
Software Architecture
T able 2-1. Message Types and Associated Data Structures
Index Message Type
4 gMlmeEdCnf_c smacEdCnf_t status
5 gMlmeTimeoutIn
d_c
6 gMlme_Unexpect
edRadioResetIn
d_c
Associated Data
Structures
This is a smacErrors_t element. If PHY
succesfully performs the ED it’s value will
be gErrorsNoError_c
energyLevel
The value of the energy level register.
energyLeveldB
The value of the energy l evel converted to
dBm.
scannedChannel
The channel number of the scanned
channel.
none -
none -
Description
All taken into consideration, the two types of messages used by the SMAC to application SAPs have the
following form:
typedef struct smacToAppMlmeMessage_tag
{
smacMessageDefs_t msgType;
uint8_t appInstanceId;
union
{
smacCcaCnf_t ccaCnf;
smacEdCnf_t edCnf;
}msgData;
} smacToAppMlmeMessage_t;
typedef struct smacToAppDataMessage_tag
{
smacMessageDefs_t msgType;
uint8_t appInstanceId;
union
{
smacDataCnf_t dataCnf;
smacDataInd_t dataInd;
}msgData;
} smacToAppDataMessage_t;
The SMAC to application SAP handlers are function pointers of a special type. When application specifies
the functions to handle asynchronous responses, the SAP handlers aquire the value of those functions.
Below are the definitions of the handlers.
typedef smacErrors_t ( * SMAC_APP_MCPS_SapHandler_t)(smacToAppDataMessage_t * pMsg,
instanceId_t instanceId);
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
2-18 Freescale Semiconduct or
Page 21
Software Architec t ure
typedef smacErrors_t ( * SMAC_APP_MLME_SapHandler_t)(smacToAppMlmeMessage_t * pMsg,
instanceId_t instanceId);
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 2-19
Page 22
Software Architecture
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
2-20 Freescale Semiconduct or
Page 23
Chapter 3
Primitives
The following sections provide a detailed description of MKW01 SMAC primitives associated with the
MKW01 SMAC application API.
3.1 MCPSDataRequest
This data primitive is used to send an over-the-air (OTA) packet. This is an asynchronous function, which
means it asks the MKW01 SMAC to transmit an OTA packet, but transmission could continue after the
function returns.
Prototype
smacErrors_t MCPSDataRequest(txPacket_t *psTxPacket);
Arguments
txPacket_t *psTxPacket Pointer to the packet to be transmitted.
Returns
gErrorNoError_c Everything is ok and the transmission will be performed.
gErrorOutOfRange_c One of the members in the pTxMessage structure is out of range (not
valid buffer size or data buffer pointer is NULL).
gErrorBusy_c The radio is performing another action and could not attend this
request.
gErrorNoValidCondition_c The MKW01 SMAC has not been initialized.
gErrorNoResourcesAvailable_c The PHY cannot process an MKW01 SMAC request, so MKW01
SMAC cannot process it, or the memory manager is unable to
allocate another buffer.
Usage
• SMAC must be initialized before calling this function.
• Declare a variable of the type smacErrors_t to save the result of the function execution.
• Prepare the txPacket_t parameter as explained in Section 2.2.6, “txPacket_t” declaration and
usage.
• Call the MCPSDataRequest function.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 3-21
Page 24
Primitives
• If the result of the call of the function is different than gErrorNoError_c, the application should
handle the error returned. For instance, if the result is gErrorBusy_c the application should wait for
the radio to finish a previous operation.
uint8_t TxDataBuffer[gMaxSmacSDULength_c + sizeof(txPacket_t)];
txPacket_t *TxPacket;
smacErrors_t smacError;
...
TxPacket = (txPacket_t*)TxDataBuffer;
TxPacket->u8DataLength = payloadLength;
//Copy the data to send into the smacPdu of the packet
FLib_MemCpy(TxPacket->smacPdu.smacPdu, bufferToSend, payloadLength);
smacError = MCPSDataRequest(TxPacket);
...
Implementation
This MCPSDataRequest primitive creates a message for the PHY task and fills it in respect to the user
configurations prior to this call and to the information contained in the packet.
3.2 MLMETXDisableRequest
This function places the radio into stand-by and the PHY and SMAC state machines into idle, if current
operation is TX. It does not explicitly check if SMAC is in a transmitting state, but it clears the SMAC
buffer containing the packet to be sent, which makes it ideal for using when application wants to switch
from TX to idle.
Prototype
void MLMETXDisableRequest(void);
Arguments
None.
Returns
None: The function will forcibly set the transceiver to standy by and the PHY and SMAC state machines
to idle, so not return value is needed.
Usage
Call MLMETXDisableRequest().
Implementation
This primitive creates a message for PHY, sets message type as set transceiver state request, with value of
force transceiver off. After passing the message to PHY, SMAC checks if a TX is in progress and clears
the buffer containing the packet.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
3-22 Freescale Semiconduct or
Page 25
Primitives
3.3 MLMEConfigureTxContext
This function aids the user in enabling/disabling the “LBT” and “AA” mechanisms and also to configure
the number of retries in case channel is found busy or no acknowledgement message is received.
Prototype
smacErrors_t MLMEConfigureTxContext(txContextConfig_t* pTxConfig);
Arguments
txContextConfig_t* pTxConfig: pointer to a configuration structure containing the information described
above.
Returns
gErrorNoError_c: The desired configuration is applied succesfully.
gErrorNoValidCondition_c: The number of retries is set but the corresponding mechanism boolean is set
to FALSE.
gErrorOutOfRange_c: The number of retries exceeds gMaxRetriesAllowed_c.
Usage
• Declare a structure of txContextConfig_t type.
• Set the desired values to the members.
•Call MLMEConfigureTxContext with the address of the declared structure as parameter.
• Capture the return value in a smacErrors_t variable and handle the result.
txContextConfig_t txConfigContext;
txConfigContext.autoAck = TRUE; //”AA” is enabled
txConfigContext.ccaBeforeTx = FALSE; //”LBT” is disabled
txConfigContext.retryCountAckFail = 0;// no retries in case no ACK is received
txConfigContext.retryCountCCAFail = 0;// no retries in case of channel busy
smacErrors_t err = MLMEConfigureTxContext(&txConfigContext);
...
Implementation
This primitive configures the way SMAC will hand le data requests and responses from PHY according to
the parameters described by the txContextConfig_t structure. Also, requests forwarded by SMAC to PHY
depend on addressing and txContextConfig_t information.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 3-23
Page 26
Primitives
3.4 MLMERXEnableRequest
Places the radio into receive mode on the channel pre-selected by MLMESetChannelRequest ().
Prototype
smacErrors_t MLMERXEnableRequest(rxPacket_t *gsRxPacket, uint32_t u32Timeout);
Arguments
rxPacket_t *gsRxPacket: Pointer to the structure where the reception results will be stored.
uint32_t u32Timeout: 32-bit tim eout value in sym bol duration. One symbol duration is equivalent to a 16
us duration.
Returns
gErrorNoError_c Everything is ok and the reception will be performed
gErrorOutOfRange_c One of the members in the rxPacket_t structure is out of range (not
valid buffer size or data buffer pointer is NULL).
gErrorBusy_c The radio is performing another action and could not attend this
request.
gErrorNoValidCondition_c The MKW01 SMAC has not been initialized.
gErrorNoResourcesAvailable_c The PHY cannot process a MKW01 SMAC request, so the
MKW01 SMAC cannot process it.
Usage
• SMAC must be initialized before calling this function.
• Declare a variable of the type smacErrors_t to save the result of the function execution.
• Prepare the rxPacket_t parameter as explained in Section 2.2.2, “rxPacket_t” declaration and
usage.
• Call MLMERXEnableRequest function.
• If the result of the call of the function is different to gErrorNoError_c, the application may handle
the error returned. For instance, if the result is gErrorBusy_c the application should wait for the
radio to finish a previous operation.
uint8_t RxDataBuffer[gMaxSmacSDULength_c + sizeof(rxPacket_t)];
rxPacket_t *RxPacket;
smacErrors_t smacError;
RxPacket = (rxPacket_t*)RxDataBuffer;
RxPacket->u8MaxDataLength = gMaxSmacSDULength_c;
smacError = MLMERXEnableRequest(RxPacket, 0);
...
• The return of anything different than gErrorNoError_c implies that the
receiver did not go into receive mode.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
3-24 Freescale Semiconduct or
NOTE
Page 27
Primitives
• 32-bit timeout value of zero causes the receiver to never timeout and
stay in receive mode until a valid data packet is received or the
MLMERXDisableRequest function is called.
• To turn off the receiver before a valid packet is received, the
MLMERXDisableRequest call can be used.
• If timeout is not zero and a valid packet with length greater than
u8MaxDataLength is received, SMAC will send a data indication
message and will set rxAbortedStatus_c in the rxStatus_t field of the
rxPacket_t variable.
Implementation
This primitive creates a mess age for PHY, completes the message with the a ppropriate values a nd fills the
timeout field with the value passed through the timeout parameter. If this value is 0, SMAC will create a
set PIB request, asking PHY to enable the gPhyPibRxOnWhenIdle attribute.
3.5 MLMERXDisableRequest
Returns the radio to idle mode from receive mode.
Prototype
smacErrors_t MLMERXDisableRequest(void);
Arguments
None
Returns
gErrorNoError_c The request was processed and the transceiver is in idle.
gErrorNoValidCondition_c The radio is not in RX state, or SMAC is not initialized.
gErrorBusy_c The radio is performing another action and could not attend this request.
Usage
Call MLMERXDisableRequest ()
NOTE
This function can be used to turn off the receiver before a timeout occurs or
when the receiver is in the always-on mode.
Implementation
This function creates a message for PHY and if the timeout value from MLMERXEnableRequest was 0,
the message is filled as a set PIB reques t, requiring the gPhyPibRxOnWhenIdle to be se t to 0. If the timeout
value is greater than 0, the message is filled as a set transceiver state request, disabling the receiver.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 3-25
Page 28
Primitives
It aborts the current requested action, puts the PHY in the idle state, and sets the transceiver in standby
mode. It also disables any previous timeout programmed.
3.6 MLMELinkQuality
This function returns an integer value that is link quality value from the last received packet, offering
information on how good is the “link” between the transmitter and the receiver. The LQI value is between
0 and 255, where 0 means bad “link” and 255 is the exact opposite.
Prototype
uint8_t MLMELinkQuality(void);
Arguments
None.
Returns
uint8_t 8-bit value representing the link quality value. Returns the result in
smacLastDataRxParams.linkQuality.
Zero The MKW01 SMAC has not been initialized.
Usage
Call the MLMELinkQuality()
Implementation
This function reads the stored value in smacLastDataRxParams.linkQuality . This element contains the LQI
value calculated by the transceiver and interpreted by the PHY layer during the last reception.
3.7 MLMESetChannelRequest
This sets the frequency on which the radio will transmit or receive.
Prototype
smacErrors_t MLMESetChannelRequest(channels_t newChannel);
Arguments
channels_t newChannel: An 8-bit value that represents the requested channel.
Returns
gErrorNoError_c The channel set has been performed.
gErrorBusy_c The MKW01 SMAC is busy in other radio activity like
transmitting/receiving data or performing a channel scan.
gErrorOutOfRange_c The requested channel is not valid.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
3-26 Freescale Semiconduct or
Page 29
gErrorNoValidCondition_c The MKW01 SMAC is not initialized.
Usage
Call the function MLMESetChannelRequest(newChannel);
NOTE
Be sure to enter a valid channel between 0 and
(gTotalChannels - 1).
3.8 MLMEGetChannelRequest
This function returns the current channel.
Prototype
channels_t MLMEGetChannelRequest(void);
Arguments
Primitives
None
Returns
channels_t (uint8_t) The current RF channel.
Usage
Call MLMEGetChannelRequest();
3.9 MLMEPAOutputAdjust
This function adjusts the output power of the transmitter.
Prototype
smacErrors_t MLMEPAOutputAdjust(uint8_t u8PaValue);
Arguments
uint8_t u8PaValue 8-bit value for the output power desired. Values 1– 31 are required.
Returns
gErrorOutOfRange_c u8Power exceeds the maximum power value gMaxOutputPower_c
(0x1F).
gErrorBusy_c The MKW01 SMAC is busy or PHY is busy.
gErrorNoError_c The action is performed.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 3-27
Page 30
Primitives
gErrorNoValidCondition_c The MKW01 SMAC is not initialized.
Usage
Call MLMEPAOutputAdjust(u8PaValue);
NOTE
Be sure to enter a valid value for the PA output adjust.
3.10 MLMEPhySoftReset
The MLMEPhySoftReset function is called to perform a software reset to the PHY and MKW01 SMAC
state machines.
Prototype
smacErrors_t MLMEPHYSoftReset(void);
Arguments
None
Returns
gErrorNoError_c If the action is performed.
gErrorNoValidCondition_c If the MKW01 SMAC is not initialized.
Usage
Call MLMEPHYSoftReset();
Implementation
This function creates a set transceiver state request message with force transceiver off field set and sends
it to PHY.
3.11 MLMEScanRequest
This function creates an ED request message to the PHY. If the channel passed as parameter is different
from the current channel, this function changes the channel before requesting the ED.
Prototype
smacErrors_t MLMEScanRequest(channels_t u8ChannelToScan);
Arguments
channels_t u8ChannelToScan: Channel to be scanned.
Returns
gErrorNoError_c Everything is normal and the scan will be performed.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
3-28 Freescale Semiconduct or
Page 31
Primitives
gErrorBusy_c The radio is performing another action.
gErrorNoValidCondition_c The MKW01 SMAC has not been initialized.
Usage
Call the function with the selected channel to be scanned.
MLMEScanRequest(u8ChannelToScan);
NOTE
Be sure to enter a valid channel. Be sure to switch back to the previous
channel after receiving the result.
3.12 MLMECcaRequest
This function creates a CCA request message and sends it to the PHY. CCA is performed on the active
channel (set with MLMESetChannelRequest). The result will be received in a message passed through the
SMAC to application management SAP.
Arguments
None
Returns
gErrorNoValidCondition_c The MKW01 SMAC has not been initialized.
gErrorBusy_c Either SMAC or PHY is busy and can not process the request.
gErrorNoError_c Everything is normal and the request was processed.
Usage
Call the function. The application can store the return value in a smacErrors_t variable and handle the error
in case it occurs. For example, if the return value is gErrorBusy_c, the application can wait on this value
until SMAC becomes idle.
smacErrors_t ReturnValue;
ReturnValue = MLMECcaRequest();
//Handle return value
...
Implementation
This function creates a message for PHY requesting a CCA on the currently selected channel. After
passing the message through the SAP, SMAC changes it’s state to
mSmacStatePerformingCca_c.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 3-29
Page 32
Primitives
3.13 MLMESetPreambleLength
This function updates the number of repetitions the preamble has.
Arguments
uint16_t u16preambleLength The new value of the number of preamble repetitions.
Returns
gErrorNoValidCondition_c SMAC was not initialized.
gErrorBusy_c SMAC is busy and cannot process the request.
gErrorNoError_c The request was processed.
Usage
Call the function. The application can store the return value in a smacErrors_t variable and handle the error
in case it occurs. For example, if the return value is gErrorBusy_c, the application can wait on this value
until SMAC becomes idle.
3.14 MLMESetSyncWordSize
This function updates the size of the synchronization word (maximum 8 bytes).
Arguments
uint8_t u8syncWordSize The size in bytes of the synchronization word.
Returns
gErrorNoValidCondition_c SMAC was not initialized.
gErrorBusy_c SMAC is busy and cannot process the request.
gErrorOutOfRange_c The requested size is outside the valid range.
gErrorNoError_c The request was processed.
Usage
Call the function. The application can store the return value in a smacErrors_t variable and handle the error
in case it occurs. For example, if the return value is gErrorBusy_c, the application can wait on this value
until SMAC becomes idle.
3.15 MLMESetSyncWordValue
This function updates the value of the synchronization word.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
3-30 Freescale Semiconduct or
Page 33
Primitives
Arguments
uint8_t* u8SyncWordValue Pointer to the buffer containing the new values for the synchronization
word.
Returns
gErrorNoValidCondition_c SMAC was not initialized.
gErrorBusy_c SMAC is busy and cannot process the request.
gErrorNoError_c The request was processed.
Usage
Call the function. The application can store the return value in a smacErrors_t variable and handle the error
in case it occurs. For example, if the return value is gErrorBusy_c, the application can wait on this value
until SMAC becomes idle.
3.16 MLMEPacketConfig
This function calls the above three functions with the parameters configured in the packetConfig_t
structure passed by address as the parameter.
Arguments
packetConfig_t* pPacketCfg Pointer to the packetConfig_t structure containing the new values for
preamble length, synchronization word size and values.
Returns
gErrorNoValidCondition_c SMAC was not initialized.
gErrorBusy_c SMAC is busy and cannot process the request.
gErrorOutOfRange_c One of the configuration parameters is out of range.
gErrorNoError_c The request was processed.
Usage
Call the function. The application can store the return value in a smacErrors_t variable and handle the error
in case it occurs. For example, if the return value is gErrorBusy_c, the application can wait on this value
until SMAC becomes idle.
3.17 MLMESetAdditionalRFOffset
This function sets the frequency drift in number of Fsteps (57 Hz on 30MHz platforms, 61 Hz on 32MHz
platforms) passed as parameter to fine tune the central frequency of the channel on MKW01 platforms.
The frequency is updated at the next MLMESetChannelRequest call.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 3-31
Page 34
Primitives
Arguments
uint32_t additionalRFOffset Signed value of the drift converted to uint32_t.
Returns
gErrorNoValidCondition_c SMAC was not initialized.
gErrorNoResourcesAvailable_c The calibration feature was not enabled.
gErrorNoError_c Everything went fine.
Usage
Use Connectivity Test (continuous tx unmodulated) and a spectrum analyzer to determine real channel
frequency. Compute the drift and divide to Fstep. Call this function with the result. The application can
store the return value in a smacErrors_t variable and handle the error in case it occurs. For example, if the
return value is gErrorBusy_c, the application can wait on this value until SMAC becomes idle.
3.18 MLMEGetAdditionalRFOffset
This function returns the latest stored frequency drift, or 0 if the feature is not enabled.
Arguments
None.
Returns
uint32_t The signed value of the drift converted to uint32_t.
3.19 SMACSetShortSrcAddress
This function creates a message of set PIB request type, requesting PHY to change the short source address
of the node. If the message i s passe d succesfully to P HY, SMAC will set it’s own source address variable
to the new value, so that when SMACFillHeader is called, the updated data is filled into the header.
Arguments
uint16_t nwShortAddress: The new value of the 16 bit node address.
Returns
gErrorNoResourcesAvailable_c The PHY layer can not handle this request.
gErrorBusy_c PHY is busy and can not process the request.
gErrorNoError_c Everything is normal and the request was processed.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
3-32 Freescale Semiconduct or
Page 35
Primitives
Usage
Call the function with the desired address. The application can store the return value in a smacErrors_t
variable and handle the error in case it occurs. For example, if the return value is gErrorBusy_c, the
application can wait on this value until PHY becomes idle.
smacErrors_t ReturnValue;
ReturnValue = MLMESetShortSrcAddress(0x1234);
//Handle return value
...
Implementation
This function creates a message for PHY requesting to set the source address pib to the value passed as
parameter. If the request is processed, the value is also stored in the SMAC layer for fast processing in case
a call to SMACFillHeader is performed.
3.20 SMACSetPanID
This function creates a message of set PIB request type, requesting PHY to change the short P AN address
of the node. If the message is passed succesfully to PHY, SMAC will set it’ s own PAN address variable to
the new value, so that when SMACFillHeader is called, the updated data is filled into the header.
Arguments
uint16_t nwShortPanID: The new value of the 16 bit PAN address.
Returns
gErrorNoResourcesAvailable_c The PHY layer can not handle this request.
gErrorBusy_c PHY is busy and can not process the request.
gErrorNoError_c Everything is normal and the request was processed.
Usage
Call the function with the desired address. The application can store the return value in a smacErrors_t
variable and handle the error in case it occurs. For example, if the return value is gErrorBusy_c, the
application can wait on this value until PHY becomes idle.
smacErrors_t ReturnValue;
ReturnValue = MLMESetShortPanID(0x0001);
//Handle return value
...
Implementation
This function creates a message for PHY requesting to set the PAN address pib to the value passed as
parameter. If the request is processed, the value is also stored in the SMAC layer for fast processing in case
a call to SMACFillHeader is performed.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 3-33
Page 36
Primitives
3.21 SMACFillHeader
This function has no interaction with the PHY layer. It’s purpose is to aid the application in configuring
the addressing for packet to be sent. The function will fill the packet header with the updated addressing
and hard-coded configuration values and will add the destination address passed as parameter.
Arguments
smacHeader_t* pSmacHeader : Pointer to the SMAC header that needs to be filled with addressing and
configuration information.
uint16_t destAddr : The 16 bit destination address.
Returns
None.
Usage
Call the function if it’s the first time the application uses the txPacket_t variable, or if the destination
address must be changed.
uint8_t TxDataBuffer[gMaxSmacSDULength_c + sizeof(txPacket_t)];
txPacket_t *TxPacket;
smacErrors_t smacError;
...
TxPacket = (txPacket_t*)TxDataBuffer;
SMACFillHeader(&(TxPacket->smacHeader), gBroadcastAddress_c);
TxPacket->u8DataLength = payloadLength;
//Copy the data to send into the smacPdu of the packet
FLib_MemCpy(TxPacket->smacPdu.smacPdu, bufferToSend, payloadLength);
smacError = MCPSDataRequest(TxPacket);
...
Implementation
This function fills the smacHeader with default, hard-coded frame control and sequence number values.
Also, it adds the addressing information (configured by calling MLMESetShortSrcAddress and
MLMESetPanID) and the destination address passed as parameter.
3.22 SMAC_SetIVKey
This function sets the initial vector and encryption key for the encryption process if gSmacUseSecurity_c
is defined.
Arguments
uint8_t* KEY Pointer to a 16 byte buffer containing the key.
uint8_t* IV Pointer to a 16 byte buffer containing the initial vector.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
3-34 Freescale Semiconduct or
Page 37
Primitives
Returns
None.
Usage
Declare two buffers each with 16 byte size. F ill one of them with key information and the other with initial
vector information. Call this function with pointers to the buffers as parameters.
3.23 Smac_RegisterSapHandlers
This function has no interaction with the PHY layer. It’s purpose is to create a communication bridge
between SMAC and application, so that SMAC can respond to asynchronous requests.
Arguments
SMAC_APP_MCPS_SapHandler_t pSMAC_APP_MCPS_SapHandle: Pointer to the function handler
for data layer response to
asynchronous requests.
SMAC_APP_MLME_SapHandler_t pSMAC_APP_MLME_SapHandler: Pointer to the function handler
for management layer response
to asynchronous requests (ED/
CCA requests).
instanceId_t smacInstanceId: The instance of SMAC for which the SAPs are registered. Always use 0 as
value for this parameter since this version of SMAC does not support
multiple instances.
Returns
None
Usage
Implement two functions that meet the constraints of the function pointers. Then call
Smac_RegisterSapHandlers with the names of the functions.
smacErrors_t smacToAppMlmeSap(smacToAppMlmeMessage_t* pMsg, instanceId_t instance)
{
switch(pMsg->msgType)
{
case gMlmeEdCnf_c:
...
break;
case gMlmeCcaCnf_c:
...
break;
case gMlmeTimeoutInd_c:
...
break;
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
Freescale Semiconduc tor 3-35
Page 38
Primitives
default:
break;
}
MEM_BufferFree(pMsg);
return gErrorNoError_c;
}
smacErrors_t smacToAppMcpsSap(smacToAppDataMessage_t* pMsg, instanceId_t instance)
{
switch(pMsg->msgType)
{
case gMcpsDataInd_c:
...
break;
case gMcpsDataCnf_c:
...
break;
default:
break;
}
MEM_BufferFree(pMsg);
return gErrorNoError_c;
}
void InitApp
{
...
Smac_RegisterSapHandlers(
(SMAC_APP_MCPS_SapHandler_t)smacToAppMcpsSap,
(SMAC_APP_MLME_SapHandler_t)smacToAppMlmeSap,
0)
...
}
Implementation
This function associates the SMAC internal function handlers with the ones registered by the application.
Whenever an asynchronous response needs to be passed from SMAC to application, the internal handlers
are called, which in turn call the ones defined by the application.
MKW01 Simple Media Access Controller (SMAC) Reference Manual, Rev. 0.0
3-36 Freescale Semiconduct or
Loading...