From ContikiWiki

NOTE: this information is to be deprecated after Contiki 2.5. Read more about the upcoming version in this paper.

[edit] Source code location

/core/net/rime/announcement.c
/core/net/rime/announcement.h

[edit] The announcement concept

[The following is an extract from an email from Adam Dunkels to the developer mailing list]

First a bit of background to the announcements concept: The announcement abstraction is used for disseminating small amounts of data (16+16 bits) to neighbors. Announcements reach only those that listen for them and therefore are not as expensive as repeated broadcasts. Broadcasts are typically quite expensive with a power-saving MAC protocol because broadcasts have to wake up everybody from sleep mode - even those that already know the information, or who are not interested anyway. Waking up everybody both requires every neighboring node to spend energy in listening for radio packets, and also requires bandwidth because all nodes have to be woken up.

The announcement module is a central location for announcements for all applications and protocols on the node. Because all announcements are registered with the announcement module, applications play nicer together than if they'd each independently open a broadcast channel to announce their data.

Because announcements do not go to every neighbor, the information can be transmitted more efficiently than if every application would need to use explicit broadcasts to disseminate the information. Power-saving MAC layers that use beacons, such as LPP, are particularly suited to transport announcements because announcements are piggy-backed on the beacons and no additional packets need to be sent.

For mobile nodes, announcements allow a mobile node to quickly get up to speed in terms of neighbors, routes, and other network information: all a new node need to do to get information about the network is to listen for announcements. This means that only the new node has to pay a (small) price to get the information, by switching on its radio to listen for announcements. The alternative would have been for the new node to send a broadcast asking for information from all nodes. Thus the new node would not only need to wake everybody up (thus causing all nodes to spend energy), the broadcasts would also interfere with the normal operations of the network which could be very problematic if there are many new or mobile nodes and each would send a broadcast.

The announcement abstraction conceptually consists of three parts:

• The announcement front-end: this is where applications register announcements with announcement_register(), and what calls the application when an announcement from a neighbor is heard.
• The announcement back-end: this is what actually transmits and receives the announcement packets. There are currently three announcement back-ends implemented: polite-announcement.c (that uses periodic broadcasts to send out announcements), xmac.c (that sends out announcements at the MAC layer), and lpp.c (also sends out announcements at the MAC layer, as part of the LPP beacons). The polite-announcement.c back-end is to be used when no MAC-layer back-end is in place (say, when using nullmac). Different back-ends typically have different timer policies (e.g. MAC-layer back-ends can send announcements more often because they do not have to rely on a costly broadcast to send their announcements).
• Listen triggers: this calls announcement_listen() whenever there is reason to listen for incoming announcements. There can be several listen triggers that trigger a listen for different reasons. For example, in a network with mobile nodes, the mobile nodes will want to listen for announcements (e.g. ETX beacons) when they have moved to a new location to quickly get routes, a neighbor list, and other network information. A listen trigger than would use acceleration sensors to find out that the node has moved and call announcement_listen() (see e.g. examples/jcreate/announce-blink.c for an example of this). Applications and protocols can also themselves trigger listening. For example, the collect.c protocol will trigger listening when it wants to send a packet but has no route.

Because there may be multiple listen triggers, an application must be ready to receive announcements at any time, even if it has not called announcement_listen() itself.

[edit] Selecting the announcement back-end

For the sky platform, the announcement back-end can be selected by appropriately setting the macros XMAC_CONF_ANNOUNCEMENTS and RIME_CONF_NO_POLITE_ANNOUCEMENTS in the file platform/sky/contiki-conf.h.