Microchip CoAP Stackww1.microchip.com/downloads/en/AppNotes/00002512A.pdf · coap – constrained...

AN2512Microchip CoAP Stack

INTRODUCTION TO IoTWhether called Internet of Things (IoT), Industrial IoT,or Industrial Ethernet, today any “thing” can beconnected and controlled via Internet: garage doors,home appliances, HVAC systems, lighting sensors andan endless array of other common products. Thisplaces increased importance on creating products thatare easily connected and provide intelligent controlwithin a simplified development environment. Theresult is a completely transformed end user experienceobtained by easily and efficiently controlling,monitoring and managing commercial, industrial andresidential buildings and products, as shown inFigure 1.

The objective of this application note is to describesolutions for making “things” talk to each other. Themain protocol that enables this communication is theConstrained Application Protocol (CoAP). This protocolprovides features similar to HTTP, tailored forconstrained devices like embedded microcontrollers.

FIGURE 1: IoT SOLUTION

Author: Janaki KurugantiMicrochip Technology Inc.

2017 Microchip Technology Inc. DS00002512A-page 1

AN2512
Microchip’s Wired IoT Solutions
IoT has vastly spread into both wired and wireless markets.

The focus of this application note is to highlightMicrochip’s wired IoT solutions. The link belowprovides detailed information on Microchip’s “Ethernetof Everything” solutions: http://www.microchip.com/design-centers/ethernet/ethernet-of-everything.

IoT FIRMWAREThe firmware for an IoT device has to provide astandardized means for connectivity while abstractingapplication functionality. Figure 2 below shows thearchitectural overview of the IoT firmware.

FIGURE 2: IoT FIRMWARE ARCHITECTURE

As shown in Figure 2, TCP/IP Stack handlesconnectivity to the Internet. CoAP provides a commonprotocol for devices to communicate in the network.The user code can handle the aspects customized forend application.

TCP/IP Protocol SuiteThe TCP/IP Protocol suite has four layers ofabstraction: application, transport, network, andnetwork interface layer or link layer. An architecturaloverview of the TCP/IP Stack is shown in Figure 3.The packet received by the link layer is propagated tothe upper layers. During this process, the headerinformation is separated and used by intermediatelayers while the data finally reaches the applicationlayer. Similarly, the transmit data travels in the reversedirection from application layer to the link layer whileintermediate layers add their header information.

FIGURE 3: ARCHITECTURAL OVERVIEW OF TCP/IP STACK

Microchip provides several TCP/IP stacks. For moreinformation, refer to http://www.microchip.com/SWLibraryWeb/product.aspx?product=TCPIPSTACK.

DS00002512A-page 2 2017 Microchip Technology Inc.

http://www.microchip.com/design-centers/ethernet/ethernet-of-everything




http://www.microchip.com/SWLibraryWeb/product.aspx?product=TCPIPSTACK

http://www.microchip.com/SWLibraryWeb/product.aspx?product=TCPIPSTACK

AN2512
IoT ProtocolsVarious protocols exist for IoT communication. Someexamples, in addition to CoAP, include RESTful HyperText Transfer Protocol (HTTP) and Message QueuingTelemetry Protocol (MQTT). All these protocols have aminimum requirement of ~100 KiB flash and ~10 KiBRAM. Devices that meet these requirements are calledClass 1 or C1 devices.The following are some key characteristics of CoAPwhen compared to other IoT protocols:• CoAP uses User Datagram Protocol (UDP) as its
transport layer protocol whereas HTTP andMQTT use Transmission Control Protocol (TCP).UDP is lighter than TCP because it isconnectionless and does not includeacknowledgment. As a result, CoAP is morelightweight when compared to HTTP and MQTT.

• The message technique used by CoAP is Request/Response. The client requests for data/action while the server responds. In comparison, MQTT implements Publish/Subscribe mechanism in addition to Request/Response. This enables a client to subscribe for server resource updates.

CoAP – CONSTRAINED APPLICATION PROTOCOL

Introduction to CoAPCoAP is a specialized web transfer protocol mainlyintended for constrained nodes and networks in IoT. Itis designed for M2M applications, such as smartenergy and building automation. CoAP architecture isbuilt based on the REST model. So, this protocol isvery similar to HTTP. CoAP uses the client/servermodel and request/response to send and receive data.

CoAP Messaging TechniquesCoAP is an IoT protocol which runs on top of the UDPtransport layer. The messaging techniques for CoAPare based on the request/response model. This isphrased as the exchanging of the data between twoUDP endpoints. One of the characteristics of UDP isthat there is no confirmation of the message delivery.However, CoAP has enjoined its messagingtechniques above UDP in order to provide messagedelivery confirmation if required by the user application.This feature is achieved as explained below:CoAP has four types of messages: • Confirmable (CON) Messages• Non-Confirmable (NON) Messages • Acknowledgment (ACK) • Reset (RST)

CONFIRMABLE (CON) MESSAGESMessages that require a response with either ACK orRST messages are called confirmable messages.Since the response for the request is received, thisensures that the message is delivered; therefore, theseare also known as reliable messages. CON messagesare retransmitted with an exponential timeout, until theACK or RST messages are received or by default of 60seconds from the start of transmission of the first CONmessage. The figure below shows an example of aCON message.

FIGURE 4: EXAMPLE OF CON MESSAGE

NON-CONFIRMABLE (NON) MESSAGESMessages that are not forced to respond are calledNON messages. As there is no confirmation of thedelivery for these messages, they are also calledunreliable messages.

FIGURE 5: EXAMPLE OF NON-CONFIRMABLE MESSAGE

ACKNOWLEDGMENT (ACK) MESSAGESACK messages are responses for the CON messages,and provide confirmation that the CON message isreceived. These messages do not indicate if thereceived CON message is a success or a failure;however, the success and failure can be appended tothe ACK message which is referred to as piggybackresponse.


AN2512
RESET (RST) MESSAGESRST messages are responses for both CON and NONmessages. An RST message indicates that the specificmessage was received, but some context is missing toproperly process it.
CoAP RESPONSE MESSAGE TYPESIn general, CON messages require response. CoAPsupports two mechanisms of response for CONmessages: piggyback response and separateresponse.

Piggyback ResponsesPiggyback responses are sent immediately along withthe ACK. The response could be either a success or afailure, which is appended in the ACK packet. Figure 6below illustrates the behavior of a piggyback response.

FIGURE 6: PIGGYBACK RESPONSE BEHAVIOR

Separate ResponsesSeparate responses are sent when the ACK for arequest is sent immediately i.e., the packet is receivedproperly and processed. After some time, the datarequested earlier is responded to with a CON. In orderto relate the response to the request sent, the separateresponse uses the same token field that was used inthe request. Figure 7 illustrates the behavior of aseparate response.

FIGURE 7: SEPARATE RESPONSE BEHAVIOR

CoAP Message FormatThe semantic of the CoAP protocol is as shown inFigure 8 below.

FIGURE 8: SEMANTIC OF THE CoAP PROTOCOL


AN2512
There are several fields that are transferred in a CoAPpacket. Listed below are the definitions orcharacteristics of each field in the message format:• CoAP Header: CoAP message begins with a 4-
byte header- Ver – [Version] is a 2-bit integer. Ver is

indicated as ‘01’ for the implementationsbased on RFC 7252.

- T – [Message Type] is a 2-bit integer.There are four message types:

- Confirmable (0)- Non-Confirmable (1)- Acknowledgment (2) - Reset (3)- TKL – [Token Length] is a 4-bit integer.

TKL indicates the length of the token fieldwhich varies from (0-8) bytes.

- Code – [Request/Response Codes] isa 1-byte integer. Code indicates the Requestcodes, Response codes – Success, ClientError and Server Error.

- Message ID is a 2-byte integer. Message IDis a unique integer in the network order,which is used to recognize duplication of themessage in the network. Messageduplication handling is described in Section“Message Duplication”.

• Following the CoAP Header is the (0-8) bytesToken field. Token is used to relate between therequest and response.

• Following the Token field are the Options, ifany.There can be as many Options defined fromthe CoAP Options as in RFC 7252, and they areadded in the Type-Length-Value (TLV) format.

• Following the Options is the Payload, if any. A payload marker (0xFF) of 1-byte is used to indi-cate the end of options and start of the payload.

Message Duplication

In case of CON messages, the recipient may receive multiple messages with the same message ID and source endpoint in a situation where acknowledgment is missing. The recipient should acknowledge all the duplicate packets. These idempotent messages can be handled in different ways:

- The recipient might cache the response for the request and if the duplicate request is received, it can be acknowledged in an idempotent fashion; or,

- For the memory constrained nodes, the recipient can process and answer all the retransmissions of the duplicate packets without caching the responses.

It is up to the endpoint choice to either considerduplicate processing which is less expensive or keeptrack of message IDs, save the response and reply withit.

CoAP Message CodesCoAP implements RESTful architecture, is designed tointerface with HTTP for web interactions and intendedfor constrained devices. Similar to HTTP, CoAP hasimplemented two types of message codes: RequestCodes and Response Codes. The behavior of theCoAP codes are similar to the HTTP codes.

CoAP REQUEST CODESThere are four types of CoAP request codes:• GET – This method is used to request the end-

point (server) to return resource information identified by the requested URI

• PUT – This method is used to request the end-point (server) to update the resource information identified by the requested URI

• POST – This method is used to request the end-point (server) to create a resource identified by the requested URI.

• DELETE – This method is used to request the endpoint (server) to delete the resource identified by the requested URI

CoAP RESPONSE CODESThere are three categories of CoAP response codes:1. Success – These response codes are sent if

the request is successfully received, properlyunderstood, processed and responded to.These response codes start with ‘2’.

Example Success codes: - 2.05 Content – Response for only GET

requests with a payload in response- 2.04 Changed – Response for only PUT or

POST requests, that the resource information is updated with information provided in the request

2. Client Failure – These response codes are sentif the request received has an erroneous syntax.These response codes start with ‘4.’

Example Client Failure codes:- 4.02 Bad Option – Response if the request

has bad/unsupported option by the endpoint (server)

- 4.04 Method Not Allowed – Response if the request has a bad syntax

3. Server Failure – These response codes are sentif the server failed to fulfill an apparently validrequest. These response codes start with ‘5.’

Example Server Failure codes:- 5.02 Bad Gateway – Response if the gateway

has a failure


AN2512
CoAP OptionsAs the name says, options are optional. However, inorder to be more specific to reach or get to theinformation representation of a particular resource,each message carries CoAP options. Options are totedby both request and response messages. Themessage can consist of one or more options in itspacket. As per the implementation RFC 7252, there areseveral CoAP Options supported. The list of CoAPOptions is sectioned in RFC 7252– CoAP Options.Below, there are listed a few examples of helpful CoAPoptions: • Content – FormatA CoAP endpoint (CoAP server) can support multiplelanguages or media types just like HTTP. Like JSON,PLAIN/TEXT, CBOR, and XML etc. Each media type isassigned an integer ranging from 0-65535. Theassignment for the media type is handled by IANA.CoAP content-format media type assignments areavailable here. The content-format option in a CoAPpacket indicates that the source endpoint payload isencoded in that particular media type.• URI – HostThe URI Host option in the packet infers that themessage is destined to that particular host.• URI – PathThe URI Path option specifies one segment of theabsolute path to the resource. The resource path of theendpoint is sent in by adding several URI Path optionsin a message.• URI – Port The URI Port option specifies the transport layer portnumber of the resource.• URI – Query The URI Query option specifies the one argumentparameterizing the resource. This option can be usedto narrow the request to a certain resource element.• AcceptThe Accept option in a message indicates that thesource endpoint can accept only a certain type ofcontent-format as its response.• Block2The Block2 option in a message is used mainly duringsending response data from GET request. Adding thisoption helps to render the data which is greater than1500 bytes (MTU size) from the CoAP endpoint inmultiple blocks without requiring IP fragmentation. Microchip’s CoAP stack supports the Block2 option fortransmit discovery process only. Block2 option isautomatically added in the discovery process if theresponse (body of the packet) is greater than 1000bytes.
The embedded code of an endpoint device mustimplement the functionality so that the CoAP optionsare added to the message in an ascending order basedon their CoAP option number, and delta encoding isused between the options.

CoAP DiscoveryThe resources hosting at the CoAP server endpointsneed to be discovered by the CoAP client endpoints.This is an important step for machine-to-machineapplications where there is minimum humanintervention. The client has to know all the resourcesthe server is providing, so that it can act based on that.Each CoAP server has a root node (./well-known/core)where it hosts all the discoverable resources.The client/server process for discovering resources isshown in Figure 9.

FIGURE 9: CLIENT/SERVER PROCESS FOR DISCOVERY OF RESOURCES

The CoAP client requests Confirmable GET messageon the root node of the server i.e., “./well-known/core”.The CoAP server responds to the resources. Theresponse for this request is always encoded in “LINK”content-format. i.e., the server always supports theLink content-format on root.

CoAP DISCOVERY – SUPPORTEclipse has developed a framework for CoAP in Javato support the user and interact with the CoAPendpoints. This is called Californium (cf) CoAPframework. It has created an add-on called Copper (cu)for the Mozilla Firefox web browser, which allows theuser (web browser) to act as a CoAP client and interactwith the CoAP server.


AN2512
Figure 10 shows the CoAP Discovery Graphical UserInterface (GUI) with the CoAP Server.
FIGURE 10: CoAP DISCOVERY GUI WITH CoAP SERVER

CoAP ResourcesResources are hosted by the CoAP server. These canbe accessed by the CoAP client by appending URIPath option in the message. From RFC 7252, theCoAP option number for URI Path is ‘11’. Addingmultiple URI Path options to the message directs to theresource. For example, the resource path can beillustrated as:• mchp/actuators/actuator1• mchp/sensors/sensor1From the above examples, any request action with theURI Path options directs to the resource, and if the URIPath is valid, the resource returns with a representationbased on the request.

CoAP QueriesQueries are also appended in the CoAP message. Thepurpose of having queries in a message is to narrowdown the search to reach a particular resource. TheCoAP option used to add queries is URI Query. FromRFC 7252, the CoAP option number for URI Path is‘15’. The semantic for queries is dependent upon theserver implementation. Conventionally, the queries aredefined as a key-value pair (KVP), or as a name-valuepair.

EXAMPLE OF CoAP QUERY IMPLEMENTATIONThe process of handling queries is based on the type ofkeys the message holds. If the CoAP message hasmore than one query, there are two different methodsof handling queries:• Logical AND Operation• Logical OR Operation


AN2512
Different Query KeysIf the message has two different keys in the queryoptions, the logical AND operation is performedbetween the two query values.
- Example – /mchp/actuators/actuator1?keyw=group1&domn=microchip&role=light

AND operation – The request is successful if all queryvalues are true.

Same Query Keys If the message has two same keys in the query options,the logical OR operation is performed between the twoquery values.

- Example - /mchp/actuators/actuator1?keyw=group3&keyw=group2

OR operation – The request is successful if eitherquery value is true.

Mixed Query KeysIf the message has a different query key and the samequery key in the CoAP query options, the logical ORoperation is performed between the two same querykey values, and logical AND operation between thedifferent query values.

- Example - /mchp/actuators/actuator1?keyw=group1&domn =microchip&keyw=group2

Both OR and AND operations – The request issuccessful if either keyw values are true AND domn istrue.

Microchip CoAP Stack Prospective FeaturesCurrently, few options are supported in the CoAP stack,such as URI_Path, URI_Query, URI_Host, Accept,Content-format and Block wise transfer (transmit only)for discovery process only. There are plans to extendthe CoAP stack to support some more options. Observe – RFC 7641Adding this option enables the CoAP clients tosubscribe the CoAP server resources and getsupdated whenever there is a change in the resourcewithout sending a request to the server.

MICROCHIP CoAP STACK APIs

Use the CoAP StackAn endpoint can be configured as a CoAP Server, aCoAP Client, or it can be both Server and Client.

ENDPOINT AS A SERVERTo configure endpoint as server, resources need to behosted by the server.• CoAP Server listens on UDP Port 5683• The call back handler on UDP port 5683 is void COAP_Receive (int length);

Any UDP packets on port 5683 are directed to theabove call back handler.Along with the CoAP library, MCC helps to generate themethods (APIs) for the four types of request codes(GET, PUT, POST and DELETE) for each resourceseparately. However, the data model for each resourcehas to be added by the user, as shown in Example 1.

EXAMPLE 1: GENERATING THE APIs FOR THE REQUEST CODES

Led.c [Resource files]

bool LedGetter (uint8_t idx)

bool LedPutter (uint8_t idx)

bool LedPoster (uint8_t idx)

bool LedDeleter (uint8_t idx)


AN2512
ENDPOINT AS A CLIENT
FIGURE 11: CREATING CoAP CLIENT REQUEST

The CoAP Client sends a request to the CoAP Server.The following are the steps required to send a request:1. Create the CoAP Option Table, as shown in

Example 2.

EXAMPLE 2: CREATING THE CoAP OPTION TABLE

2. Create the CoAP Payload Table, as illustrated inExample 3.

EXAMPLE 3: CREATING THE CoAP PAYLOAD TABLE

3. Assign the coapTransmit_t Object, asindicated in Example 4.

EXAMPLE 4: ASSIGNING THE coaptransmit_t OBJECT

4. Start the CoAP Packet, as shown in Example 5.error_msg COAP_Transmit(coapTransmit_t*ptr, coapTypes Type, coapCodes Code,bool Retransmission);The argument of the API describes:• ptr – Holds the information of the destination end

point (server). Example: IP Address, Token etc.• Type of message – Confirmable or Non-

Confirmable Messages• Request Code type – GET, PUT, POST, DELETE• Retransmission – True or False

EXAMPLE 5: STARTING THE CoAP PACKET

5. Send the CoAP Packet.Send the CoAP packet: error_msg COAP_Send();

void TransmitOptions () { COAP_AddURIPathOption(”mchp"); COAP_AddURIPathOption(”Led1"); COAP_AddContentFormatOption(TEXT_PLAIN); }

const OptionTypeHandler_t coapTransmitOptions []=

{

{TransmitOptions}

};

void TransmitPayload () { UDP_WriteSring(“,1,Led,1,”); }

const payload_t coapTransmitPayload []=

{

{TransmitPayload}

};

Note 1: COAP_CLIENT_SRC_PORT – 655202: COAP_CLIENT_DEST_PORT – 5683

coapTransmit_t requestPtr; requestPtr.destIP = MAKE_IPV4_ADDRESS (192, 168, 1, 20);

requestPtr.clientOption = coapTransmitOptions; requestPtr.clientPayload = coapTransmitPayload;

requestPtr.srcPort = COAP_CLIENT_SRC_PORT;

requestPtr.destPort = COAP_CLIENT_DEST_PORT;

COAP_Transmit (&requestPtr, CON, PUT, true);


AN2512
MICROCHIP CoAP STACK USING MPLAB® CODE CONFIGURATOR (MCC) The Microchip CoAP library is integrated with MPLAB®
Code Configurator (MCC) and is built on top of theTCP/IP Lite stack.

Hardware Configuration1. Connect the 40-pin PIC18F46K40 DIP at (J10). 2. Connect the ETH click board at mikroBus™ Slot

1 (J28).3. Connect the Ethernet Cable from ETH Click to

the router.4. Connect the Ethernet Cable from PC to the

same router in step 3.5. Power the High-Pin Curiosity Board using the

mini USB cable connected to PC.

Configure and Generate the CoAP Stack using MCC1. Open MPLAB X IDE. 2. Create a project for the PIC18F46K40 device,

for example: CoAP_TCPIPLite.X3. Launch the MCC plug-in using the MCC icon in

the top right corner in MPLAB X IDE, as shownin Figure 12. Alternatively, MCC can also belaunched by selecting Tools Embedded MPLAB Code Configurator v3 Open/ Close.

FIGURE 12: MCC PLUG-IN LAUNCH


AN2512
4. In Project Resources tab, select System
Module. Go to Easy Setup view (Figure 13): - Update the Oscillator Select to HFINTOSC

with HFFRQ = 64 MHz and CDIV = 1:1.- Update HF Internal Clock to 16 MHz

FIGURE 13: INTERNAL OSCILLATOR UPDATE

TCP/IP Configurations5. In the Device Resources tab (Figure 14), go to

the Libraries listed. Double click TCP/IP LiteLibrary to load the module.

FIGURE 14: LOADING TCP/IP LITE MODULE

6. In Project Resources tab, select TCP/IP Litemodule. This will display all the protocolssupported by the TCP/IP Lite stack.

- Option A: Static Configuration – UDP, IPv4, ICMP, ARP protocols should be selected (Figure 15).


AN2512
FIGURE 15: SELECTING PROTOCOLS FOR TCP/IP LITE MODULE (STATIC CONFIGURATION)
- Option B: Dynamic Configuration – UDP, DHCP, IPv4, ICMP, ARP protocols should be selected (Figure 16).

FIGURE 16: SELECTING PROTOCOLS FOR TCP/IP LITE MODULE (DYNAMIC CONFIGURATION)


AN2512
MAC Configurations7. In the Device Resources tab, go to the
Libraries listed. Expand Ethernet library anddouble click MAC to load the module(Figure 17).

FIGURE 17: LOADING THE MAC MODULE

8. In the Project Resources tab, select the MediaAccess Controller (MAC) module. This willdisplay the three different Ethernet controllers.Select the ENC28J60 Ethernet device(Figure 18). The default MAC address is:02:00:00:00:00:01.

FIGURE 18: SELECTING THE ETHERNET DEVICE

MAC Pin Configuration In Pin Manager, configure the MAC module Chip Select(CS) pin to Port RA3 (Figure 19).

FIGURE 19: CONFIGURING MAC CHIP SELECT PIN

MSSP1 Pin Configuration9. Unselect the default SDO1 pin – Port RC4

(Figure 20).

FIGURE 20: CONFIGURING MSSP1 PINS

Note: The ENC28J60 device is interfaced withthe microcontroller using SPI protocol.The MCC MAC module automaticallyloads the MSSP SPI module (SPIMode 0) compatible with the device.

Note: On the High-Pin Curiosity Board (HPC),the mikroBUS Click slot 1 has Port RA3 asthe Chip Select.

Note: On the High-Pin Curiosity Board (HPC),the mikroBUS Click slot 1 has SCK1, SDI1and SDO1 are at Port B1, B2 and B3respectively.

TABLE 1: PIN MANAGERModule in Pin

Manager Pin Function Direction

MSSP1 RB1 SCK1 outputMSSP1 RB2 SDI1 inputMSSP1 RB3 SDO1 output


AN2512
Timer ConfigurationsTMR110. In the Device Resources Tab, go to the
Peripherals Expand Timer peripheral anddouble click TMR1 to load the module(Figure 21).

FIGURE 21: LOADING TMR1 MODULE

11. In Project Resources tab, select TMR1module, as shown in Figure 22. Follow thesesteps to configure the system time to 1 second:

- Update Clock Source to “FOSC/4”.- Update the Timer Period to “4 ms”.- Check the “Enable Timer Interrupt”- Update the Callback Function Rate to “250”

times This will enable the timer configuration to interrupt forevery 1 second.

FIGURE 22: CONFIGURING THE TMR1 MODULE


AN2512
CoAP Configurations12. In the Device Resources tab, go to the Libraries
listed (Figure 23). Double click CoAP UtilityLibrary to load the module.

FIGURE 23: LOADING THE CoAP MODULE

13. In Project Resources tab, select CoAP Utilitymodule. This will display a view to enable addingdifferent resources in the Configuration tab.The resources will be arranged in a tree formatafter they are added to the CoAP Resource Treein the Resource Tree tab.

Figure 24 below shows the MCC CoAP View:

FIGURE 24: MCC CoAP UTILITY VIEW

14. Create a new resource (Figure 25) such as Led,by following the steps below:

- Select the Configuration tab- In Resource Types section, click the “+”

button in Resource Types- Double click the default “untitledRT_1”

resource type, update to Led resource type and press Enter

FIGURE 25: CREATING A NEW RESOURCE

15. Select the content-format types which supportthe resources created. All resources createdcan support more than one content-format type.By default, text/plain content-format is selected.

16. In the Content-Format Types section, select“application/cbor” along with the default “text/plain” (Figure 26).

FIGURE 26: SELECTING THE CONTENT-FORMAT TYPES


AN2512
17. To add resources to the Resource Tree
(Figure 27):- Select the Resource Tree tab- Double click Root resource, update it to

“mchp” and press Enter

FIGURE 27: ADDING RESOURCES TO THE RESOURCE TREE

- Right click “mchp” to add a “Led” resource (Figure 28)

FIGURE 28: ADDING A RESOURCE

- Double click the default “untitled_1” resource name and update it to “Led1” (Figure 29)

FIGURE 29: UPDATING THE RESOURCE NAME

- Repeat the last two steps to add Led2, Led3 and Led4 resources of Led resource type respectively (Figure 30)

FIGURE 30: ADDING MORE RESOURCES

CoAP – User Application MCC Configurations1. The user application is to:

- Endpoint as a CoAP server – Turn the Leds (D2, D3, D4, and D5) ON and OFF on the High Pin Curiosity (HPC) Board using CoAP Protocol

- Endpoint as a CoAP client – Push the switch button S1 to send a CoAP request and turn the Led ON or OFF on the server board

HPC Led and Switch Button – Pin Configurations2. In Pin Manager, configure the Pin module for the

Leds D2, D3, D4 and D5 with Port RA4, RA5,RA6 and RA7 respectively as outputs(Figure 31).

3. In Pin Manager, configure the Pin module forswitch button S1 with Port RB4 as input.

FIGURE 31: HPC LED PIN CONFIGURATION


AN2512
4. In the Project Resources tab, select Pin
module. Update the Pin Names RA4, RA5, RA6,RA7 and RB4 to D2, D3, D4, D5 and S1respectively and set the pins to digital

(Figure 32).

FIGURE 32: UPDATING PIN NAMES

5. There should be NO Warning messagesdisplayed in the Notifications tab (Figure 33).

FIGURE 33: MODULES SETUP


AN2512
6. Click the Generate button on top left. MCC
queries the user to save the configuration, thenclick the Save button. This will save theconfiguration created and generate thecorresponding files.

7. In main.c file, follow these steps: - Enable the Global and Peripheral interrupts

by uncommenting their respective calls (Figure 34).

FIGURE 34: ENABLING THE GLOBAL AND PERIPHERAL INTERRUPTS

- In while (1) loop, add Network_Manage() API call (Figure 35).

FIGURE 35: ADDING THE NETWORK_MANAGE()API

Endpoint as a CoAP Server1. Add the toggleLedApplication

source(.c) and header(.h) files to the project.

2. Open the CoAP_TCPIPLite.X\datamodel\Led.c file and scroll down. Create a variable for the Led resource, as shown in Figure 36 below:

FIGURE 36: CREATING A VARIABLE FOR A RESOURCE

3. In Led.c file, initialize the variable for the fourLed resources to a default value of ‘0’ in theResource Initializer (LedInit) handler(Figure 37).

FIGURE 37: INITIALIZING THE VARIABLE

4. Add the GETTER functionality for the Lightresource in the LedGetter() handler. This willhandle all the GET requests received on the“Led” Resource Type and return SUCCESS(Figure 38).

FIGURE 38: ADDING THE GETTER FUNCTIONALITY

5. Add the PUTTER functionality for the Lightresource in the LedPutter() handler. This willhandle all the PUT requests received on the“Led” Resource Type, call thetoggleLedApplication() API and returnSUCCESS.

FIGURE 39: ADDING THE PUTTER FUNCTIONALITY

Note 1: The name of ‘ledStatus’ variable isgiven as “led” and the value isLed[idx].ledStatus.

2: Variable data type is defined asuint8_t, so the argument is“UNSIGNED_INTEGER”.


AN2512
Option A: Static Configuration6. In MPLAB IDE, in the Run menu, click Clean
and Build Project. After successful build, go toRun menu and click Run Project to program thecode to the board.

7. Update the PC network configuration to staticconfiguration, as shown in Example 6.

EXAMPLE 6: IN WINDOWS OS

8. Open the Microchip_CoAP_GUI.jar file.The GUI shows the default IP address of thedevice i.e., “192.168.0.1”; click the Discoverbutton (Figure 40).

FIGURE 40: CONFIGURING THE CoAP GUI

9. Select Led1 Resource and push thecorresponding Led1 button to toggle led “D2” onthe High-Pin Curiosity Board (Figure 41).

FIGURE 41: TOGGLE LED USING CoAP GUI

10. Similarly, toggle the D3, D4 and D5 Leds byselecting resources “Led2”, “Led3” and “Led4”and pushing their corresponding buttons.


AN2512
11. Open Mozilla Firefox with Copper Plug-in, enter
the IP address of the device from step 6(Figure 15) into the URL and click the Discoverbutton (Figure 42).

FIGURE 42: CoAP DISCOVER USING MOZILLA CU PLUG-IN

12. Select Led1 resource and click the GET button,to get the status of the D2 Led (Figure 43).

FIGURE 43: CoAP GET USING MOZILLA CU PLUG-IN


AN2512
13. Similarly, by selecting “Led2”, “Led3” and “Led4”
resources individually and clicking the Getbutton, the status of the D3, D4 and D5 Leds isreceived.

Option B: Dynamic Configuration14. Open Wireshark and select the interface to

which the board and PC are connected.15. In the display filter, add ‘bootp || coap’ to

filter DHCP and CoAP packets over the network(Figure 44).

FIGURE 44: FILTERING DHCP AND COAP PACKETS

16. In MPLAB IDE, go to the Run menu and clickClean and Build Project. After successful build,go to Run menu and click Run Project toprogram the code to the board.

17. In Wireshark, the user will notice the DHCPpackets handshake to get the device IPaddress.

18. In Wireshark, double click “offer” packet.Expand “Bootstrap” protocol to get the device IPaddress (Figure 45).

FIGURE 45: DEVICE IP ADDRESS USING WIRESHARK

19. Open “Microchip_CoAP_GUI.jar” file.Enter the IP address of the device from step 17and click the Discover button (Figure 46).

FIGURE 46: CONFIGURING THE CoAP GUI

20. Select “Led1” Resource and push thecorresponding “Led1” button to toggle Led “D2”on the High-Pin Curiosity Board (Figure 47).

FIGURE 47: TOGGLE LED USING CoAP GUI

21. Similarly, toggle the D3, D4 and D5 Leds byselecting resources “Led2”, “Led3” and “Led4”and clicking their corresponding buttons.

22. In Wireshark, notice the CoAP PUT andrespective ACK packets exchanged betweenthe PC and board in CBOR format.

23. Open Mozilla Firefox with Copper plug-in, enterthe IP address of the device from step 17 intothe URL, and click the Discover button(Figure 48).


AN2512
FIGURE 48: CoAP DISCOVER USING MOZILLA CU PLUG-IN
24. Select “Led1” resource and click the Get buttonto get the status of the D2 Led (Figure 49).

FIGURE 49: CoAP GET USING MOZILLA CU PLUG-IN

25. Similarly, the status of the D3, D4 and D5 Ledsis received by selecting “Led2”, “Led3” and“Led4” resources individually and clicking on theGet button.

26. In Wireshark, observe the CoAP GET andrespective ACK packets exchanged betweenthe PC and board in text/plain format.


AN2512
Endpoint as a CoAP Client1. Add the coapClientApplication source
(.c) and header (.h) files to the project.2. Get the IP Address of the server’s board. [OR] In

this application, the client request is broadcasti.e., IP address of the server is 0xFFFFFFFF.

3. Open the ‘CoAP_TCPIPLite.X\coapClientApplication.c’ file, scroll down.

4. Create the CoAP Option table:- The request is sent to the resource “Light1”.

The URI Path to ‘Light1’ resource – “mchp/Led1”. Each resource path element is sent in individual options.

- Add option for Content-format of the payload which will be sent as part of request (Figure 50).

FIGURE 50: TRANSMIT OPTIONS API

- In coapTransmitOptions[] table, add the TransmitOptions function, which includes all the options for the request (Figure 51).

FIGURE 51: ADDING THE TRANSMITOPTIONS FUNCTION

5. Create the CoAP Payload table:- In TransmitPayload() API, add the

payload to be sent in the request (Figure 52).

FIGURE 52: TRANSMIT PAYLOAD API

- In coapTransmitPayload[] table, add the function TransmitPayload, which includes payload for the request (Figure 53).

FIGURE 53: ADDING THE TRANSMIT PAYLOAD FUNCTION

6. Assign the coapTransmit_t object:- The IP address of the server is noted. [OR] IP

address of the server in this application 0xFFFFFFFF. Assign the IP Address to the coapTranmsit_t variable (requestPtr) in transmitCoAPPutRequest() API (Figure 54).

FIGURE 54: ASSIGNING DESTINATION IP ADDRESS

- Assign the coapOptionsTable to the coapTranmsit_t variable (requestPtr) (Figure 55).

FIGURE 55: ASSIGNING TRANSMIT OPTIONS TO THE CoAP OPTIONS TRANSMIT HANDLER

Note: It is the user responsibility to add theCoAP options in ascending order in to thetable.

Note 1: The payload is sent in “TEXT/PLAIN”content-format.

2: The payload is written to the EthernetBuffer using UDP APIs.


AN2512
- Assign the coapPayloadTable to the coapTranmsit_t variable (requestPtr) (Figure 56).
FIGURE 56: ASSIGNING TRANSMIT PAYLOAD TO THE CoAP PAYLOAD TRANSMIT HANDLER

- Assign the Source and destination port numbers to the coapTranmsit_t variable (requestPtr) (Figure 57).

FIGURE 57: ASSIGNING SOURCE AND DESTINATION PORT NUMBERS

7. Start the CoAP Packet (Figure 58).

FIGURE 58: START CoAP TRANSMIT

8. Send the CoAP Packet (Figure 59).

FIGURE 59: CoAP SEND API

9. In main.c, scroll down. In while (1) loop, callthe API to transmit a CoAP PUT request onButton Press (Figure 60).

FIGURE 60: CALL TRANSMIT APPLICATION FUNCTION

10. In the Run menu, click Clean and BuildProject. After successful build, go to the Runmenu and click Run Project to program thecode to the board.

11. Open Wireshark and select the interface towhich the board and PC are connected.

12. In the display filter, add bootp || coap to filterDHCP and CoAP packets over the network(Figure 61).

FIGURE 61: WIRESHARK FILTER

13. Push the S1 button on HPC board to send PUTrequests to the server and turn the LED on or off.

14. Observe the CoAP Put Packets on Wireshark. 15. If the server board is connected in the network,

the D2 led on the server board turns ON.16. To turn off the LED, the payload is sent as “0”

(Figure 62).

FIGURE 62: TRANSMIT PAYLOAD APINote 1: COAP_CLIENT_SRC_PORT – 655202: COAP_CLIENT_DEST_PORT – 5683


Note the following details of the code protection feature on Microchip devices:• Microchip products meet the specification contained in their particular Microchip Data Sheet.

• Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions.

• There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property.

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

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

Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of ourproducts. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such actsallow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act.

Information contained in this publication regarding deviceapplications and the like is provided only for your convenienceand may be superseded by updates. It is your responsibility toensure that your application meets with your specifications.MICROCHIP MAKES NO REPRESENTATIONS ORWARRANTIES OF ANY KIND WHETHER EXPRESS ORIMPLIED, WRITTEN OR ORAL, STATUTORY OROTHERWISE, RELATED TO THE INFORMATION,INCLUDING BUT NOT LIMITED TO ITS CONDITION,QUALITY, PERFORMANCE, MERCHANTABILITY ORFITNESS FOR PURPOSE. Microchip disclaims all liabilityarising from this information and its use. Use of Microchipdevices in life support and/or safety applications is entirely atthe buyer’s risk, and the buyer agrees to defend, indemnify andhold harmless Microchip from any and all damages, claims,suits, or expenses resulting from such use. No licenses areconveyed, implicitly or otherwise, under any Microchipintellectual property rights unless otherwise stated.

2017 Microchip Technology Inc.

Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified.

QUALITY MANAGEMENT SYSTEM CERTIFIED BY DNV

== ISO/TS 16949 ==

TrademarksThe Microchip name and logo, the Microchip logo, AnyRate, AVR, AVR logo, AVR Freaks, BeaconThings, BitCloud, CryptoMemory, CryptoRF, dsPIC, FlashFlex, flexPWR, Heldo, JukeBlox, KEELOQ, KEELOQ logo, Kleer, LANCheck, LINK MD, maXStylus, maXTouch, MediaLB, megaAVR, MOST, MOST logo, MPLAB, OptoLyzer, PIC, picoPower, PICSTART, PIC32 logo, Prochip Designer, QTouch, RightTouch, SAM-BA, SpyNIC, SST, SST Logo, SuperFlash, tinyAVR, UNI/O, and XMEGA are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries.ClockWorks, The Embedded Control Solutions Company, EtherSynch, Hyper Speed Control, HyperLight Load, IntelliMOS, mTouch, Precision Edge, and Quiet-Wire are registered trademarks of Microchip Technology Incorporated in the U.S.A.Adjacent Key Suppression, AKS, Analog-for-the-Digital Age, Any Capacitor, AnyIn, AnyOut, BodyCom, chipKIT, chipKIT logo, CodeGuard, CryptoAuthentication, CryptoCompanion, CryptoController, dsPICDEM, dsPICDEM.net, Dynamic Average Matching, DAM, ECAN, EtherGREEN, In-Circuit Serial Programming, ICSP, Inter-Chip Connectivity, JitterBlocker, KleerNet, KleerNet logo, Mindi, MiWi, motorBench, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM, PICDEM.net, PICkit, PICtail, PureSilicon, QMatrix, RightTouch logo, REAL ICE, Ripple Blocker, SAM-ICE, Serial Quad I/O, SMART-I.S., SQI, SuperSwitcher, SuperSwitcher II, Total Endurance, TSHARC, USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, and ZENA are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries.SQTP is a service mark of Microchip Technology Incorporated in the U.S.A.Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries.GestIC is a registered trademark of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip Technology Inc., in other countries. All other trademarks mentioned herein are property of their respective companies.© 2017, Microchip Technology Incorporated, All Rights Reserved. ISBN: 978-1-5224-2000-2

DS00002512A-page 25


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

ASIA/PACIFICAsia Pacific OfficeSuites 3707-14, 37th FloorTower 6, The GatewayHarbour City, KowloonHong KongTel: 852-2943-5100Fax: 852-2401-3431Australia - SydneyTel: 61-2-9868-6733Fax: 61-2-9868-6755China - BeijingTel: 86-10-8569-7000 Fax: 86-10-8528-2104China - ChengduTel: 86-28-8665-5511Fax: 86-28-8665-7889China - ChongqingTel: 86-23-8980-9588Fax: 86-23-8980-9500China - DongguanTel: 86-769-8702-9880 China - GuangzhouTel: 86-20-8755-8029 China - HangzhouTel: 86-571-8792-8115 Fax: 86-571-8792-8116China - Hong Kong SARTel: 852-2943-5100 Fax: 852-2401-3431China - NanjingTel: 86-25-8473-2460Fax: 86-25-8473-2470China - QingdaoTel: 86-532-8502-7355Fax: 86-532-8502-7205China - ShanghaiTel: 86-21-3326-8000 Fax: 86-21-3326-8021China - ShenyangTel: 86-24-2334-2829Fax: 86-24-2334-2393China - ShenzhenTel: 86-755-8864-2200 Fax: 86-755-8203-1760China - WuhanTel: 86-27-5980-5300Fax: 86-27-5980-5118China - XianTel: 86-29-8833-7252Fax: 86-29-8833-7256

ASIA/PACIFICChina - XiamenTel: 86-592-2388138 Fax: 86-592-2388130China - ZhuhaiTel: 86-756-3210040 Fax: 86-756-3210049India - BangaloreTel: 91-80-3090-4444 Fax: 91-80-3090-4123India - New DelhiTel: 91-11-4160-8631Fax: 91-11-4160-8632India - PuneTel: 91-20-3019-1500Japan - OsakaTel: 81-6-6152-7160 Fax: 81-6-6152-9310Japan - TokyoTel: 81-3-6880- 3770 Fax: 81-3-6880-3771Korea - DaeguTel: 82-53-744-4301Fax: 82-53-744-4302Korea - SeoulTel: 82-2-554-7200Fax: 82-2-558-5932 or 82-2-558-5934Malaysia - Kuala LumpurTel: 60-3-6201-9857Fax: 60-3-6201-9859Malaysia - PenangTel: 60-4-227-8870Fax: 60-4-227-4068Philippines - ManilaTel: 63-2-634-9065Fax: 63-2-634-9069SingaporeTel: 65-6334-8870Fax: 65-6334-8850Taiwan - Hsin ChuTel: 886-3-5778-366Fax: 886-3-5770-955Taiwan - KaohsiungTel: 886-7-213-7830Taiwan - TaipeiTel: 886-2-2508-8600 Fax: 886-2-2508-0102Thailand - BangkokTel: 66-2-694-1351Fax: 66-2-694-1350

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

Worldwide Sales and Service

11/07/16

http://support.microchip.com

http://www.microchip.com

Microchip CoAP Stackww1.microchip.com/downloads/en/AppNotes/00002512A.pdf · coap – constrained...

Documents

Transcript of Microchip CoAP Stackww1.microchip.com/downloads/en/AppNotes/00002512A.pdf · coap – constrained...