Chapter9 Softwaredocumentationbibing.us.es/proyectos/abreproy/11364/fichero... · Chapter9...

Chapter 9

Software documentation

9.1 IntroductionCode developed in this project complies with NesC source documentationguidelines [8]. This chapter contains the source documentation in NesDocstyle. There are also additional comments for some functions that are onlyin the source code. These comments refer to speci�c implementation detailsand are meaningless without the source code. That is the reason why theyhave not been included here.

Documentation is divided in two sections: Interfaces and Components.In the source code, every interface and component (a component might bea module or a con�guration) is implemented in a separate �le. The nameof each �le is the name of the interface/component implemented with .ncextension.

In the case of commands and events that are part of interfaces, documen-tation about parameters and return value is detailed in the interface docu-mentation, either in this document or in TinyOS documentation1 in case theinterface is part of TinyOS.

9.2 InterfacesInterface AppMWInterface between MW and application .

1Available at http://www.tinyos.net/

44

CHAPTER 9. SOFTWARE DOCUMENTATION 45

Commands

result_t attributesRegistered();Attributes registered event. This event is signaled when the applicationhas �nished registering attributes. This command lets the MW knowwhen it's time to start the attributes (they should no be started untilthey have been registered).

Interface ChannelMngChannel management interface. This interface provides the communicationmethod to pass the ChannelMngC component the pointer to the group dataand to update �elds in the group table (only GroupMng should write on thattable).

Commands

result_t groupAndAttrInfo(GroupMembership_t *groupsPtr,uint16_t*attrDataPtr);Pass pointer to the group list to channel manager. Channel manage-ment component should access pointer data in read-only.

Parameter groupsPtr pointer to the array with the group membershipinformation.

Parameter attrDataPtr pointer to the array with the values of theattributes.

Returns whether the information was successfully stored.

Events

result_t receivedDataFromMembers(uint8_t weight, uint8_t group-Type, uint16_t sender);New data received from group members. This event is signaled every-time the leader receives new data from the members, so that weight andnextLeader �elds in the group table can be updated by group manager.

Parameter weight number of measurements received, to add a weightdepending on this value.

Parameter groupType group ID to which the channel we received thedata through is associated.


Parameter sender ID of the node from which the data was received.This information is used by GroupMng to determine possible suc-cessor in group leadership.

Returns SUCCESS.

Interface NewDripNewDrip interface. This interface allows PacketInjector notify other compo-nents about new Drip packets injected from the PC .

Commands

void* notify(uint8_t dripAM,void* msg);Notify new drip message. This command tells the provider of the inter-face about a new Drip command. The dripAM �eld corresponds withthe AM type of the Drip instance associated with the info.

Parameter dripAM AM type of the Drip instance associated with theinfo.

Parameter msg pointer to the message.Returns must return same bu�er received to be used in the next no-

ti�cation.

9.3 ComponentsCon�guration AppWiring for the application module.

This con�guration provides the wiring for the Application. The appli-cation component is seen as an abstract and autonomous component fromoutside this con�guration. Communication with other components and withthe operating system is carried out through interfaces.

Wiring provided by this component is shown in �gure 9.1.

Module AppMThe application registers two attributes: TSR and PAR readings.


Figure 9.1: Wiring provided by App component

Commands

result_t StdControl.init()init command. Call StdControl.init() on all used components that pro-vide StdControl interface.For parameters and return information see the corresponding interfacedocumentation.

result_t StdControl.start()start command. Call StdControl.start() on all used components thatprovide StdControl interface.For parameters and return information see the corresponding interfacedocumentation.

result_t StdControl.stop()stop command. Call StdControl.stop() on all used components thatprovide StdControl interface.For parameters and return information see the corresponding interfacedocumentation.

Events

result_t AttrRegTSR.startAttr()Function to start the TSR attribute. The sensor should be alreadystarted, because its StdControl interface is wired to Main


For parameters and return information see the corresponding interfacedocumentation.

result_t AttrRegTSR.getAttr(char *name, char *resultBuf, SchemaEr-rorNo *errorNo)Function called when an update of the attribute is requested. Attributevalue is saved in the provided bu�er. If the attribute cannot be updatedand error code is returned by the errorNo pointer.For parameters and return information see the corresponding interfacedocumentation.

result_t AttrRegTSR.setAttr(char *name, char *attrVal)Setting this attribute makes no sense because it comes directly from asensor, so we return error.For parameters and return information see the corresponding interfacedocumentation.

async result_t TSR.dataReady(uint16_t data)Event signaled when the TSR ADC �nishes its conversion. The value isreturned in the same bu�er that was provided by the module requestedthe attribute update, so that module should not access to that bu�eruntil this function returns.For parameters and return information see the corresponding interfacedocumentation.

result_t AttrRegPAR.startAttr()Function to start the PAR attribute. The sensor should be alreadystarted, because its StdControl interface is wired to MainFor parameters and return information see the corresponding interfacedocumentation.

result_t AttrRegPAR.getAttr(char *name, char *resultBuf, SchemaEr-rorNo *errorNo)Function called when an update of the attribute is requested. Attributevalue is saved in the provided bu�er. If the attribute cannot be updatedand error code is returned by the errorNo pointer.For parameters and return information see the corresponding interfacedocumentation.


result_t AttrRegPAR.setAttr(char *name, char *attrVal)Setting this attribute makes no sense because it comes directly from asensorFor parameters and return information see the corresponding interfacedocumentation.

async result_t PAR.dataReady(uint16_t data)Event signaled when the TSR ADC �nishes its conversion. The value isreturned in the same bu�er that was provided by the module requestedthe attribute update, so that module should not access to that bu�eruntil this function returns.For parameters and return information see the corresponding interfacedocumentation.

Tasks

void getTSRDoneTask()Task for getAttrDone. This task avoids calling getAttrDone from asyn-chronous code.

void getPARDoneTask()Task for getAttrDone. This task avoids calling getAttrDone from asyn-chronous code.

Module AttrMngModule for managing attributes. This module manages attributes form thepoint of view of the middleware, checking for registered attributes and start-ing them. It also sets up the Tx power .

Commands

result_t StdControl.init()init command. Call StdControl.init() on all used components that pro-vide StdControl interface.For parameters and return information see the corresponding interfacedocumentation.


result_t StdControl.start()start command. Call StdControl.start() on all used components thatprovide StdControl interface. We also set Tx power.For parameters and return information see the corresponding interfacedocumentation.


result_t AppMW.attributesRegistered()Attributes registered event. This event is signaled when the applicationhas �nished registering attributes. It's time to start them.

Eventsresult_t WatchDogTimer.�red()

WatchDog reset.

result_t AttrUse.startAttrDone(uint8_t id)Event for attribute started. Once the attribute has been started, thisevent is triggered.

result_t AttrUse.getAttrDone(char *name, char *resultBuf, SchemaEr-rorNo errorNo)Event for attribute value updated. This function is triggered every timethe value of the attribute is updated. In this module, attributes arestarted to be read by other modules, so no need to do anything here.

Tasksvoid checkRegAttr()

Task for checking registered attributes. Two attributes are considered.

Module ChannelMngCChannel management module. This module checks the channels that areestablished in the system and sends the info to the leader if the node belongsto a group that has associated channels.


Commands

result_t StdControl.init()init command. Call to Drip.init() (necessary since ChannelMngC iswired to a Drip instance). Call StdControl.init() on all used compo-nents that provide StdControl interface.For parameters and return information see the corresponding interfacedocumentation.



result_t ChannelMng.groupAndAttrInfo(GroupMembership_t *group-sPtr,uint16_t *attrDataPtr)Noti�cation of group list and attribute data When this command isinvoked the value of groups is updated. Once we have the pointer tothe group list the module can start doing its job. The value of attrDatais also updated and the attribute data is available through this pointer.(Attribute values are obtained in component GroupMng).For parameters and return information see the corresponding interfacedocumentation.

void* NewDrip.notify(uint8_t dripAM,void* msg)The next command is called when a new Channel Drip packet is re-ceived through the serial interface. This only happens in node 0, whichis attached to a PC.For parameters and return information see the corresponding interfacedocumentation.


Eventsresult_t CheckChannelTimer.�red()

Timer for checking channels. In this event, we check whether it isnecessary to feed any of the existing channels.For parameters and return information see the corresponding interfacedocumentation.

result_t ChannelTimer.�red[uint8_t i]()Publish data on channels. This event is signaled every time new data isto be published on a channel. The value of the attributes are updatedand scheduled to be sent to the leader.For parameters and return information see the corresponding interfacedocumentation.

void DataMsgReceive.receive[uint8_t channelId](sp_message_t *spmsg,TOS_MsgPtr m, sp_error_t result)Reception of DataMsg. We aggregate the receive measurement to thedata received from other members.For parameters and return information see the corresponding interfacedocumentation.

void DataMsgSend.sendDone[uint8_t channelId](sp_message_t *msg,sp_message_�ags_t �ags, sp_error_t error)This event is signaled when the transmission has �nishedFor parameters and return information see the corresponding interfacedocumentation.

result_t MultiHopSend.sendDone[uint8_t channelId](TOS_MsgPtrmsg, result_t success)This event is signaled when the multi-hop packet has been sentFor parameters and return information see the corresponding interfacedocumentation.

TOS_MsgPtr ReceiveDrip.receive(TOS_MsgPtr message, void*payload, uint16_t payloadLen)The next event is signaled when new information about establishedchannels is receivedFor parameters and return information see the corresponding interfacedocumentation.


result_t Drip.rebroadcastRequest(TOS_MsgPtr msg, void *pData)Event for rebroadcasting Drip packetFor parameters and return information see the corresponding interfacedocumentation.

Tasks

void sendData()This function sends the data associated to the channel. It pops the�rst element from the send queue and send the data associated withthat channel ID.

void processDripPacket()Task for processing new Drip packet. This task process a newly receivedDrip packet.

Functions

result_t sendQueuePush(uint8_t channel)Insert new channel into send queue.

Parameter channel channel ID to put in the queue.Returns whether the channel was successfully enqueued.

result_t sendQueuePop(uint8_t *channel)Get next channel to send from send queue.

Parameter channel pointer to store the retrieved channel ID.Returns whether the operation was completed successfully. If FAIL

is returned, the value of channel is not valid.

bool checkGroup(uint8_t groupType,uint16_t groupId,uint8_t chan-nelId)Function for checking group type and Id. This function checks whetherthe node belongs to a certain group type and groupId. The functionalso updates the value of the group to which the 'channelId' chan-nel is associated. The function understands special values such asGROUP_TYPE_ALL and GROUP_ID_ALL .

Parameter groupType group type to check.


Parameter groupId group ID to check.Parameter channelID channel ID that is associated with this group

type and group id. This value determines for which channel thegroupType �eld is updated.

Returns whether the mote belongs to a group of that type and ID.(Note that GROUP_TYPE_ALL and GROUP_ID_ALL are con-sidered as special values).

Module CommandMngThe middleware waits for a command from the radio and when it arrives,performs a certain action. The middleware waits for a group message and, ifthere are group types created it monitors the attribute to become a memberif the condition is satis�ed. While the node is a member, it turns on thegreen led.

Commands

result_t StdControl.init()init command. Call to Drip.init()For parameters and return information see the corresponding interfacedocumentation.

result_t StdControl.start()start command. Nothing to do hereFor parameters and return information see the corresponding interfacedocumentation.

result_t StdControl.stop()stop command. Nothing to do hereFor parameters and return information see the corresponding interfacedocumentation.

void* NewDrip.notify(uint8_t dripAM,void* msg)The next command is called when a new Channel Drip packet is re-ceived through the serial interface. This only happens in node 0, whichis attached to a PC.For parameters and return information see the corresponding interfacedocumentation.


Events

TOS_MsgPtr ReceiveDrip.receive(TOS_MsgPtr msg, void* pay-load, uint16_t payloadLen)Event for command received through Drip. This event is signaled when-ever a new command packet is received through DripFor parameters and return information see the corresponding interfacedocumentation.

result_t Drip.rebroadcastRequest(TOS_MsgPtr msg, void *pData)Event for rebroadcasting Drip packetFor parameters and return information see the corresponding interfacedocumentation.

Tasks

void processCommand()This task processes the command received through Drip.

Functions

result_t display(uint16_t value)The next function displays the received value on the leds.

Module GroupMngThis is the component for group management. In this early version it justperforms a leader election. The attributes used here should have been ini-tialized by the AttrMng module.

Commands

result_t StdControl.init()init command. Call to Drip.init() (necessary since GroupMng is wiredto Drip instances). Call StdControl.init() on all used components thatprovide StdControl interface.For parameters and return information see the corresponding interfacedocumentation.


result_t StdControl.start()start command. Call StdControl.start() on all used components thatprovide StdControl interface. We also start the timer for the leaderbeacon.For parameters and return information see the corresponding interfacedocumentation.


void* NewDrip.notify(uint8_t dripAM,void* msg)The next command is called when a new Group Drip packet is receivedthrough the serial interface. This only happens in node 0, which isattached to a PC.For parameters and return information see the corresponding interfacedocumentation.

EventsTOS_MsgPtr ReceiveDrip.receive[uint8_t i](TOS_MsgPtr mes-

sage, void* payload, uint16_t payloadLen)The next event is signaled when new information about establishedgroups types is receivedFor parameters and return information see the corresponding interfacedocumentation.

result_t Drip.rebroadcastRequest[uint8_t i](TOS_MsgPtr msg, void*pData)Event for rebroadcasting Drip packetFor parameters and return information see the corresponding interfacedocumentation.

result_t GroupRefreshTimer.�red()When this event is signaled, the values of the attributes are collected.Attribute values are requested sequentially, to prevent the ADC fromrejecting request because of being busy.



result_t AttrUse.getAttrDone(char *name, char *resultBuf,SchemaErrorNoerrorNo)The next event is signaled when the data acquisition �nishes.For parameters and return information see the corresponding interfacedocumentation.

result_t AttrUse.startAttrDone(uint8_t id)Attribute initialized. Now we can start checking for membership to agroup.For parameters and return information see the corresponding interfacedocumentation.

void LeaderBeaconReceive.receive(sp_message_t *spmsg, TOS_MsgPtrmsg, sp_error_t result)The next event is signaled every time a leader beacon is receivedFor parameters and return information see the corresponding interfacedocumentation.

result_t LeaderBeaconTimer.�red()When this event is signaled, next leader beacon is sent. Leader beaconsare sent in a sequence, with a frequency that is incremented when thenode becomes leader of more groups, so that the frequency of a singlebeacon remains the same.For parameters and return information see the corresponding interfacedocumentation.

void LeaderBeaconSend.sendDone(sp_message_t *msg, sp_message_�ags_t�ags, sp_error_t error)This event is signaled when the transmission has �nishedFor parameters and return information see the corresponding interfacedocumentation.

result_t ChannelMng.receivedDataFromMembers(uint8_t weight,uint8_t groupNo, uint16_t sender)New data received from group members. When this event is signaledwe must increase the weight in the corresponding group.



Tasks

void updateMembership()This task updates the membership type for every group to which thenode belongs. It's executed after checkMembership(), so it can use theinformation generated by that task that is stored in state variables.

void checkMembership()This task checks whether there are any group types created and checksmembership to every group type.

void sendBeacon()This task sends the beacon for the group type determined by bea-conIndex. We use a task and reduce the RC problems, since task donot preempt other tasks.

Con�guration MWWiring for the middleware module.

This con�guration provides the wiring for the MW. Viewed from outsidethis con�guration, the MW is an abstract and autonomous component, withinterfaces to interact with the Application and the Operating System.

Wiring for this component is shown in �gure 9.2.

Module NoSensorThis module provides interface StdControl and ADC but the value returnedin the ADC interface is always zero. This module is used to provide an ADCinterface implementation for Delta without interferring with the ADC.

Commands

async result_t ADC.getContinuousData()The next command should set a continuous sampling, but this imple-mentation returns only one sampling, similar to a hardware device thathad a very long sampling period.


Figure 9.2: Wiring provided by MW component


Module PacketInjectorThis component receives Drip packets from the UART and noti�es about itto the module that handles that Drip packet.

Commandsresult_t StdControl.init()

init command. Call StdControl.init() on all used components that pro-vide StdControl interface.For parameters and return information see the corresponding interfacedocumentation.


result_t StdControl.stop() ;stop command. Call StdControl.stop() on all used components thatprovide StdControl interface.For parameters and return information see the corresponding interfacedocumentation.

Eventsvoid SPReceive.receive(sp_message_t* spmsg, TOS_MsgPtr tosmsg,

sp_error_t result)Event for received message. We must check that it came through theUART and that it is a Drip message, then cache it and post task forprocessing.For parameters and return information see the corresponding interfacedocumentation.

Tasksvoid processMsg()

This task noti�es the appropriate module about the received Drip mes-sage.


Figure 9.3: Program top-level con�guration

Con�guration TestMWTop level con�guration for TestMW.

This component provides the highest wiring level for the developed soft-ware.

Wiring is shown in �gure 9.3.

Chapter9 Softwaredocumentationbibing.us.es/proyectos/abreproy/11364/fichero... · Chapter9...

Documents

Transcript of Chapter9 Softwaredocumentationbibing.us.es/proyectos/abreproy/11364/fichero... · Chapter9...