CSE 466 Lab 8: The Raven Deconstructed

This page, like the final project, is still under development. It will change frequently, so check it often as you are developing your Raven agent. This document, not including linked resources, was last changed on Wednesday, 18 March at 04:24 PM.

• Changes on 16 Mar 2009:
  • Added pad byte to packet headers so that the 2-byte values in the payload are aligned on word boundaries if the beginning of the TOS_Msg struct is aligned.
  • Fixed state machine logic (indentation) for echoing phrase packets.
  • Added reply_to field to phrase_message
  • Added global parameter for radio channel
  • Made RSSI a signed value
• Changes on 12 Mar 2009:
  • Added echo_probability variable and extra logic to WAIT_STATE so that nodes will sometimes echo what another node is saying, to boost volume in the Atrium.
• Changes on 11 Mar 2009:
  • changed definition of LED color parameter to fit in an int16_t
  • removed unused probability parameter
• Changes on 10 Mar 2009:
  • clarified delay procedure
• Changes on 9 Mar 2009:
  • Added timeout to WAIT_STATE to make slam self-starting and to ensure that it will be re-started if it dies out
  • Added rules for choosing whether or not to play a phrase and which phrase to play

Objectives

In this lab, you will:

• Implement poetry agents
• Explore emergent behavior
• Develop an agent that can be used in the final demo

Suggested Reading and Resources

• Performing tasks at startup on the iMote2
• Raven-filelst.xls
• RavenSounds poem phrases
• RavenCalls sound effects
• The Raven.doc
• TOS_MAC driver source

Background

The Raven Deconstructed is based on the concept of cellular automata and on the collective behavior of decentralized, self-organized systems. An example of this is the famous BOIDS, which is a visual simulation of a flying flock of birds, where each bird follows simple rules independently.

The variant of using separate physical agents derives from the field of swarm robotics.

Description

We will appropriate the term "poetry slam," or "slam," to refer to our collective behavior in this project.

A Slam is a cloud of sound events of related phrases of a poem, in this case "The Raven" by Edgar Allen Poe, as read by James Earl Jones. The choices and the phrases derive from the execution of a set of common rules, without the intervention of any central control. Therefore, the resultant effect falls under the category of Emergent Behavior.

Slam sound-file phrases consist of several types:

• poem phrases: 32 phrases from the poem, classed as complete thought (t), subject cluster (s), or verb cluster (v)
• raven sounds: three distinct raven vocal sounds
• storm sounds: thunder and rain sounds, two files

Each set of partners will implement their own version of a “Cooperative compositional agent” using the specifications listed in this document. Your compiled code will run on both you and your partner’s “agents” for the Slams demonstration on the final exam day, 10:30 AM, on Thursday, March 19th in the atrium. Remember you need to qualify your “agent” before it can participate in the Slams demonstration. If for some reason you are unable to qualify your “agent”, an alternative “agent” program will be provided so that you may receive your participation points for the demonstration.

There will also be a dress rehearsal and testing session in the Atrium on Tuesday, March 17 from 6:30 to 10:00 PM.

State Machine

Idle State

This is the state in which your agent should start. In IDLE_STATE, your agent should be listening for control packets from the controller and the user interface should be active, but the agent is not actively participating in the slam.

• ON ENTER:
  • set LED to red
• ALWAYS:
  • evaluate command packets that arrive from the controller
  • if start button is pushed, or if a listen packet is received, go to WAIT_STATE

Wait State

• ON ENTER:
  • set LED to yellow
  • choose a timeout on the order of 30-60 seconds in the future
• ALWAYS:
  • evaluate command packets that arrive from the controller
  • if startled_message packet is received:
    • decrement TTL and resend startled_message if TTL is greater than zero
    • set LED to purple
    • set play_phrase to ID of sound file
    • go to PLAY_STATE
  • if phrase_message packet is received:
    • add entry to the circular receive queue
    • evaluate rules for whether to play a sound
    • if the result of the rules is PLAY:
      • execute delay
      • if carrier clear:
        • transmit phrase_message packet
        • set LED to green
        • set play_phrase to ID of sound file
        • go to PLAY_STATE
      • else:
        • go to WAIT_STATE
    • else if the phrase_num field in the message matches a trigger phrase:
      • set LED color to blue
      • execute delay
      • set play_phrase to ID of sound file
      • go to PLAY_STATE
    • else if rand() % echo_probability == 0:
      • set LED color to cyan
      • set play_phrase to the ID of the sound file you received in the phrase_message
      • go to PLAY_STATE
  • if the timeout chosen when entering the state has expired:
    • choose a random phrase from a random list
    • transmit phrase_message packet
    • set play_phrase to ID of sound file
    • set LED to green
    • go to PLAY_STATE

Play State

• ALWAYS:
  • listen for incoming packets
  • evaluate command packets that arrive from the controller
  • add received phrase_message packets to the receive queue
  • play play_phrase
  • if there are no more samples left to play:
    • go to WAIT_STATE

Delays

During several states, your agent must delay. You should choose the amount of time to delay by evaluating the following expression:

	phrase_len - trigvar >> 1 + rand() % trigvar

where phrase_len is the length of the audio file that the new sound is in response to, in milliseconds, trigvar is a global parameter, and rand() is the C function for generating a random integer.

While you are delaying, you should continue to receive and process packets:

• if a command packet is received from the controller, you should execute the command, including any state changes that may result.
• if a startle_message packet is received, decrement its TTL and rebroadcast if still greater than 0; then play the startle sound
• if a phrase_message packet is received, add it to the receive queue.

You can implement delays with the usleep() call. The delay times do not need to be exact (in fact, some randomness is desirable.) However, don't call usleep() for the entire duration you want to delay; instead, sleep for some small timeslice, perform the tasks that you need to do while delaying, sleep some more, etc. until the entire delay has elapsed.

Rules for Choosing to Play a Phrase

When choosing whether or not to respond to a phrase_message packet by playing another phrase, the following rules should be evaluated.

• should_play = (rand() % silence + RSSIfactor) == 0
• if should_play:
  • choose a random phrase from the appropriate list
  • result of evaluating the rules is PLAY; continue evaluating actions defined by state machine
• else:
  • result of evaluating rules is DON'T PLAY; continue evaluating actions defined by state machine

RSSIfactor is a boolean function of the RSSI of the node that triggered this evaluation of the rules. An RSSI value of a closer node should result in an RSSIfactor of zero, allowing sound to be played. A far away node should result in a non-zero RSSIfactor, meaning that packets from nodes that are too far away are essentially ignored. The exact details of the implementation of this function are up to you.

Phrases are categorized as complete thoughts, subject clusters (nouns), and verb clusters. The choice of which list you will play a phrase from is dependent on the type of the phrase that triggered this evaluation of the rules. The rules for this decision are as follows:

• thought -> another thought, or a subject
• subject -> verb
• verb -> a thought, or a subject

User Interface

You should develop a user interface for your agent using the LED and LCD for output and the SuperBird's switches for input. Your interface should allow for the following:

• Manual start and stop: This should allow your agent to be started manually from the interface. This can also be done with a global command packet from the controller.
• Display of slam parameters: Parameters such as the current phrase number, transmit signal strength, average received signal strength, and other relevant information should be displayed on the SuperBird's LCD.
• Display of the current state: The RGB LED on the SuperBird should indicate the current state with its color. The colors for the different states are defined with the state definitions themselves.

Try to make your interface efficient. Remember that it will become a part of your agent program, so it should use resources effectively (e.g. don't update the display every time through a tight infinite loop.)

Using the LCD

The LCD driver allows you to put graphics and text on the SuperBird's LCD. It allows you to update a rectangle on the LCD with raw pixel data, with or without an alpha channel, and also to draw text on the display with a few simple bitmap fonts. The driver is available through subversion/trac here. Note that you can download a zip archive of the entire driver at the bottom of the trac page.

Refer to the documentation.txt file in the driver source for information on how to use it. test.c also provides several examples of how to use the driver (make test should build it.)

Using the switches

A new version of the SuperBird driver that implements ioctls for reading the switches, among other things, is available here or as a package here. Documentation and a description of what all of the status bits mean is included in the superbird.h header file, which you should include in your program.

The status of the switches is also available through sysfs in /sys/bus/i2c/devices/0-004d/switches.  This is how the sbstatus application you used to test the SuperBird reads the switches.

Network Protocol

All packets should have the following format:

src and dest are the node numbers of the transmitter and receiver, respectively. This addressing scheme is independent of the TinyOS MAC layer, which you should always set to broadcast packets (0xFFFF) as you have done with previous labs. pad is an empty/ignored byte to eliminate alignment issues with the packets. The content and length of payload, if present, is defined by the packet type.

To make your code more readable and allow for easy changes to the packet structure, you should define all of your packet types as C structs in one of your header files. By casting a pointer to the data field of a TOS_Msg to your own type that defines the packet structure, you can access the packet fields by name. If we need to change the structure of a packet, you will then be able to do so by just editing the header file instead of fixing a bunch of manual indices.

Addressing

You will be assigned a node number that will be your slam agent's address. This address should appear in the src field of all packets you transmit, and your agent should ignore packets that are not addressed to it or to the broadcast address.

There are two special node addresses:

• 0x00 is the address of the master controller. Certain control commands should only be accepted from this address.
• 0xFF is the broadcast address. All nodes should process packets addressed to the broadcast address.

Packet Types

This section defines the packet types that your agent must understand.

Set Global Parameter

This packet is a request from the controller for the agent to change one of its global parameters. It should only be accepted from the controller's address.

• Header
  • uint8_t type is 0x50.
  • uint8_t src should always be the controller address, 0x00.
  • uint8_t dest is the address of your node, or broadcast.
• Payload
  • uint8_t id is the parameter ID to change.
  • int16_t value is the new value for the parameter.

Listen

This packet from the controller tells the agent to stop any current sound and go to WAIT_STATE. If the agent is currently in IDLE_STATE and it receives a listen packet, it should go to WAIT_STATE.

• Header
  • uint8_t type is 0x51.
  • uint8_t src should always be the controller address, 0x00.
  • uint8_t dest is the address of your node, or broadcast.
• listen packets have no payload.

Do Sound

This packet from the controller tells the agent to stop what it is doing, go to PLAY_STATE and to play the sound file indicated in the payload.

• Header
  • uint8_t type is 0x52.
  • uint8_t src should always be the controller address, 0x00.
  • uint8_t dest is the address of your node, or broadcast.
• Payload
  • uint8_t sound_num is the phrase number of the sound that should be played.
  • uint8_t send_start is a boolean value that indicates whether or not this agent should send a phrase_message packet when beginning to play the sound. If dest is not broadcast, and send_start is nonzero, then a phrase_message packet should be sent. Otherwise, this node should play the sound without sending anything.

Stop

This packet from the controller tells the agent to stop any current sound and go to IDLE_STATE.

• Header
  • uint8_t type is 0x53.
  • uint8_t src should always be the controller address, 0x00.
  • uint8_t dest is the address of your node, or broadcast.
• stop packets have no payload.

Phrase Message

The phrase_message packet is the main packet type sent out by your agent. It contains information about what your agent is doing, such as the currently playing phrase.

• Header
  • uint8_t type is 0x42.
  • uint8_t src is the address of the node that sent this message.
  • uint8_t dest is broadcast.
• Payload
  • uint8_t seq_num starts at 0, and is incremented each time you send a phrase_message packet. When it reaches 255, it rolls over to 0.
  • uint8_t phrase_num is the phrase number of the sound your agent is about to play.
  • uint8_t top_num is the node ID of the agent with the highest RSSI value currently in the receive queue.
  • uint8_t top_strength is the RSSI value of the agent with the highest RSSI value currently in the receive queue.
  • int8_t txpower is the current transmit power of this agent.
  • uint8_t reply_to is 0 if this node decided to make sound on its own, else the node ID of the agent to whose phrase_message packet we're responding

Startled Message

This packet is triggered by the accelerometer, and indicates that the receiving agent should stop what it is doing and resend the startled_message packet after decrementing TTL.

• Header
  • uint8_t type is 0x54.
  • uint8_t src is the address of the node that sent this message.
  • uint8_t dest is broadcast.
• Payload
  • uint8_t startled_num is the node ID of the agent that was startled. This may be different than src, since the message may have been retransmitted. (Make sure to change src to your own node ID when retransmitting.)
  • uint8_t TTL is the "Time to Live" or the number of hops remaining. If the value is zero, you should ignore the message. Otherwise, decrement TTL and re-broadcast the message.
  • uint16_t seq_num is a randomly generated number for this startle event. You should maintain a list of the startle sequence numbers you receive to check whether you have been startled by this packet before. If you have already been startled by this packet, you should ignore it.

The Receive Queue

As you receive phrase_message packets, you should store them in an 8-entry circular FIFO queue. The entries in this queue will be used to decide what to do next.

Entries in the queue should contain the following information:

• uint8_t src — the node ID that sent this message
• uint8_t phrase_num — the phrase ID that the node is playing
• int8_t strength — the RSSI value of the packet as it was received
• uint8_t txpower — the transmit power that the sending node indicated that it was using

Each new entry should overwrite the oldest entry in the queue. Make sure you initialize the data structure to a reasonable state when it starts out empty at the beginning of your program.

Global Parameters

Your agent should have a set of global parameters that govern its behavior. These parameters should have consistent IDs across everyone's implementations and should be controllable with a set_global_parameter packet from the controller.

Note that the list of parameters and their default values will likely change as the project progresses. Expect new parameters to be added and the default values to change.

Part 1: Build your state machine

Build your state machine as shown above. To begin, use a button push to move from state to state, showing the LED color change for each state. Use one button for trigger sound, another button for playing a phrase. Use the accelerometer to cause the startle sound.

Add code to handle and create the packet types defined in the specification document.

Part 3: Add Everything Else...

Finish it!

Notes on the TOS MAC driver...

The source is here: TOS_MAC driver source

In SG2_CC2420.h is the following:

#define TEST_CCA_PIN()   (GPLR(SG2_GPIO116_CC_CCA) & GPIO_bit(SG2_GPIO116_CC_CCA))

This is used in CC2420.c in void CC2420_try_to_send()

Let's adapt this for our purposes to determine if it's safe to transmit.