embernet application development guidecseweb.ucsd.edu/groups/csag/html/teaching/cse291s03... ·...

EmberNet Application Development Guide

120-0003-210 December 2002

C o m p a n y C o n f i d e n t i a l

Copyright © 2002 by Ember Corporation

All rights reserved

The information in this document is subject to change without notice. The statements, configurations, technical data,and recommendations in this document are believed to be accurate and reliable, but are presented without express orimplied warranty. Users must take full responsibility for their applications of any products specified in this document.The information in this document is the property of Ember Corporation.

EmberNet and Ember are a trademarks of Ember Corporation.All other trademarks are the property of their respective holders.


EmberNet Application Develo

C o m p a n y C o n f

Contents

Contents

Tables

PrefaceAssociated EmberNet Documentation -xiii

CHAPTER 1 EmberNet NetworkingOverview 1-1

Before Architecting a Solution 1-1Contents 1-1

About the Mesh Mindset 1-2Understand these Mesh Networking concepts 1-2

Use Unicast over Broadcast messaging when possible 1-2Broadcast messaging is expensive 1-3Broadcasting to a Service 1-5

pment Guide 120-0003-210 iii

i d e n t i a l

Contents

Unicast messaging is relatively inexpensive 1-5When to use Broadcast over Unicast 1-6

Push data rather than pull it when possible 1-7Use Distributed Tasks and Communications as much as possible 1-8

Distributed Processing 1-8Spatial Multiplexing 1-11

Services and Discovery 1-12Services are used to build EmberNet applications 1-12

Referring to Services 1-12About Service Handles 1-13

Subscribing to Services 1-13Every node participates in routing, regardless of its subscribed services 1-14Nodes subscribe to services based on the types of messages they wish to receive 1-15

Discovery defines your network 1-16How Discovery works 1-17When to use Discovery 1-17

Discovery also happens on its own 1-18Discovery by Announcement 1-18Discovery by Request 1-20

EmberNet routing 1-21Benefits of EmberNet routing 1-22How does EmberNet routing work? 1-23

Example of EmberNet routing 1-24EmberNet minimizes network traffic 1-26EmberNet routing adjusts to changing network topologies 1-27

CHAPTER 2 EmberNet Host API and ESPOverview 2-1About the EmberNet Node SPI interface 2-2About EmberNet host API functions and EmberNet SPI protocol

commands 2-4About EmberNet packets 2-6Minimum host requirements 2-7Defined values 2-8Data structures 2-9EmberNet message types and flags 2-11

iv EmberNet Application Development Guide 120-0003-210


Contents

Messages with multiple flags 2-11Application template 2-12

CHAPTER 3 EmberNet Node ConfigurationOverview 3-1Setting the EmberNet Node network ID 3-2Getting the EmberNet Node network ID 3-2Getting the EmberNet Node’s product code 3-3Creating a label string 3-4Enabling routing 3-4Notifying EmberNet Nodes of a host reset 3-5Resetting an EmberNet Node 3-6Changing the radio channel 3-8Changing the radio transmitter power 3-9

CHAPTER 4 ServicesOverview 4-1Subscribing an EmberNet Node to a service 4-2Unsubscribing a Node from a service 4-2Service Description versus Service Handle 4-3Comparing service descriptions 4-4Copying a service description 4-4Getting a service handle 4-5Releasing a service handle 4-6Deconstructing a service handle 4-7

CHAPTER 5 EmberNet CommunicationsOverview 5-1Configuring Broadcast communications 5-2Configuring Unicast communications 5-3Obtaining Route Cost 5-4

EmberNet Application Development Guide 120-0003-210 v


Contents

CHAPTER 6 Processing Incoming Messages and CallbacksOverview 6-1

Contents 6-1About Handlers and Callbacks 6-2API return values 6-5Processing Incoming Messages with the Host API 6-6

CHAPTER 7 Debug LoggingOverview 7-1Configuring Debug Messaging 7-2Sending Debugging Raw Data Messages 7-3Sending Debugging String Messages 7-4

CHAPTER 8 ESP and API ReferenceOverview 8-1ESP Commands 8-2EmberNet Host API functions 8-5

emberAcknowledgeNodeReset 8-7emberBroadcast 8-8emberDebugConfig 8-10emberDeconstructServiceHandle 8-11emberEnableRouting 8-12emberGetNodeId 8-13emberGetProductCode 8-14emberGetServiceCost 8-15emberGetServiceHandle 8-16emberHandleError 8-17emberHandleIncomingData 8-18emberHandleIncomingDiscovery 8-20emberHandleNodeId 8-22emberHandleNodeReset 8-23emberHandleProductCode 8-24emberHandleReleasedServiceHandle 8-25emberHandleServiceCost 8-26emberHandleServiceHandle 8-27emberHostHasReset 8-28

vi EmberNet Application Development Guide 120-0003-210


Contents

emberProcessIncomingMessage 8-29emberReleaseServiceHandle 8-30emberResetNode 8-31emberSendDebugRawData 8-32emberSendDebugString 8-33emberSetLabelString 8-34emberSetNodeId 8-35emberSetRadioChannel 8-36emberSetRadioPower 8-37emberSubscribe 8-38emberSvcCopyDescription 8-39emberSvcDescriptionsAreEqual 8-40emberUnicast 8-41

Index

EmberNet Application Development Guide 120-0003-210 vii


Contents

viii EmberNet Application Development Guide 120-0003-210


EmberNet Application Devel

C o m p a n y C o n

Tables

o

f

Table 2-1: EmberNet Node SPI Signals 2-3Table 2-2: EmberNet Packet Fields 2-6Table 2-3: EmberNet Host API/ESP Command Defined Values 2-8Table 2-4: EmberNet API Data Structures 2-9Table 2-5: Message Type Flags 2-11Table 3-1: Radio Transmitter Power Levels 3-9Table 4-1: Service Descriptions versus Service Handle 4-3Table 6-1: API Return Values 6-5Table 8-1: API Function and ESP Command Cross Reference 8-2Table 8-2: ESP Commands 8-3Table 8-3: EmberNet Host API Functions 8-5Table 8-4: Debug Commands 8-10Table 8-5: EmberNet Error Codes 8-17Table 8-6: EmberNet Node Radio Power Levels 8-37

pment Guide 120-0003-210 ix

i d e n t i a l

Tables

x 120-0003-210 EmberNet Application Development Guide




Figures

Figure 1-1: Example of Broadcast Messaging 1-4Figure 1-2: Example of Unicast Messaging 1-6Figure 1-3: Traditional Sensing-Device Network 1-9Figure 1-4: Distributed Sensing-Device Network 1-10Figure 1-5: Spatial Multiplexing Example 1-11Figure 1-6: Discovery by Announcement 1-18Figure 1-7: Discovery by Request 1-20Figure 1-8: Discovery by Broadcast Announcement 1-24Figure 1-9: Routing Example 1-25Figure 2-1: EmberNet Node SPI Interface 2-2Figure 2-2: EmberNet Host API/ESP Model 2-5Figure 2-3: EmberNet Packet 2-6Figure 6-1: Processing Incoming Messages 6-3

pment Guide 120-0003-210 xi

i d e n t i a l

xii 120-0003-210 EmberNet Application Development Guide




Preface

About This GuideThe EmberNet Application Development Guide is intended for application developers and programmers who will use the EmberNet Host API and EmberNet SPI Protocol (ESP) to develop host applications that configure and manage EmberNet networks.

Associated EmberNet Documentation

EmberNet OverviewEmberNet Developer Kit User’s GuideEmberNet View User’s GuideEmberNet Node Technical Specification

Getting Help

Documentation, customer service, and support are available at support.ember.com or by contacting your account representative at Ember.

pment Guide 120-0003-210 xiii

i d e n t i a l

http://support.ember.com

Preface

xiv
120-0003-210 EmberNet Application Development Guide

CHAPTER 1 EmberNet Networking

EmberNet Application Dev

C o m p a n y C o n f i d

Overview

Before Architecting a SolutionThis chapter introduces you to concepts that are important to understand as you prepare to design Ember Enabled products.

Contents

Section Page Number

About the Mesh Mindset 1-2

Use Unicast over Broadcast messaging when possible 1-2

Push data rather than pull it when possible 1-7

Use Distributed Tasks and Communications as much as possible 1-8

Services and Discovery 1-12

Services are used to build EmberNet applications 1-12

Discovery defines your network 1-16

EmberNet routing 1-21

elopment Guide 120-0003-210 1-1

e n t i a l

EmberNet Networking

1-2

About the Mesh Mindset

An EmberNet network uses a mesh topology, much like the Internet. It provides reliability without the centralized control of a base station. EmberNet takes advantage of a mesh network’s flexibility and offers self-organizing and self-healing characteristics to the network’s features.

An EmberNet network’s decentralized approach and reliable flexibility should prompt you to consider different approaches to designing your Ember Enabled solution. Doing so will maximize the benefits of mesh networking and allow you to get the most efficient, effective use of your embedded network.

Understand these Mesh Networking conceptsEmberNet communication is a cooperative, distributed process. In developing Ember Enabled devices, consider the following suggestions to maximize the performance of your EmberNet network. When possible, you should:

• use Unicast over broadcast messaging. • push information rather than pull it.• use distributed tasks.

Use Unicast over Broadcast messaging when possibleBoth the EmberNet SPI Protocol and the EmberNet Host API support two messaging functions—broadcast and unicast. A broadcast message must be relayed to every node, while unicast messaging routes a message to a specific destination. Either mode of communication delivers a message across the network, but there are times when it is advantageous to use one over the other.

Benefits of EmberNet routing 1-22

How does EmberNet routing work? 1-23

Section Page Number



EmberNet Application Deve

Understand these Mesh Networking concepts

C o m p a n y C o n f i d e

Broadcast messaging is expensiveWhen you use broadcast messaging, every node that hears the message is instructed to repeat it, regardless of where the message has already been transmitted. Every node must repeat the message, because it may have access to a node that no other node can reach.

In Figure 1-1, assume that Node A sends a broadcast. In this diagram, the dashed lines around each node represent its “neighborhood,” or the range within which other nodes can hear the message. Each node that hears or receives Node A’s message must pass it on, so that all nodes in the network receive it. This method of communication ensures delivery, but is somewhat inefficient.

To compound the inefficiency, only one node can use the radio at a time. For example, assume that Node C receives the message and before it can relay the message to its neighbors (A, B, E, or F), Node B begins to relay the message. Node C must hold that message and wait. The sending node is tied up for the duration of the transmission, and every node that hears it is tied up for the duration as well.

lopment Guide 120-0003-210 1-3

n t i a l

EmberNet Networking

1-4

Additionally, each node retries the message a fixed number of times (default is three) to ensure delivery.

Figure 1-1: Example of Broadcast Messaging

As you can see, broadcasts result in a significant amount of message traffic. They consume quite a bit of the channel, particularly if the network has a lot of nodes and the physical space is small enough so that many nodes can hear each other. To propagate a message through the network with broadcast consumes a lot of time and energy. You can limit the network congestion when broadcasting by specifying a radius, or number of hops, that the message should travel in the network. Using the example above, if Node A sends a broadcast with a radius of two, Node G never receives the message. The maximum radius or number of hops permitted in an EmberNet network is 256.




Understand these Mesh Networking concepts


Broadcasting to a ServiceIf a node sends a broadcast that is destined for nodes who are subscribed to a particular service, it is important to remember that all nodes who hear the message must relay it, regardless of whether or not they are subscribed to the service. Assume that all nodes in Figure 1-1, with the exception of Node F, subscribe to the FanController service. If Node A broadcasts a message to the FanController service, Node F still participates in relaying the message, as that’s the only way Node G can receive the message. Only nodes that subscribe to the service actually send the message to their host processor via the SPI channel for processing.

For more information on EmberNet services, refer to “Services and Discovery.”

Unicast messaging is relatively inexpensiveUnicast messaging allows a node to send a message to a specific service on a particular node. Unicasts affect only those nodes that are on the path between the source and the destination. As a consequence, the message transmits from source to destination with far less traffic.

For example, if the FanController service on Node A needs to send a message to the same service on Node F, there are a number of alternate routes that could be used. Using a cost metric to make its routing decisions, the EmberNet ensures that the message reaches the destination using the most efficient route, while other more costly routes are available as backups.

For more information on EmberNet routing, refer to the section on routing later in this chapter.


n t i a l

EmberNet Networking

1-6

Figure 1-2: Example of Unicast Messaging

When to use Broadcast over UnicastBecause broadcasts are more expensive in terms of network resources, you should broadcast as little as possible. Broadcasts are a valuable tool, however, for discovery of other nodes in the network.




Push data rather than pull it when possible


You should first use broadcast messaging for initial discovery, and unicast discovery messages when needed thereafter. Unicast discovery messages are somewhat expensive because the discovery flag forces nodes to re-evaluate their location in the network and therefore, their cost for delivering messages. Unicast data messages are considered the least expensive method of delivering messages.

Push data rather than pull it when possibleMost legacy sensing and control systems use a poll/return methodology. When you pull information, the data recipient must first send out a request or poll for the information, and the sender (usually a sensing device) then replies with its data. By using a push model, where the data is sent at regular intervals, the EmberNet network traffic is cut in half, as no request prompt is sent out. If you know that you need information from a node on a regular basis, it makes sense to let the node push the information to the destination on a defined schedule.

Additionally, you can further reduce network traffic by having nodes send messages to a destination only when they have something important to report—perhaps a change in temperature above or below a pre-defined threshold.

Congestion is not a concern if multiple nodes push data to a destination at the same time. The EmberNet protocol stack manages traffic to reduce collisions.

Note: The EmberNet protocol stack provides link-level or hop-to-hop acknowledgments; end-to-end acknowledgments should be handled within the application you develop.


n t i a l

EmberNet Networking

1-8

Use Distributed Tasks and Communications as much as possibleUsing distributed tasks allows you to shorten pathways between nodes, which is important in a wireless network for these reasons:

• Network reliability follows a product rule. Reliability decreases multiplicatively as the number of hops required to deliver a message increases.

• Latency follows a sum rule. Latency is added with each additional hop required to deliver a message.

Distributed Processing

To better explain this concept, consider a network application where a number of thermistors are monitoring temperatures in a particular environment. If the temperature reaches a high-end threshold, the fans turn on. The fans run until the temperature decreases below a low-end threshold and then turn off.

In traditionally designed industrial sensing networks (Figure 1-3), a centralized controller prompts each thermistor for its temperature on a regular basis. When a thermistor says it is too hot, the controller takes a reading, and then commands the fan to turn on.




Use Distributed Tasks and Communications as much as possible


Figure 1-3: Traditional Sensing-Device Network


n t i a l

EmberNet Networking

1-10

A more distributed solution (Figure 1-4) allows for direct communication between a thermistor and the corresponding fan, without the need for a centralized controller to make operating decisions. In this case, a thermistor tells its fan directly when it has important information, such as a reading that is too hot. The fan acknowledges the message so that the thermistor need not send the message repeatedly, and then turns on. A centralized controller could instead be used for monitoring. If, for example, a fan did not acknowledge a message from its thermistor, the thermistor could report the problem to the monitoring station. The monitoring station could also be used to send some occasional information to the sensor, perhaps to change set points or to check on the health of a thermistor.

Figure 1-4: Distributed Sensing-Device Network




Use Distributed Tasks and Communications as much as possible


Spatial MultiplexingBecause EmberNet Nodes are relatively low power, you can increase the effective bandwidth of your network by localizing message traffic. If you have areas in your network that are spatially separated and traffic can be localized (Figure 1-5), message traffic can be transmitted in parallel without interfering with other communications.

Figure 1-5: Spatial Multiplexing Example

An example of this concept can again be found in the thermistor/fan application. Assume you have a large facility with several dozen thermistor points and fans. If each thermistor and fan are physically close in location, then communications between each thermistor and fan do not cause traffic in other parts of the network.

Source 1

Destination 1

Source 2

00017

Destination 2

lopment Guide 120-0003-210 1-11

n t i a l

EmberNet Networking

1-12

Services and Discovery

Services and discovery play very important roles in the development and operation of an EmberNet network.

• Services are used to define the roles of each device in an EmberNet network.• Discovery is used to define the cost associated with routing a message through

the network.

Services are used to build EmberNet applications

EmberNet makes use of services to help you build your application. Services represent a logical chunk of your application and a logical destination for messages. For example, in an application where a thermistor and fan are linked to enable or disable the fan, both would need to subscribe to the same service. As many as 64 services can be defined within a network, and any node can subscribe to as many as 16 of the services.

Referring to Services

An EmberNet network references services in three ways:

• Service Description. A 6-byte service description defines a service so that it may be used. At the application level, a service pointer references the 6-byte service description for subscribing to services, etc.

• Service Handle. A 1-byte service handle references a particular service on a specific node.






About Service Handles

A service handle is a way to reference a one-way communications link for a particular service that is running on a specific node. It is a shorthand representation of the pointer to the service description and the node ID.

When developing your EmberNet application, there are several important things to understand about service handles:

• The EmberNet Host API issues service handles in response to certain com-mands or functions. Service handles can be cached for later use in the applica-tion.

• Because each node cannot have more than 64 active service handles at any time, you should design your application to free service handles once they are no longer useful so that the node can manage its memory efficiently. One common way to refresh handles is to age them using a timer.

• You can statically define service handles using the API.• Unless it is static, a service handle defining a service s on node n will not always

be consistent, because EmberNet dynamically allocates service handles on an as-needed basis. If you free a service handle and need to re-establish it, the new handle may not be the same as the previous one.

• If the EmberNet Node resets, you should flush all of your handles at that point, because they are no longer valid.

• Service handles are node specific. The service handle that Node A uses to refer-ence service s on Node C will not be the same service handle that Node B uses to reference service s on Node C.

Subscribing to Services

Nodes in an EmberNet network subscribe to the services they need. This allows them to filter the messages that they relay and process only (send the message to its host processor) the messages to which it subscribes. A node can subscribe to as many as 16 services.

lopment Guide 120-0003-210 1-13

n t i a l

EmberNet Networking

1-14

Every node participates in routing, regardless of its subscribed services

Nodes in the EmberNet network participate in relaying all types of messages, even if they are not subscribed to the service or message type (announcement, request, or data). When relaying the message, each node in the path makes a decision based on the message semantics as to whether or not its host will want to know about this type of message. If the node subscribes to these kinds of messages for this service, then the node passes the message over the SPI channel to the host for processing. If a node does not subscribe to this type of message for this service, the routing algorithm on the node simply participates in routing the message to its destination (based on the cost), and does not forward the message to the host processor.






Nodes subscribe to services based on the types of messages they wish to receive

More specifically, nodes subscribe to the semantics, or particular types of messages, they want to accept from the service. There are three kinds of messages—announcements, requests, or data. When a node subscribes to a particular kind of message for a service, it can receive or accept those kinds of messages from other nodes.

• Announcements. If a node subscribes to announcements of a particular service s, it accepts announcements from other nodes that offer the service s. Announcements, like requests, are discovery messages, as they allow nodes participating in their relay to understand their location within the network and to update their cost metric.

• Requests. If a node subscribes to requests for a particular service s, it can respond to another node’s request for a node offering service s. Requests, like announcements, are discovery messages, as they allow nodes participating in their relay to understand their location within the network and to update the cost metric.

• Data. If a node subscribes to data on a particular service s, it receives data traffic destined for nodes of service s.

lopment Guide 120-0003-210 1-15

n t i a l

EmberNet Networking

1-16

Applications subscribe to messages based on service and semantics, or the type of messages it wishes to receive from the service. For example, in an application for the FanController service, a node could subscribe to both requests (messages asking to locate the service) and data (messages destined for the service) from the FanController service using the following API command:

emberSubscribe(FanController, REQUEST & DATA);

As a general rule:

• Service providers (servers) send announcements that they offer a particular service, and they subscribe to requests and data messages.

• Service users (clients) subscribe to announcements of service from other nodes. They probably send data and they possibly send requests for a service.

• The decision to use announcements or requests is usually based on how often you expect a particular type of information to be passed around.

Discovery defines your network

When a node in an EmberNet network powers up, it can communicate only with its host processor, which doesn't know what to do, or where all the other nodes are. The only thing a node knows about is a service, and therefore, it needs to do discovery. Discovery is the process by which nodes learn their location in the network.






How Discovery works

Nodes perform discovery by transmitting either an announcement of service or a request for service. Announcements allow a node to declare the service that it implements, for example, “I am a fan.” Announcements notify other nodes of the service they provide. In contrast, nodes use requests to get service handles for all nodes that subscribe to a particular service. Requests tell the network “I'm looking for a fan.”

Sending announcements or requests enables discovery, which instructs nodes who relay the message to learn where they are in the message’s path. To learn their location, each node takes note of the source and the “cost” of getting the message. Each node stores this discovery information, allowing an EmberNet network to make intelligent and low-cost routing decisions.

Discovery does not determine optimal paths across the network. Instead, it allows nodes to know where they are on the path, and whether they are optimal. If an optimal node can’t participate in the message relay for whatever reason, the routing algorithm uses an alternate node.

When to use Discovery

Discovery consumes network resources, so you should minimize it whenever possible. In certain circumstances, however, discovery is very appropriate:

• A node or an entire network of nodes powers up for the first time. Certain nodes may broadcast an announcement to advertise that they offer a particular service. All nodes in the network relay the broadcast and, therefore, learn their position in the network.

• A route is broken or doesn't exist. Assume, for example, a message is sent to a particular node and you have designed the application to return an acknowledg-ment. If the sender has not received an acknowledgment, it can presume that the route to the node is broken or non-existent and can send either an announcement or request for service to re-establish the path.

The discovery flags (announcements and requests) are not exclusive to particular types of messages. For example, you can attach an announcement flag to a data packet to turn discovery on while it transits the network.

lopment Guide 120-0003-210 1-17

n t i a l

EmberNet Networking

1-18

Discovery also happens on its own

When you add new nodes to the network, they can determine where they are in the network and what message routing they should participate in, based on the network traffic that is passing by them. As long as a basic pathway has been established and messages are passing back and forth, new nodes can place themselves without doing discovery at all.

Discovery by AnnouncementConsider the diagram in Figure 1-6. Node A (on the left of the diagram) needs to send data to nodes subscribed to the FanController service, and Node B (on the right of the diagram) implements the FanController service.

Figure 1-6: Discovery by Announcement

The first thing both nodes do when powering up is subscribe to the FanController service. Node A subscribes only to announcements for the service so that it knows

A BThe EmberNet

implements the fan controllerservice S

needs to send data to the fan controllerservice S

SPI SPI

subscribe(i, announce)subscribe(i, data)

broadcast(i, announce, ...)

Establish routei = pointer to name of serviceh = handleS = serviceB = broadcast






which nodes in the network are implementing that service, and Node B subscribes only to data that is destined for the service, since it is the implementer of the service.

Next, Node B broadcasts an announcement that it is an implementer of the FanController service. This packet is the first to travel across the EmberNet network, and it is relayed to every node on the network, updating each node’s cost for relaying a message along this path.

Because Node A subscribes to announcements for the service, it receives the incoming announcement packet, which includes the service handle, h, for the FanControllerService on Node B. Node A can use this service handle to send messages to B.

Understanding that the announcement was also used for network discovery and that Node B probably wants to receive messages from others (since it was announcing that it implements a service), EmberNet remembers the cost of transmitting a message from Node A to Node B. It is important to note that this path is not fixed. Essentially, all of the nodes that heard this broadcast—potentially every node in a radius of 256 hops—remembers how much it costs for it to send a packet to Node B.

Node A next sends a unicast announcement to acknowledge Node B so that Node B doesn’t repeatedly announce itself. This step also ensures that Node B knows the cost associated with sending a message back to Node A.

lopment Guide 120-0003-210 1-19

n t i a l

EmberNet Networking

1-20

Discovery by Request

Figure 1-7 illustrates a unicast discovery message. This type of discovery is somewhat more expensive than a unicast transfer of data because it requires extra work to set up the routes.

Figure 1-7: Discovery by Request

In this case, Node A again subscribes to announcements while Node B subscribes to both data intended for the service and to requests for the service. Assume that Node B sends out the broadcast announcement and no one receives it—perhaps Node A doesn’t have power, or there was a power failure during the transmission. Node A can use a broadcast request to see which nodes implement the FanControllerService.




EmberNet routing


Node B receives the incoming service request packet, including a service handle for the service on Node A, and establishes a route to Node A. Node B can then announce its availability of the service by directing a unicast message to Node A, using the service handle for the FanController service running on Node A. This step gives Node A a service handle for the FanController service running on Node B and establishes a route for Node A to get back to Node B.

If Node A sends out the request and receives several reply announcements, you can select the nodes you wish to use and get a service handle for each. Just dispose of any service handles you don’t need.

EmberNet routingRouting in an EmberNet network is significantly different from routing in a traditional network. EmberNet routing does not provide a fixed path through the network; rather it uses a “cost metric” on every node so that each node can decide whether or not it should participate in relaying a message. Routing information is set on demand and updates as discovery messages (announcements and requests for services) are passed among nodes.

lopment Guide 120-0003-210 1-21

n t i a l

EmberNet Networking

1-22

Benefits of EmberNet routingEmberNet routing offers a number of advantages over traditional routing algorithms:

• EmberNet routing is on-demandEmberNet uses an on-demand routing protocol. Routes are set up only when nodes wish to communicate with one another. When there is no communication between nodes, there is no need to create or maintain routes between them.

• EmberNet routing has very low latencyEach transmission is a local broadcast; therefore, the routing algorithm does not use a request to send / clear to send (RTS/CTS) handshake associated with unicast transmissions. As a result, EmberNet routing exhibits very low latencies. Messages pass quickly, and nearby node cost estimates are updated.

• EmberNet routing is flexibleA changing network topology does not disturb EmberNet routing. New nodes “learn” their location in the network by listening to the traffic that goes by them.

• EmberNet routing provides network stability When each message reaches a number of nodes, a single link failure does not cause a break in the communication path, as long as another neighbor node relays the message.




How does EmberNet routing work?



Because EmberNet uses a decentralized multi-hop architecture, each node communicates only with its immediate neighbors (those nodes within its transmission range). EmberNet Nodes relay messages on behalf of their neighbors to reach the intended destination. Out-of-range nodes communicate to each other by relaying messages through intermediate neighbor nodes.

A node in an EmberNet network does not select a particular neighbor node to relay its message. Instead, it relays the message to its neighbors along with an advertised cost at which it believes the message can be delivered to a destination. Only the neighbor nodes that can deliver the message at a lower cost are eligible, and the neighbor node with the lowest cost is the only node that participates. Ember refers to this process as loop-free gradient routing.

The cost metric is a value between one and 255, and relates to things like the number of hops, the link quality on the way, and internal congestion figures.

If a path exists between two nodes and one of the nodes on the path, for whatever reason, becomes unavailable, any other paths along which that message can be sent in a decreasing-cost fashion is used without any reconfiguration.

lopment Guide 120-0003-210 1-23

n t i a l

EmberNet Networking

1-24

Example of EmberNet routing

Using the diagram in Figure 1-8, Node A sends a broadcast announcement to the network. Along the way, each node takes note of its own location (number of hops) relative to Node A. The discovery process allows a node to know its location with respect to the source node, and no further intervention is required from the application. Once Node A transmits a broadcast, all of the nodes on the network know how many hops away from A they are. This number is shown next to each node in Figure 1-8.

Figure 1-8: Discovery by Broadcast Announcement






Instead of the source node selecting a route by which to transmit the packet, the destination side controls the routing, in a sense. If Node B (Figure 1-9) wants to send a message to Node A, Node B does not explicitly choose Node Y to deliver the message. Instead, it sends a unicast message to Node A with an advertised cost of 3, since it believes that it is located three hops away from A. Even though the message is a unicast, it originates with a local broadcast (broadcasts to all of its neighbors out one hop), allowing both Node Y and Node Z to hear the message.

Figure 1-9: Routing Example

When Nodes Y and Z receive the message, the node with the least cost path to Node A (Node Y in this case), continues to relay the message. Node Y then sends out a local broadcast to its immediate neighbors with an advertised cost of 2, and only nodes that can deliver the message back to Node A in fewer than two hops participate in the relay. Each node that hears the message along the transmission path knows whether or not it is in an advantageous position to forward the message.

lopment Guide 120-0003-210 1-25

n t i a l

EmberNet Networking

1-26

The path back to Node A through Node Z is a backup route in the event of failure along Node Y’s path.

One other important event to understand is that when Node B initiates its message back to A, all nodes who hear the message along its path update their cost metric for relaying information to B—whether or not they actually participate in the routing.

If, in the process of relaying the message, the network presents more than one node with the same cost (number of hops to a destination), the routing algorithm randomly chooses one of the nodes.

EmberNet minimizes network trafficAs nodes relay messages, multiple nodes may hear the same transmission. Assume Node A wants to send a message to Node B and that several nodes are in between. As a result of discovery, all nodes have differing ideas costs to relay a packet to Node B, as does Node A.

When Node A transmits the packet, it announces that it has a message for Node B and that it (Node A) believes that it costs x to deliver it. The nodes between Nodes A and B determine whether they can beat the cost. Those that cannot beat the cost don’t bother to relay the message. Those that can beat the cost metric try to relay it.

The first node to relay the message dampens some of the attempts by the other nodes to relay it, as they hear another transmit the message and cancel their transmissions. This passive acknowledgment whereby nodes listen and will not send redundant transmissions of the same packet helps to reduce network congestion.

Additionally, if any node along the path hears another node trying to transmit a packet that they know has already been sent, they tell the attempting node to stop transmitting. The destination node also does this. These acknowledgments are link-level only; no acknowledgment returns to the source node. The source node will not know that the message arrived unless you explicitly design the application that way.






EmberNet routing adjusts to changing network topologiesIf the path between the originator and target nodes becomes shorter, perhaps due to the removal of a node, the routing algorithm automatically compensates for the change by “skipping over” any intervening nodes.

If, however, new nodes are added and the path becomes longer, the message may not reach the destination, because the originally advertised cost estimate for delivering the message may not be sufficient. In this case, the originator repeats the transmission with a higher cost estimate. If repeated attempts fail, then the originator may need to perform discovery again to update cost estimates.

lopment Guide 120-0003-210 1-27

n t i a l

EmberNet Networking

1-28

CHAPTER 2 EmberNet Host API and ESP



Overview

This chapter provides an overview of important concepts for the EmberNet Host 2-2.API and EmberNet SPI Protocol (ESP) commands.

Section Page Number

About the EmberNet Node SPI interface 2-2.

About EmberNet host API functions and EmberNet SPI protocol commands

2-4.

About EmberNet packets 2-6.

Minimum host requirements 2-6.

Defined values 2-8.

Data structures 2-9.

EmberNet message types and flags 2-11.

Application template 2-12.


e n t i a l

EmberNet Host API and ESP

2-2

About the EmberNet Node SPI interfaceThe host processor communicates to the EmberNet Node through the Node’s SPI interface. The SPI interface is a half-duplex, 5-wire interface that connects to the host processor. The EmberNet Node sends and receives five signals, as shown in Figure 2-1 and Table 2-1.

Figure 2-1: EmberNet Node SPI Interface




About the EmberNet Node SPI interface


The host processor is the master, the EmberNet Node is the slave. The host/master receives a signal telling it that it is the master.

The EmberNet API functions contain routines that generate packets for host processor-to-Node and over-the-air communications as defined by the ESP. For more information, see “About EmberNet packets” on page 2-6.

Table 2-1: EmberNet Node SPI Signals

Wire Direction Bit Width Description

MOSI Input 1 Master Out, Slave In.

MISO Output 1 Master In, Slave Out

SCLK Input 1 System Clock

INT_OUT Output 1 Interrupt out. Passes incoming data directly to the host through the host processor’s interrupt interface or general purpose input/output (GPIO). This wire relieves the host of constantly polling the EmberNet Node for the presence of incoming data.

DIRECTION Input 1 Selects the direction of transfer through the SPI wires.


n t i a l


2-4


The EmberNet Node and the host processor communicate through a 5-wire SPI channel (Figure 2-2). The host processor and node connect to the SPI channel through their SPI interfaces. The EmberNet SPI Protocol (ESP) defines the packet structure so that the host processor can communicate with the node through the 5-wire SPI interface. Each ESP command is assigned a unique number used to identify it in the command byte of the EmberNet packet.

The EmberNet host API is a thin layer running atop the ESP. The host API uses the host processor's SPI interface to send packets to the node in the format defined by the ESP. The Host API functions execute the ESP commands as part of their routines. Consequently, with a few exceptions, the EmberNet Host API has the same command set as the ESP commands. For more information, see “ESP and API Reference” on page 8-1.

The EmberNet Node is delivered with its API image already loaded. For the host processor, the EmberNet host API is delivered as a binary image and source code. The binary image is for use with the Atmel 8535 host processor on the Ember Breakout Board. For other host processors, you can modify the EmberNet host API source code to develop your application, or use the ESP commands to create your own API. For more information, see the EmberNet Developer Kit User’s Guide.

The EmberNet Host API implements routines that build the packets for over-the-air and host processor-to-EmberNet Node communications. If you write an application using ESP commands only, you must write a routine to add the Start Frame, Data Length, Command, and End Frame bytes to the packet.

API messages are returned asynchronously. API functions that logically expect results do not wait for them. If, for example, the host processor requests information about a service handle, the host should expect a message back from the Node with the relevant information, but should not expect the response in the next message.






Figure 2-2: EmberNet Host API/ESP Model


n t i a l


2-6

About EmberNet packetsFigure 2-3 and Table 2-2 describe the general packet format for EmberNet communications. The ESP defines the packet format. The EmberNet API functions implement routines that build the packets for over-the-air communications between EmberNet Nodes and communications between the Node and host processor. If you use the ESP commands only, you must write a routine to create the Start Frame, Data Length, Command, and End Frame bytes.

EmberNet packets are arranged with the high order bytes first.

The length of a packet depends on the type of message being sent. The maximum acceptable length for a packet is 104 bytes. The maximum length of a packet is defined in the source code provided with the node and should not be changed.

Figure 2-3: EmberNet Packet

Table 2-2: EmberNet Packet Fields

Name Bytes Description

Start Frame 1 Contains Start of Frame information.

Data Length 1 Contains length of message.

Message variable Contains message information. Size of message depends on message being sent. A message is not required to send a packet.

Command 1 Contains command information. Each ESP command has a unique number that identifies it. See the EmberNet source code for details.

End Frame 1 Contains end of packet information.




Minimum host requirements


Minimum host requirementsThe host can use any processor and real-time operating system (RTOS) to run its application. The host API is delivered as a binary image and source code. The binary image of the host API provided with an EmberNet Node supports the Atmel 8535 processor on the Ember Breakout Board. The source code for the EmberNet Host API is also provided, enabling you to tailor the source code for use with a different host processor. Alternately, you can create your own API with the ESP commands. For more information, see the EmberNet Developer Kit User’s Guide.


n t i a l


2-8

Defined valuesTable 2-3 shows values that are defined in the EmberNet API source code and should not be changed.

Table 2-3: EmberNet Host API/ESP Command Defined Values

Defined Value Description

#define EMBER_LABEL_STRING_LENGTH The length of a node's label string in bytes. The maximum is 32 bytes.

#define EMBER_DATA_SIZE_LIMIT The limit on packet size for over-the-air and SPI channel communications. The maximum packet size is 104 bytes.

#define EMBER_SVC_ANNOUNCE A discovery flag used to indicate that the sending node offers a service.

#define EMBER_SVC_REQUEST A discovery flag used to indicate information.

#define EMBER_SVC_DATA The “non-discovery” flag.

#define EMBER_ESP_PACKET_OVERHEAD The maximum overhead for EmberNet data in an SPI buffer.

#define EMBER_ESP_VERSION The current version of the EmberNet SPI Protocol (ESP).




Data structures


Data structuresTable 2-4 shows the data structures for the EmberNet Host API.

Table 2-4: EmberNet API Data Structures

Data Structure Description

typedef int8u EmberStatus; A status type returned by all host API functions

typedef int16u EmberNodeID; A 2-byte number that is the network-wide unique id for a particular node.

typedef int8u EmberServiceHandle; A 1-byte handle that represents a service description as implemented on a particular node.

typedef int8u EmberCostValue; A cost value represents the cost to route a packet to a particular node.

typedef struct { int8u implementorCode[3]; int16u projectCode; int8u implementorTag;} EmberServiceDescription;

A globally unique id for a service. For more information, see the EmberNet Developer Kit User’s Guide.


n t i a l


2-10

typedef struct { int8u manufacture_code[3]; int8u date_stamp[2]; int8u serial_number[3];} EmberNodeProductCode;

A unique code for every node added during manufacturing.

typedef enum { EMBER_NO_ERROR, EMBER_ERROR_LABEL_STRING_TOO_LONG, EMBER_ERROR_INVALID_CHANNEL, EMBER_ERROR_INVALID_POWER, EMBER_ERROR_BUS_BUSY,} EmberErrorCode;

EmberNet API return values. For more information, see “Processing Incoming Messages with the Host API” on page 6-6.

Table 2-4: EmberNet API Data Structures (Continued)

Data Structure Description




EmberNet message types and flags


EmberNet message types and flags

The EmberNet supports three types of messages, as shown in Table 2-5. Announcements and requests are collectively known as discovery messages. For more information, see “Services and Discovery” on page 1-12

Each message type has a hexadecimal value, which is defined in the EmberNet API/ESP source code and should not be changed. The hexadecimal values allow the EmberNet Nodes and the host processor to determine what type of message is being received. In the API and ESP command code, you use flags parameter to designate the type of message—Announcement, Request, or Data—when you send a broadcast or unicast message.

For more information, see “EmberNet Communications” on page 5-1.

Messages with multiple flagsEmberBroadcast() and emberUnicast() both have flag arguments. Multiple flags can be set in this field simply by “OR”-ing them together: (E.g. EMBER_SVC_ANNOUNCE | EMBER_SVC_DATA is a combination that’s frequently used.) When the destination node receives this message, it sends only one notification message to the host, and discovery takes precedence over data. Consequently, the emberHandleIncomingDiscovery() handler gets called, but the emberHandleIncomingData does not.

Combining discovery with data is an efficient use of EmberNet messaging, but it is important to remember that you need corresponding data-handling code in your discovery handler.

Table 2-5: Message Type Flags

Message Type Flag Syntax and Value

Announcement EMBER_SVC_ANNOUNCE

Request EMBER_SVC_REQUEST

Data EMBER_SVC_DATA

lopment Guide 120-0003-210 2-11

n t i a l


2-12

Application template

Ember provides an application template, which is an outline of a sample application. For more information, see the EmberNet Developer Kit User’s Guide.



CHAPTER 3 EmberNet Node Configuration



Overview

This chapter describes how to configure an EmberNet Node.

Section Page Number

Setting the EmberNet Node network ID 3-2

Getting the EmberNet Node network ID 3-2

Getting the EmberNet Node’s product code 3-3

Creating a label string 3-4

Enabling routing 3-4

Notifying EmberNet Nodes of a host reset 3-5

Resetting an EmberNet Node 3-6

Changing the radio channel 3-8

Changing the radio transmitter power 3-9


e n t i a l

EmberNet Node Configuration

3-2

Setting the EmberNet Node network IDYou can set an EmberNet Node’s Network ID with the emberSetNodeId API function or ESP_SET_NODE_ID ESP command. Each node has a unique network-wide number. When you turn on an EmberNet Node, the host processor discovers the node ID by default. In most cases, you will not want to change the node’s network ID.

To change a node network ID

• Use the emberSetNodeId API function or ESP_SET_NODE_ID ESP command.

For more information, see the “ESP and API Reference” on page 8-1.

Getting the EmberNet Node network IDYou can get the network ID of an EmberNet Node with the emberGetNodeId API function or ESP_GET_NODE_ID ESP command. The node’s network ID is derived from the node’s product code and assigned automatically when you turn the node on. The network ID is the node’s unique ID in the EmberNet network.

After processing, the node returns the Network ID to the host processor. The host processor must handle the return message with the emberProcessIncomingMessage and emberHandleNodeId API functions, or ESP_NODE_ID ESP command. For more information, see “Processing Incoming Messages and Callbacks” on page 6-1.

To get a node’s network ID

1. Get the node’s network ID with the emberGetNodeId API function or ESP_GET_NODE_ID ESP command.

The node returns its network ID.

2. Handle the incoming node network ID with the appropriate API functions or ESP command. For more information, see “Processing Incoming Messages and Callbacks” on page 6-1.





Getting the EmberNet Node’s product code


Getting the EmberNet Node’s product code

You can get an EmberNet Node’s product code with the emberGetProductCode API function or ESP_GET_PRODUCT_CODE ESP command. The node’s product code is an 8-byte globally unique product code set during manufacturing. You cannot change the product code.

After processing, the node returns its product code to the host processor. The host processor must handle the return message with the emberProcessIncomingMessage and emberHandleProductCode API functions, or ESP_PRODUCT_CODE ESP command. For more information, see “Processing Incoming Messages and Callbacks” on page 6-1.

To get a node’s product code

1. Get the product code with the emberGetProductCode API function or ESP_GET_PRODUCT_CODE ESP command.

The node returns its product code.

2. Handle the incoming node product code with the appropriate API functions or ESP command. For more information, see “Processing Incoming Messages and Callbacks” on page 6-1.



n t i a l


3-4

Creating a label stringYou can create a label for an EmberNet Node with the emberSetLabelString API function or ESP_SET_LABEL_STRING ESP command. The label string can be a name or description of the node and may be a maximum of 32 bytes long, including a null character at the end of the string. This string may be used to create a unique description for a node, which the host application can use to identify an EmberNet Node in addition to the node’s network ID.

To create a label string

• Create the label with the emberSetLabelString API function or ESP_SET_LABEL_STRING ESP command.


Enabling routingBy default, routing on an EmberNet Node is enabled. However, in some applications, such as portable nodes or diagnostic tools, you may want to disable the node’s routing capability. You can disable and enable routing on an EmberNet Node with the emberEnableRouting API function or ESP_ENABLE_ROUTING ESP command.

To disable or enable routing

• Use the emberEnableRouting API function or ESP_ENABLE_ROUTING ESP command.





Notifying EmberNet Nodes of a host reset


Notifying EmberNet Nodes of a host resetYou can notify EmberNet Nodes that the host has reset with the emberHostHasReset API function or ESP_HOST_HAS_RESET ESP command. The host processor must reset using its own procedure.

To notify EmberNet Nodes of a host reset

• Use the emberHostHasReset API function or ESP_HOST_HAS_RESET ESP command.



n t i a l


3-6

Resetting an EmberNet Node

You can reset an EmberNet Node with the following sequence of functions or commands. The host application initiates reset of an EmberNet Node with the emberResetNode API function or ESP_RESET_NODE ESP command. These commands send a message from the host processor telling the EmberNet Node to reset itself.

After the node resets, it returns a message telling the host processor that the reset is complete. Upon receiving the return message, the host processor should process the incoming message with the emberProcessIncomingMessage API function, which passes the information to the emberHandleNodeReset message handler function. For more information about message handling, see “Processing Incoming Messages and Callbacks” on page 6-1.

The EmberNet Node relays, but does not process, messages until it receives a message from the host that acknowledges the EmberNet Node’s reset. Therefore, the host must acknowledge the node’s reset with the emberAcknowledgeNodeReset function or ESP_ACK_NODE_RESET ESP command.

Note that when you reset a node, information stored in the node’s volatile memory—such as radio channel, label string, and service handles—are lost or return to their default values.




Resetting an EmberNet Node


To reset an EmberNet Node

1. Use the emberResetNode API function or ESP_RESET_NODE ESP command to reset the EmberNet Node.

The EmberNet Node returns a message to the host processor saying that the node has reset.

2. If using the API, process the EmberNet Node’s return message with the ember-ProcessIncomingMessage API function. After processing, the emberProcessIn-comingMessage function directs the information to the appropriate message handler.

3. Process the reset message with the emberHandleNodeReset function or ESP_NODE_HAS_RESET ESP command.

4. Acknowledge the EmberNet Node’s reset with the emberAcknowledgeNodeRe-set API function or ESP_ACK_NODE_RESET ESP command.



n t i a l


3-8

Changing the radio channelYou can change the radio channel of an EmberNet Node with the emberSetRadioChannel API function or ESP_SET_RADIO_CHANNEL ESP command. EmberNet Node supports 12 separate radio channels. By default, the EmberNet Nodes are set to channel 6.

In overlaid networks where EmberNet Nodes are in close proximity to one another, you cannot use adjacent channels because of possible interference. As a result, a maximum of six channels are available in an overlaid EmberNet network. For example, channels 1, 3, 5, 7, 9, and 11 or 2, 4, 6, 8, 10, and 12 are valid combinations of radio channels in an overlaid network. However, you cannot use channels 1 and 2 at the same time in an overlaid network because of possible interference.

To change the radio channel

• Change the radio channel with the emberSetRadioChannel API function or ESP_SET_RADIO_CHANNEL ESP command.





Changing the radio transmitter power


Changing the radio transmitter powerYou can change the power level of an EmberNet Node’s radio transmitter channel with the emberSetRadioPower API function or ESP_SET_RADIO_POWER ESP command. An EmberNet Node provides four transmitter power levels. Table 3-1 shows the node’s radio power levels and corresponding values in DeciBels below 1 Milliwatt (dBm). The default is power level 2 (14 dBm)

Warning: Do not place powered nodes within 3 feet of each other to avoid desensitizing the radio..

To set the radio power level

• Use the emberSetRadioPower API function or ESP_SET_RADIO_POWER ESP command.


Table 3-1: Radio Transmitter Power Levels

Power Level Value (dBm)

0 0

1 7

2 14

3 20


n t i a l


3-10

CHAPTER 4 Services



Overview

This chapter describes services and service handles and how to configure the services across an EmberNet network.

Contents

Section Page Number

Subscribing an EmberNet Node to a service 4-2

Unsubscribing a Node from a service 4-2

Comparing service descriptions 4-4

Copying a service description 4-4

Getting a service handle 4-5

Releasing a service handle 4-6

Deconstructing a service handle 4-7


e n t i a l

Services

4-2

Subscribing an EmberNet Node to a serviceYou can subscribe an EmberNet Node to a service with the emberSubscribe API function or ESP_SUBSCRIBE ESP command. When a node subscribes to a service, it subscribes to flags for different message types.

To subscribe an EmberNet Node to a service

• Use the emberSubscribe API function or ESP_SUBSCRIBE ESP command.


Unsubscribing a Node from a serviceYou can unsubscribe an EmberNet Node from a service by setting the flags parameter to all zeroes in the emberSubscribe API command or ESP_SUBSCRIBE ESP command. Unsubscribing a service breaks the link between the service handle and deletes all states associated with the service, including service handles.

To unsubscribe a service

• Use the emberSubscribe API command or ESP_SUBSCRIBE ESP command. Set the flags parameter to all zeroes.





Service Description versus Service Handle


Service Description versus Service HandleThe differences between a service description and a service handle are described in the following table:

Table 4-1: Service Descriptions versus Service Handle

Type Description

service description A six byte description of a service that a node offers.

service handles Represent things such as “ModBus Slave” or “Tem-perature input.”

Considered shorthand for a particular service at a par-ticular node.

Indicate things such as “ModBus node attached to device #6” or “Temperature at node 47”.

Constructed during the discover process.


n t i a l

Services

4-4

Comparing service descriptionsYou can compare service descriptions with the emberSvcDescriptionsAreEqual API function. Comparing service descriptions allows you to ensure that a node has the most current version of a service description.

To compare service descriptions

• Use the emberSvcDescriptionsAreEqual API function.


Copying a service descriptionYou can copy a service description from one location to another with the emberSvcCopyDescription API function. Copying a service description allows you to replace an outdated service description.

To copy a service description

• Use the emberSvcCopyDescription API function.





Getting a service handle


Getting a service handleDiscovery packets (packets with the announcement or request flag enabled) automatically generate a service handle as they pass through the network. However, you can request the handle for a service implemented on a particular EmberNet Node with the emberGetServiceHandle API function or ESP_GET_SERVICE_HANDLE ESP command. If a service handle does not already exist, the EmberNet Node generates a service handle automatically and returns it to the host processor.

After processing, the node returns the service handle to the host processor. The host processor must handle the return message with the emberProcessIncomingMessage and emberHandleServiceHandle API functions, or ESP_SERVICE_HANDLE ESP command. For more information, see “Processing Incoming Messages and Callbacks” on page 6-1.

See “Releasing a service handle” on page 4-6 to release a service handle.

To get a service handle

1. Use the emberGetServiceHandle API function or ESP_GET_SERVICE_HANDLE ESP command.

The node returns the service handle.

2. Handle the incoming service handle with the appropriate API functions or ESP command. For more information, see “Processing Incoming Messages and Callbacks” on page 6-1.



n t i a l

Services

4-6

Releasing a service handleYou can release a service handle with the emberReleaseServiceHandle API function or ESP_RELEASE_SERVICE_HANDLE ESP command. Releasing the service handle tells the EmberNet Node that the host no longer requires a service handle.

After processing, the node acknowledges the released service handle to the host processor. The host processor must handle the return message with the emberProcessIncomingMessage and emberHandleReleasedServiceHandle API functions, or ESP_SERVICE_HANDLE_RELEASED ESP command. For more information, see “Processing Incoming Messages and Callbacks” on page 6-1.

To release a service handle

1. Use the emberReleaseServiceHandle API function or ESP_RELEASE_SERVICE_HANDLE ESP command.

The node returns an acknowledgement that it has released the service handle.

2. Process the incoming acknowledgement of a released service handle with the appropriate API functions or ESP command. For more information, see “Processing Incoming Messages and Callbacks” on page 6-1.





Deconstructing a service handle


Deconstructing a service handleYou can deconstruct a service handle with the emberDeconstructServiceHandle API function or ESP_DECONSTRUCT_SERVICE_HANDLE ESP command. If you know the service handle, deconstructing the service handle allows you to obtain the corresponding network ID of the EmberNet Node that implements the service.

After processing, the node returns the service handle, node ID, and service description. You must process the return message with the emberProcessIncomingMessage and emberHandleServiceHandle API functions, or the ESP_SERVICE_HANDLE ESP command. For more information, see “Processing Incoming Messages and Callbacks” on page 6-1.

To deconstruct a service handle

1. Use the emberDeconstructServiceHandle API function or ESP_DECONSTRUCT_SERVICE_HANDLE ESP command.

The node returns the service handle, service description, and node network ID.

2. Process the returned data with the appropriate API functions or ESP command. For more information, see “Processing Incoming Messages and Callbacks” on page 6-1.



n t i a l

Services

4-8

CHAPTER 5 EmberNet Communications



Overview

There are two methods of communication in an EmberNet network:

• Broadcast—Messages relayed to all nodes in the network.• Unicast—Message relayed to a specific node in a network.

This chapter describes how and when to use these methods.

Contents.

Section Page Number

Configuring Broadcast communications 5-2

Configuring Unicast communications 5-3

Obtaining Route Cost 5-4


e n t i a l

EmberNet Communications

5-2

Configuring Broadcast communications

You can broadcast messages to all EmberNet Nodes in a network with the emberBroadcast API function or ESP_BROADCAST ESP command. You can also broadcast messages to nodes within a particular radius, or number of hops. If you broadcast to a service, all nodes in the network hear and relay the message, but only those nodes that subscribe to the service process the message and send it to the host processor.

To broadcast messages

• Use the emberBroadcast API function or ESP_BROADCAST ESP command.





Configuring Unicast communications


Configuring Unicast communications

You can unicast a message to an individual EmberNet Node with the emberUnicast API function or ESP_UNICAST ESP command.

To unicast a message

• Use the emberUnicast API function or ESP_UNICAST ESP command.



n t i a l

EmberNet Communications

5-4

Obtaining Route Cost

You can obtain the route cost of sending a service handle with the emberGetServiceCost API function or ESP_GET_SERVICE_COST ESP command.

In an EmberNet network, the route’s cost is the number of hops required to traverse the network to the destination node. As a rule of thumb, the higher the number of hops, the poorer the performance. EmberNet supports a maximum of 256-hop radius in a network.

You can use the emberGetServiceCost API function or ESP_Service_Cost ESP command to diagnose the performance of an EmberNet Node’s connection. For example, you can use the emberGetServiceCost API function to obtain the cost, or number of hops, required for a particular node to communicate with another node. If the cost is too high, you can add repeaters between, or move a node to a better location to improve position in the path. You could also use these commands to determine how close a particular node is to its neighbors. In general, the higher the route cost, the poorer the performance.

After processing, the node returns the service cost to the host processor. The host processor must handle the return message with the emberProcessIncomingMessage and emberHandleServiceCost API functions, or ESP_SERVICE_COST ESP command. For more information, see “Processing Incoming Messages and Callbacks” on page 6-1.

To obtain route cost

1. Use the emberGetServiceCost API function or ESP_GET_SERVICE_COST ESP command.

The node returns the route cost.

2. Handle the incoming acknowledgement of a released service handle with the appropriate API functions or ESP command. For more information, see “Processing Incoming Messages and Callbacks” on page 6-1.




CHAPTER 6 Processing Incoming Messages and Callbacks



Overview

This chapter describes how the host processor can process messages returned from an EmberNet Node.

Contents

Section Page Number

About Handlers and Callbacks 6-2

API return values 6-5

Processing Incoming Messages with the Host API 6-6


e n t i a l

Processing Incoming Messages and Callbacks

6-2

About Handlers and CallbacksWhen the host receives messages from a node, it must pass the incoming data to the appropriate handler. A handler is a callback function that processes incoming data.

Functions that “get” values (E.g. emberGetServiceHandle), do not return values - that they appear to be “getting”. Each “get” function requires a corresponding “handle” function, written by you, that does something with the information generated by the “get” function.

When designing the API, we didn't want to make any assumptions about the processing power of the host CPU, so we decided to do as much work as possible on the EmberNode's CPU. This work includes managing most of the data needed to do any EmberNet-related tasks (i.e. service subscriptions, handles, etc) in the EmberNode's memory.

The end result of all of this is that whenever you request information from the host API, it has to forward the request to the EmberNode via the SPI bus. Because we are dealing with two independent CPU’s, there is no guarantee that the next message coming over the SPI bus will contain the information that you asked for. In fact on a busy network, the next message that the Host API sees after you ask for information could very well be normal network traffic that happened to arrive at the EmberNode around the same time that your “get” request got executed by the Host CPU.

We handle this by having emberProcessIncomingMessage serve as the dispatch point for ALL messages (including results from "Get" calls). This routine will execute YOUR emberHandleXXX (i.e. emberHandleServiceHandle) to process the information that you asked for when it arrives.

The host processor polls for incoming data arriving on the SPI channel from the EmberNet Node (Figure 6-1). When data is present, the data is directed to the emberProcessIncomingMessage API function. Based on the message’s semantics




About Handlers and Callbacks


and flags, the emberProcessIncomingMessage API function passes the data to the appropriate callback function.

Figure 6-1: Processing Incoming Messages

IncomingMessageFunction

emberProcessIncomingMessage

Product CodeHandler

Network ID Handler

Service HandleHandler

AcknowledgementHandlers

Incoming DataHandler

Incoming DiscoveryHandler

Error Handler

Service CostHandler

Callback Functions(User-Defined Handlers)

IncomingMessage Sorter

Host Processor0009

EmberNetNode

( ( ( ) ) )5-wire

SPI Channel


n t i a l


6-4

The EmberNet Host API defines the following handlers:

• emberHandleNodeReset• emberHandleError• emberHandleIncomingData• emberHandleIncomingDiscovery• emberHandleNodeId• emberHandleProductCode• emberHandleServiceCost• emberHandleServiceHandle• emberHandleReleasedServiceHandle

The host processor should call the handler functions to process the incoming data. You must implement each handler and how it processes incoming data. Use the following rules of thumb when implementing handlers:

• Complex data structures, like product codes, are not persistent and must be copied into the body of the handler.

• Packets are not persistent and must be copied into the body of the handler.• The packet processing function should not be invoked in an interrupt

context.

If you use the EmberNet SPI Protocol (ESP) commands to create your own API, you can develop an equivalent function to emberProcessIncomingMessage API function to sort and process incoming messages. The ESP defines the following commands to handle incoming data:

• ESP_NODE_HAS_RESET• ESP_ERROR_REPORT• ESP_INCOMING_DATA• ESP_INCOMING_DISCOVERY• ESP_NODE_ID• ESP_PRODUCT_CODE• ESP_SERVICE_HANDLE• ESP_SERVICE_HANDLE_RELEASED• ESP_SERVICE_COST




API return values


API return valuesTable 6-1 shows return values for the EmberNet Host API. Messages are returned asynchronously. If you send a message that requires a response, you should not expect the response in the next message received.

Table 6-1:API Return Values

Asynchronous API Return Value Description

EMBER_NO_ERROR Everything was OK.

EMBER_ERROR_LABEL_STRING_TOO_LONG The caller tried to set a label string longer than 32 characters.

EMBER_ERROR_INVALID_CHANNEL The radio channel number supplied was not in the valid range.

EMBER_ERROR_INVALID_POWER The power level supplied was not in the valid range.

EMBER_ERROR_BUS_BUSY No bytes were written during busWrite operation.


n t i a l


6-6

Processing Incoming Messages with the Host API

You can process incoming messages with the following sequence of API function calls.

1. Pass the incoming data to the emberProcessIncomingMessage API function.2. Depending on the type of message, process the incoming data with one of the

following user-defined API callback or handler functions:• emberHandleNodeReset• emberHandleError• emberHandleIncomingData• emberHandleIncomingDiscovery• emberHandleNodeId• emberHandleProductCode• emberHandleServiceCost• emberHandleServiceHandle• emberHandleReleasedServiceHandle


Note: If you set multiple flags (i.e. both discovery and data), the discovery flag will take precedence. This will force the emberHandleIncomingDiscovery handle to be called, instead of your intended function. Also, your disovery handle must also have a corresponding data handling function.



CHAPTER 7 Debug Logging



Overview

The EmberNet Host API contains functions that, when included in a host applica-tion, can generate debug messages. These debug messages can be sent over the Ethernet debug channel connection through the EmberNet/Ethernet connection board, which is attached to the EmberNet breakout board. The Ember Debug Log-ging Utility, a Java application, runs on a development PC (also connected via Ethernet) to collect and format the debug messages to aid in the debugging of EmberNet host applications.

Note: The EmberNet/Ethernet connection boards and Ember Debug Logging Util-ity are included in the EmberNet Advanced and Premium Developer Kits.

This chapter describes how and when to use these methods.

Contents

Section Page Number

Configuring Debug Messaging 7-2

Sending Debugging Raw Data Messages 7-3

Sending Debugging String Messages 7-4


e n t i a l

Debug Logging

7-2

Configuring Debug Messaging

You can manage error reporting on the Node, using the emberDebugConfig API function. Debug commands are sent to the node to specify the debug data that the node will report over the debug channel.

Note: In order to use this API function, you must have configured your develop-ment system for debugging. Refer to the “Debugging your Host Application” chapter in the EmberNet Developer Kit User’s Guide for more information.

Three types of debug messages can be generated and logged:

• Two levels of SPI traffic logging:• Log ESP commands sent and received by the node.• Log ESP commands and full ESP payloads sent and received by the node.

• Log errors generated on the node. • Log service headers received by the node over the radio.

After you have specified the debug data that you would like the Node to report, the debug data will be transmitted via the EmberNet/Ethernet connection board.





Sending Debugging Raw Data Messages


Sending Debugging Raw Data Messages

You can set up the host to print out raw data through the EmberNet/Ethernet connection board, using the emberSendDebugRawData API function. The entire message will be sent as raw bytes are printed in hex, with a space between each byte.




n t i a l

Debug Logging

7-4

Sending Debugging String Messages

You can set up your host application to print out data in string format through the EmberNet/Ethernet connection board, using the emberSendDebugString API func-tion. The entire message will be sent as it was received, in string format.





CHAPTER 8 ESP and API Reference



Overview

This chapter describes the EmberNet Host API functions and EmberNet SPI Proto-col (ESP) commands..

Contents

Section Page Number

ESP Commands 8-2

EmberNet Host API functions 8-5


e n t i a l

ESP and API Reference

8-2

ESP Commands

Table 8-1 provides a cross reference of EmberNet Host API functions and EmberNet SPI Protocol (ESP) commands.

Table 8-1: API Function and ESP Command Cross Reference

API Function ESP Command

emberAcknowledgeNodeReset ESP_ACK_NODE_RESET

emberBroadcast ESP_BROADCAST

emberDebugConfig No ESP equivalent

emberDeconstructServiceHandle ESP_DECONSTRUCT_SERVICE_HANDLE

emberEnableRouting ESP_ENABLE_ROUTING

emberGetNodeId ESP_GET_NODE_ID

emberGetProductCode ESP_GET_PRODUCT_CODE

emberGetServiceCost ESP_GET_SERVICE_COST

emberGetServiceHandle ESP_GET_SERVICE_HANDLE

emberHandleError ESP_ERROR_REPORT

emberHandleIncomingData ESP_INCOMING_DATA

emberHandleIncomingDiscovery ESP_INCOMING_DISCOVERY

emberHandleNodeId ESP_NODE_ID

emberHandleNodeReset ESP_NODE_HAS_RESET

emberHandleProductCode ESP_PRODUCT_CODE

emberHandleReleasedServiceHandle ESP_SERVICE_HANDLE_RELEASED

emberHandleServiceCost ESP_SERVICE_COST

emberHandleServiceHandle ESP_SERVICE_HANDLE

emberHostHasReset ESP_HOST_HAS_RESET

emberProcessIncomingMessage No ESP equivalent

emberReleaseServiceHandle ESP_RELEASE_SERVICE_HANDLE

emberResetNode ESP_RESET_NODE

emberSendDebugRawData No ESP equivalent

emberSendDebugString No ESP equivalent

emberSetLabelString ESP_SET_LABEL_STRING

emberSetNodeId ESP_SET_NODE_ID




ESP Commands


Table 8-2 shows the ESP commands and parameters.

emberSetRadioChannel ESP_SET_RADIO_CHANNEL

emberSetRadioPower ESP_SET_RADIO_POWER

emberSubscribe ESP_SUBSCRIBE

emberSvcCopyDescription No ESP equivalent

emberSvcDescriptionsAreEqual No ESP equivalent

emberUnicast ESP_UNICAST

Table 8-2: ESP Commands

ESP Command Length Direction Additional FieldsESP_ACK_NODE_RESET 1 OutgoingESP_BROADCAST — Outgoing payload | service id | flags |

radiusESP_RESET_NODE 1 OutgoingESP_DECONSTRUCT_SERVICE_HANDLE

2 Outgoing service handle

ESP_ENABLE_ROUTING 2 Outgoing enable (T/F)ESP_GET_NODE_ID 1 OutgoingESP_GET_PRODUCT_CODE 1 OutgoingESP_GET_SERVICE_COST 2 Outgoing service handleESP_GET_SERVICE_HANDLE 4 Outgoing service id | node (High

Order Byte) | node (Low Order Byte)

ESP_NODE_HAS_RESET 3 IncomingESP_ERROR_REPORT 2 Incoming error codeESP_INCOMING_DATA — Incoming payload | service id | flags |

sender id (High Order Byte) | sender id (Low Order Byte)

ESP_INCOMING_DISCOVERY — Incoming payload | service id | flags | sender handle | cost

Table 8-1: API Function and ESP Command Cross Reference (Continued)

API Function ESP Command


n t i a l


8-4

ESP_NODE_ID 3 Incoming node id (High Order Byte) | node id (Low Order Byte)

ESP_PRODUCT_CODE 9 Incoming product code (8 bytes)ESP_SERVICE_HANDLE_RELEASED — IncomingESP_SERVICE_COST 3 Incoming service handle | costESP_SERVICE_HANDLE 5 Incoming service handle | service |

node id (High Order Byte) | node id (Low Order Byte)

ESP_HOST_HAS_RESET 1 IncomingESP_RELEASE_SERVICE_HANDLE 2 Outgoing service handleESP_SET_LABEL_STRING — Outgoing label stringESP_SET_NODE_ID 3 Outgoing node id (High Order Byte)

| node id (Low Order Byte)

ESP_SET_RADIO_CHANNEL 2 Outgoing channel (1 to 12)ESP_SET_RADIO_POWER — Outgoing level (0 to 3)ESP_SUBSCRIBE 3 Outgoing service id | flagsESP_UNICAST — Outgoing payload | service handle |

flags

Table 8-2: ESP Commands (Continued)

ESP Command Length Direction Additional Fields




EmberNet Host API functions



This section provides a listing of the following EmberNet Host API functions:

Table 8-3: EmberNet Host API Functions

emberAcknowledgeNodeReset 8-7

emberBroadcast 8-8

emberDebugConfig 8-10

emberDeconstructServiceHandle 8-11

emberEnableRouting 8-12

emberGetNodeId 8-13

emberGetProductCode 8-14

emberGetServiceCost 8-15

emberGetServiceHandle 8-16

emberHandleError 8-17

emberHandleIncomingData 8-18

emberHandleIncomingDiscovery 8-20

emberHandleNodeId 8-22

emberHandleNodeReset 8-23

emberHandleProductCode 8-24

emberHandleReleasedServiceHandle 8-25

emberHandleServiceCost 8-26

emberHandleServiceHandle 8-27

emberHostHasReset 8-28

emberProcessIncomingMessage 8-29

emberReleaseServiceHandle 8-30

emberResetNode 8-31

emberSendDebugRawData 8-32

emberSendDebugString 8-33

emberSetLabelString 8-34

emberSetNodeId 8-35

emberSetRadioChannel 8-36

emberSetRadioPower 8-37

emberSubscribe 8-38


n t i a l


8-6

Note: Many API calls return an error code of type EmberStatus. For calls that result in a message being sent to the EmberNet Node via the high-speed serial inter-face, it is extremely important that applications monitor the return value. If the high-speed serial line is busy, these calls will not be able to send their message and the application must repeat the call.

emberSvcCopyDescription 8-39

emberSvcDescriptionsAreEqual 8-40

emberUnicast 8-41

Table 8-3: EmberNet Host API Functions






emberAcknowledgeNodeReset

Use the emberAcknowledgeNodeReset function to acknowledge the node’s reset. The node continues to pass traffic while waiting for the acknowledgement, but the host processor must acknowledge the reset before the node resumes processing of messages.

SyntaxEmberStatus emberAcknowledgeNodeReset(void);

Packet Data

ESP Command ESP_ACK_NODE_RESET

ReturnsEMBER_NO_ERRORS No errors.

Note: If you set multiple flags (i.e. both discovery and data), the discovery flag will take precedence. This will force the emberHandleIncomingDiscovery handle to be called, instead of this function. Also, your disovery handle must also have a corre-sponding data handling function.


n t i a l


8-8

emberBroadcast

Use the emberBroadcast function to send a message to all nodes in a network. The broadcast message reaches only the host processor on those nodes subscribed to the given service and message type.

SyntaxEmberStatus emberBroadcast(

EmberServiceDescription* service,int8u flags,int8u radius,int8u* contents,int8u length);

Packet Information

application data

service description 6 bytes

flags 1 byte

radius 1 byte

ESP command ESP_BROADCAST







Parametersservice The ID of the service for which the message is

intended.

flags Flag indicating the message's semantics. Choose one of the following: EMBER_SVC_ANNOUNCE EMBER_SVC_REQUEST EMBER_SVC_DATA

radius A limit on the broadcast radius in number of hops. The message travels no more than this number of hops as it traverses the network. The valid range is 1 to 255 hops.

contents The data to be transmitted in the message.

length The length of the data. The length must be less than the defined maximum packet length.


EMBER_ERROR_INVALID_FLAGS The flags byte is ill-formed.

EMBER_ERROR_MESSAGE_TOO_LONG Message is too long.


n t i a l


8-10

emberDebugConfig

The emberDebugConfig API function provides a way for the host to manage error reporting on the Node. Debug commands are sent from the host to the node to specify the debug data that the node will report back over the debug channel.


SyntaxEmberStatus emberDebugConfig(DebugCommandType

debugCommand);

ParametersdebugCommand The level of debugging enabled or disabled

Table 8-4: Debug Commands


Note: This is a host-only function, and there is no corresponding ESP command.

debugCommand Meaning

DEBUG_COMMAND_ERRORS_ON Enables SPI error reporting

DEBUG_COMMAND_ERRORS_OFF Disables SPI error reporting

DEBUG_COMMAND_SPI_TRAFFIC_FULL_ON Enables full reporting of SPI traffic

DEBUG_COMMAND_SPI_TRAFFIC_CMD_ON Enables command byte reporting of SPI traffic

DEBUG_COMMAND_SPI_TRAFFIC_OFF Disables SPI traffic reporting

DEBUG_COMMAND_SERVICE_ON Enables reporting of service headers

DEBUG_COMMAND_SERVICE_OFF Disables reporting of service headers






emberDeconstructServiceHandle

If you have a service handle, use the emberDeconstructServiceHandle function to get the corresponding node network ID and service description.

SyntaxEmberStatus emberDeconstructServiceHandle(

EmberServiceHandle serviceHandle);

Packet Data

service handle 1 byte

ESP command ESP_DECONSTRUCT_SERVICE_HANDLE

ParametersserviceHandle The handle about which data is being

requested.


lopment Guide 120-0003-210 8-11

n t i a l


8-12

emberEnableRouting

Use the emberEnableRouting function to enable or disable the EmberNet Node to route packets on behalf of others. Routing is enabled by default on a node.

SyntaxEmberStatus emberEnableRouting(boolean enable);

Packet Data

enable 1 byte

ESP command ESP_ENABLE_ROUTING

Parameters enable TRUE to enable routing, FALSE to disable.







emberGetNodeId

Use the emberGetNodeId function to get a EmberNet Node coprocessor's network ID. Nodes have a network-wide unique ID that is used for routing This network ID can also be referenced by the service handle to indicate the sender of an unicast packet.

SyntaxEmberStatus emberGetNodeId (void);

Packet Data

ESP command ESP_GET_NODE_ID


lopment Guide 120-0003-210 8-13

n t i a l


8-14

emberGetProductCode

Use the emberGetProductCode function to get the EmberNet Node's product code. Every node has an 8-byte globally unique product code. The product code is set during manufacturing and never changed.

SyntaxEmberStatus emberGetProductCode (void);

Packet DataESP command ESP_GET_PRODUCT_CODE







emberGetServiceCost

Use the emberGetServiceCost function to get the cost of sending a packet to a particular service handle.

SyntaxEmberStatus emberGetServiceCost(


Packet Dataservice handle 1 byte

ESP command ESP_GET_SERVICE_COST

ParametersserviceHandle The handle about which cost information is

required.


lopment Guide 120-0003-210 8-15

n t i a l


8-16

emberGetServiceHandle

Use the emberGetServiceHandle function to get the handle for a service as implemented on a particular node.

SyntaxEmberStatus emberGetServiceHandle (

EmberServiceDescription* service,EmberNodeID nodeId);

Packet Dataservice description 6 bytes

node id 2 bytes

ESP command ESP_GET_SERVICE_HANDLE

Parametersservice The ID of the service of interest.

nodeId The ID of the node implementing the service.







emberHandleError

Use the emberHandleError function to handle an error report from an EmberNet Node.

Syntaxvoid emberHandleError(EmberStatus errorCode);

Packet Data

error code 1 byte

ESP command ESP_ERROR_REPORT

ParameterserrorCode The error code that is being reported.

.

Table 8-5: EmberNet Error Codes

Code Meaning

0x1F Invalid ESP command code.

0x23 Subscription table is full.

0x24 Subscription not found.

0x25 Service table is full.

0x26 Invalid service handle.

0x28 Malformed or otherwise invalid service handle (received over radio).

0x29 Cost to service handle unknown.

lopment Guide 120-0003-210 8-17

n t i a l


8-18

emberHandleIncomingData

Use the emberHandleIncomingData function to handle an incoming unicast directed to the node. Data messages come packaged with the EmberNet Node ID of the sender.

Syntaxvoid emberHandleIncomingData(

int8u* contents,int16u length,EmberServiceDescription* service,int8u flags,EmberNodeID senderId);

Packet Data

application data


flags 1 byte

sender node id 2 bytes

ESP command ESP_INCOMING_DATA

Parameterscontents The contents of the message.

length The length of the contents.

service The ID of the service for which the message is intended.

flags The flag indicating the message's semantics. Choose one of the following: EMBER_SVC_ANNOUNCE EMBER_SVC_REQUEST EMBER_SVC_DATA

senderId The node ID of the sender.







lopment Guide 120-0003-210 8-19

n t i a l


8-20

emberHandleIncomingDiscovery

Use the emberHandleIncomingDiscovery function to handle a discovery (announcement or request) message.

Note: It is very important to attention to the sender handle argument. This handle represents memory on the EmberNet Node and must be managed carefully. When an application wants to send a message to a corresponding service/node, you must cache the handle and use it when you call emberUnicast(). If you don’t need the handle, first check to see if it is cached, then call emberReleaseServiceHandle() to free the Node’s memory.

When unnecessary handles are not freed, the node consumes mem-ory each time a new discovery message arrives. After the service han-dle is exhausted, the node can not process new discovery messages, and the host can not receive more discovery notices.

Syntaxvoid emberHandleIncomingDiscovery (

int8u* contents, int16u length, EmberServiceDescription* service,int8u flags,EmberServiceHandle senderHandle,EmberCostValue cost);

Packet Dataapplication data


flags 1 byte

sender handle 1 byte

cost to respond 1 byte

ESP command ESP_INCOMING_DISCOVERY






Parameterscontents The contents of the message.

length The length of the contents.

serviceId The id of the service for which the message is intended.


senderHandle A handle for the given service on the sender.

cost The estimated cost to respond to this message.


lopment Guide 120-0003-210 8-21

n t i a l


8-22

emberHandleNodeId

Use the emberHandleNodeId to handle the Node’s incoming network ID.

Syntaxvoid emberHandleNodeId (EmberNodeID id);

Packet Datanode id 2 bytes

ESP command ESP_NODE_ID






emberHandleNodeReset

Use the emberHandleNodeReset function to process a message from a node indicating that the EmberNet Node has reset.

Syntaxvoid emberHandleNodeReset (void);

Packet Data

ESP command ESP_NODE_HAS_RESET

lopment Guide 120-0003-210 8-23

n t i a l


8-24

emberHandleProductCode

Use the emberHandleProductCode function to handle the response to a call to the emberGetProductCode function.

Syntaxvoid emberHandleProductCode(

EmberNodeProductCode* productCode);

Packet Dataproduct code 8 bytes

ESP command ESP_PRODUCT_CODE

ParametersproductCode The product code that has been returned.






emberHandleReleasedServiceHandle

Use the emberHandleReleasedServiceHandle function to process the acknowledgement of a released service handle.

Syntaxvoid emberHandleReleasedServiceHandle(

EmberServiceHandle handle);


ESP command ESP_SERVICE_HANDLE_RELEASED

Parametershandle The released service handle.

lopment Guide 120-0003-210 8-25

n t i a l


8-26

emberHandleServiceCost

Use the emberHandleServiceCost function to handle a cost value report from the node. In response to a call to the emberGetServiceCost function for a particular service handle, the node generates a message that contains the estimated cost to send something to that service handle.

Syntaxvoid emberHandleServiceCost(

EmberServiceHandle serviceHandle, boolean CostIsKnown,EmberCostValue cost);


cost 1 byte

ESP command ESP_SERVICE_COST

ParametersserviceHandle A service handle about which cost information

has been requested.

CostIsKnown Zero if there is no known route to the service. One if there is a known route.

cost The cost to send a packet to the destination.






emberHandleServiceHandle

Use the emberHandleServiceHandle function to handle a report from the host of information about a service handle. This function handles the response to the emberDeconstructServiceHandle and emberGetServiceHandle functions.

Syntaxvoid emberHandleServiceHandle(

EmberServiceHandle serviceHandle,EmberServiceDescription* service,EmberNodeID nodeId);

Packet Dataservice description 6 bytes

node id 2 bytes

handle 1 byte

ESP command ESP_SERVICE_HANDLE

ParametersserviceHandle A service handle about which information has

been requested.

service The service description associated with the handle.

nodeId The corresponding node network ID.

lopment Guide 120-0003-210 8-27

n t i a l


8-28

emberHostHasReset

Use the emberHostHasReset function to indicate that the host processor has reset.

SyntaxEmberStatus emberHostHasReset(void);

Packet DataESP command ESP_HOST_HAS_RESET







emberProcessIncomingMessage

Use the emberProcessIncomingMessage function to process an incoming message from an EmberNet Node. When the host processor receives a message from the node, the host processor should pass the message to this general-purpose handler routine, which in turn parses the message and calls the appropriate application-specific handler function. The message pointer points to the length byte at the beginning of the message.

SyntaxEmberStatus emberProcessIncomingMessage(

int8u* message,int16u length);

Parametersmessage The content of the message.

length The length of the message.


EMBER_ERROR_INVALID_MESSAGE The message was ill-formed.

lopment Guide 120-0003-210 8-29

n t i a l


8-30

emberReleaseServiceHandle

Use the emberReleaseServiceHandle function to tell the EmberNet Node that the host no longer uses a service handle.

SyntaxEmberStatus emberReleaseServiceHandle(



ESP command ESP_RELEASE_SERVICE_HANDLE

ParametersserviceHandle The handle being released.







emberResetNode

Use the emberResetNode function to instruct the EmberNet Node to reset.

SyntaxEmberStatus emberResetNode (void);

Packet DataESP command ESP_RESET_NODE


lopment Guide 120-0003-210 8-31

n t i a l


8-32

emberSendDebugRawData

The emberSendDebugRawData provides a way for the host to print out raw data through the Ethernet debug channel (using the RabbitCore board attached to the node’s breakout board).


SyntaxEmberStatus emberSendDebugRawData(int8u *data,

int8u length);

Parametersdata The contents of the data

length The length of the message








emberSendDebugString

The emberSendDebugString function provides a way for the host to print out debug strings through the Ethernet debug channel. (The node and a RabbitCore board must be attached to a breakout board to enable this function).


SyntaxEmberStatus emberSendDebugString(char *string);

Parametersstring The contents of the data



lopment Guide 120-0003-210 8-33

n t i a l


8-34

emberSetLabelString

Use the emberSetLabelString function to create the EmberNet Node's label string. Each node may have a label string that the monitor or other applications can use to describe the node. The string may be a maximum of 32 characters including the null at the end.

SyntaxEmberStatus emberSetLabelString (char* string,

int8u* messageBuffer);

Packet Datalabel string Up to 32 characters.

ESP command ESP_SET_LABEL_STRING

Parametersstring The intended label string.

messageBuffer Buffer used during transmission of the label string.


EMBER_ERROR_LABEL_STRING_TOO_LONG Label string is too long.






emberSetNodeId

Use the emberSetNodeId function to set the EmberNet Node's network id. Nodes have a network-wide unique ID that is used for routing and sometimes, by the service code to indicate the sender of an unicast packet.

SyntaxEmberStatus emberSetNodeId (EmberNodeID id);

Packet Datanode id 2 bytes

ESP command ESP_SET_NODE_ID

Parameters: id The EmberNet Node network ID to set.

ReturnsEMBER_NO_ERRORS No error.

lopment Guide 120-0003-210 8-35

n t i a l


8-36

emberSetRadioChannel

Use the emberSetRadioChannel function to set the EmberNet Node’s radio channel. The radio used in every node has 12 channels numbered 1 to 12. The default is channel 12.

SyntaxEmberStatus emberSetRadioChannel (int8u channel);

Packet Datachannel 1 byte

ESP command ESP_SET_RADIO_CHANNEL

Parameterschannel Radio channel. Valid range is 1 to 12.


EMBER_INVALID_CHANNEL The given channel number was wrong.






emberSetRadioPower

Use the emberSetRadioPower to set the power level of EmberNet Node’s radio. The radio in an EmberNet Node has four transmit power levels. Table 8-6 shows the power levels for the EmberNet Node transmitter power ranges in DeciBels below 1 Milliwatt (dBm). The default is power level 2 (14 dBm).

SyntaxEmberStatus emberSetRadioPower(int8u power);

Packet Datapower 1 byte

ESP command ESP_SET_RADIO_POWER

Parameters power Transmitter power level. Valid range is 0 to 3.

Level 2 is the default power level.


EMBER_ERROR_INVALID_POWER The given power level is incorrect.

Table 8-6: EmberNet Node Radio Power Levels

Power Level Value (dBm)

0 0

1 7

2 14

3 20

lopment Guide 120-0003-210 8-37

n t i a l


8-38

emberSubscribe

Use the emberSubscribe function to express interest in messages with a given service and semantics. The host processor can choose what kinds of messages it wants to receive with respect to a particular service. Set the flags parameter to all zeroes to unsubscribe.

SyntaxEmberStatus emberSubscribe(

EmberServiceDescription* service, int8u flags);

Packet Dataservice 6 bytes

flags 1 byte

ESP command ESP_SUBSCRIBE

Parametersid The id of the service to which the node is being

subscribed (or unsubscribed).

flags The flag byte indicating the terms of the subscription:

EMBER_SVC_ANNOUNCE

EMBER_SVC_REQUEST

EMBER_SVC_DATA


EMBER_ERROR_INVALID_FLAGS The message’s flags byte is ill-formed.






emberSvcCopyDescription

Use the emberSvcCopyDescription function to copy one service description to another.

SyntaxEmberServiceDescription* emberSvcCopyDescription(

EmberServiceDescription* source,EmberServiceDescription* destination);

Parameterssource The description to copy from.

destination The description to copy to.

ReturnsThe destination description.


lopment Guide 120-0003-210 8-39

n t i a l


8-40

emberSvcDescriptionsAreEqual

Use the emberSvcDescriptionsAreEqual function to test whether or not two service descriptions are equal.

Syntaxboolean emberSvcDescriptionsAreEqual(

EmberServiceDescription* d1,EmberServiceDescription* d2);

Parametersd1 The first description to test.

d2 The second description to test.

ReturnsTRUE Service descriptions are equal.

FALSE Service descriptions are not equal.







emberUnicast

Use the emberUnicast function to unicast a message to a particular EmberNet Node and service. A unicast sends a message to a particular node and service represented by a service handle.

SyntaxEmberStatus emberUnicast(

EmberServiceHandle serviceHandle,int8u flags,int8u* contents,int8u length);

Packet Dataapplication data

service handle 1 byte

flags 1 byte

ESP command ESP_UNICAST

ParametersserviceHandle The handle of the node/service pair for which

the unicast is intended.


contents The data to be transmitted in the message.

length The length of the data. The length must be less than the defined limit for packet size.

lopment Guide 120-0003-210 8-41

n t i a l


8-42


EMBER_ERROR_INVALID_FLAGS The flags byte is ill-formed.

EMBER_ERROR_MESSAGE_TOO_LONG Message is too long.




120-0003-210 EmberNet A


Index

A

aboutcallbacks 6-2handlers 6-2

acknowledgments 1-7adjacent radio channels 3-8announcement 1-15

discovery by, example 1-18for discovery purposes 1-18service handles 4-5

APIAtmel 8535 processor 2-4binary image 2-4, 2-7callbacks 6-4data structures 2-9defined 2-4ESP comparison matrix 8-2formatting packets 2-4handlers 6-4

model 2-5processing messages with 6-6reference 8-5return values 6-5source code 2-4, 2-7

Atmel 8535 processor 2-4, 2-7

B

binary image, API 2-4, 2-7Board, Ember Breakout 2-7broadcast messaging 1-3, 5-1, 5-4

configuring 5-2example 1-4radius 5-2sending a message 8-8sending message 5-2to a service 1-5

broadcast vs. unicast 1-2, 1-6

pplication Development Guide 1-1

i d e n t i a l

Index

1-2

C

callbacks 6-2changing

radio channel 3-8radio power level 3-9

code, source 2-7command

byte 2-6values, defined 2-8

commands, ESP 8-3comparing service descriptions 4-4, 8-40configuring

broadcast communications 5-2broadcast radius 5-2unicast communications 5-3

copying a service description 4-4, 8-39cost, determining route 5-4creating, label string 3-4

D

data 1-15length byte 2-6push vs. pull 1-7structures 2-9

deconstructing a service handle 4-7defined command values 2-8disabling

routing 3-4discovery 1-12, 1-16

by announcement 1-18by announcement, example 1-18by request 1-20by request, example 1-20happening on its own 1-18how it works 1-17messages defined 2-11

when to use 1-17distributed processing 1-8, 1-10

example 1-10distributed tasks 1-8

E

Ember Breakout Board 2-7emberDebugConfig 8-10emberSendDebugRawData 8-32emberSendDebugString 8-33enabling, routing 3-4end frame byte 2-6error messages 2-9, 6-5ESP

API comparison matrix 8-2callbacks 6-4commands 8-3defined 2-4formatting packets 2-4handlers 6-4model 2-5

F

flagsannouncement 2-11data 2-11request 2-11

G

gettingnetwork ID 3-2service handle 4-5




Index


H

handleservice 1-12, 1-13

handler, defined 6-2high order byte first 2-6host processor

Atmel 8535 2-4, 2-7master 2-3minimum requirements 2-7notifying nodes of reset 3-5

I

ID, network 3-2incoming messages 6-6

processing 6-2

L

label string, creating 3-4latency 1-8

routing 1-22

M

master/slave configuration 2-3mesh

concepts 1-2mindset 1-2

message field, packet 2-6messages

discovery defined 2-11flags 2-11type flags 2-11

messages, error 2-9, 6-5messaging

broadcast 1-3, 5-1configuring 5-2example 1-4to a service 1-5

functions 1-2radius

maximum 5-4route cost 5-4unicast 1-5, 5-1

configuring 5-3example 1-6

N

networkID 3-2

getting 3-2setting 3-2

reliability 1-8node

radio channelchanging 3-8default 3-8

radio power levelchanging 3-9default 3-9

resetting 3-6, 8-7slave 2-3subscribing to a service 4-2unsubscribing from a service 4-2

O

overlaid networksusing adjacent channels 3-8


i d e n t i a l

Index

1-4

P

packetbytes 2-6command 2-6creating with ESP 2-4data length 2-6end frame 2-6fields 2-6format 2-6high order byte first 2-6maximum length 2-6message 2-6start frame 2-6

processingincoming messages 6-2incoming messages with API 6-6

pull 1-7push data 1-7push vs. pull 1-7

R

radiochannel

changing 3-8default 3-8in overlaid networks 3-8setting 8-36

power levels 3-9, 8-37changing 3-9default 3-9, 8-37setting 8-37

radius 5-2reference

API 8-5releasing a service handle 4-6reliability

of network 1-8

request 1-15discovery by 1-20

example 1-20resetting

default values 3-6host processor 3-5node 3-6, 8-7node acknowledgement 3-6

return values 6-5route cost, determining 5-4routing 1-21

benefits 1-22disabling 3-4enabling 3-4example 1-24, 1-25flexible 1-22how it works 1-23in changing topologies 1-27latency 1-22minimizes traffic 1-26network stability 1-22on-demand 1-22

RTOS 2-7

S

sendingbroadcast message 5-2, 8-8unicast message 5-3, 8-41

service 1-12, 1-13broadcasting to a 1-5description 1-12

comparing 4-4, 8-40copying 4-4, 8-39pointer to 1-12

flag types 4-2handle 1-12, 1-13

announcements 4-5deconstructing 4-7generating 4-5




Index


getting 4-5releasing 4-6

pointer 1-12providers 1-16referring to 1-12routing regardless of 1-14subscribing to 1-15, 4-2unsubscribing 4-2users 1-16

settinglabel string 3-4network ID 3-2radio channel 8-36radio power level 8-37

signal names, SPI interface 2-2, 2-4source code 2-4, 2-7spatial multiplexing 1-11

example 1-11SPI interface 2-2, 2-4

signal names 2-2, 2-4signals 2-3

start frame byte 2-6subscribing to a service 1-15, 4-2, 8-38

T

traditional network example 1-9transmitter, radio 3-9types, messages 2-11

U

unicast messaging 1-5, 5-1configuring 5-3example 1-6sending message 5-3, 8-41

unsubscribing from a service 4-2

V

valuesreturn 6-5


i d e n t i a l

Index

1-6



elopment Guide 120-0003-210

n t i a l www.ember.com

EmberNet Application Development GuideDoc #120-0003-210December, 2002

313 Congress Street, Boston, MA 02210617-951-0200www.ember.com


embernet application development guidecseweb.ucsd.edu/groups/csag/html/teaching/cse291s03... ·...

Documents