View source for Simple Embedded System Project

== Objective ==
Work together as a class to create a wireless network of interactive devices.  An example would be one controller responsible for lights, another controller responsible for motion sensor, and a central control can interact with these controllers to perform tasks such as turning on lights when motion has been detected.  

Your board contains wireless mesh network allowing you to freely connect many boards together and they can all communicate with each other.  You will exploit this capability to do something creative, and ultimately learn, and have fun.

Think outside the box; you can do much more than the examples given :
*  A commander can be programmed as an alarm clock.
*  A remote node can be connected to a motor that turns sprays water to wake up a person upon an alarm :)
*  You can create "Christmas Lights" which has a bunch of lights connected over wireless network.
*:  Each light sensor node can control an LED strip not just one LED.

[[File:cmpe_proj_wireless_nodes.png|right|frame|link=Sample Wireless Nodes]]

== Structure ==
There are minimum three nodes to be designed by a team of 6; you can add more nodes and more people in a team if you project is challenging enough.  Each team is then split into smaller sub-team for the design of each of the nodes.  Each team will also compete with the other teams in your class and your grade will be assigned relative to each other with the best team earning the best grade.

Each '''sub-team of 2''' should take ownership of what they will do.  You '''shall not''' share the code with each other; but instead just list out "how" you can communicate.  Here are a couple of examples that show how you can list your communication protocol:

{| class="wikitable"
 !colspan="2"| Lights Wireless Protocol
 |-
 | Wireless Channel
 | 2580
 |-
 | Wireless bitrate
 | 250
 |-
 | Wireless Address
 | 110
 |-
 !colspan="2"| Command List
 |-
 | Lights ON
 | Send 1 byte with value 1
 |-
 | Lights OFF
 | Send 2
 |-
 | Lights Auto
 | Send 3
|}

{| class="wikitable"
 !colspan="3"| Sensor Node Wireless Protocol
 |-
 | Wireless Channel
 | 2580
 |-
 | Wireless bitrate
 | 250
 |-
 | Wireless Address
 | 125
 |-
 !colspan="3"| Command List
 |-
 | Get Light Sensor
 | Send 1 byte with value 1
 | &nbsp;2-byte data returned as uint16_t
 |-
 | Get Temperature Sensor
 | Send 1 byte with value 2
 | &nbsp;2-byte data returned as int16_t
|}

A good suggestion to follow is that the commander node always initiates communication and other nodes only "speak when spoken to".  This can generally simplify your project.  When the light sensor receives a byte with the chosen values, you can send a packet back to the sender.  Each packet sent receives an acknowledgement back, so ask your lab instructor how you can send back the acknowledgment packet with your sensor data.  This will only require two packets (instead of four), one to request for data, and one for acknowledgment with your sensor data.

== Example Nodes ==
The nodes listed below are just examples.  You can and should create your own node with its own purpose that goes above and beyond the examples listed in this article.  Four unique features are required per node, and some hints are provided in the latter part of this document.  '''Do not worry about the "how"; let the class instructors help you.  Just think about the "what"'''.

=== Lights Node ===
This node shall act like a wireless node that is responsible to turn on and off lights.  This will involve some hardware design such that you can connect your board to some high-power LEDs.  Look-up “super bright led” at sparkfun.com for examples.

=== Sensor Node ===
This node shall act like a sense point for the commander node.  The objective is not just to provide the on-board sense points such as temperature and light, but also implement features such that you can report other creative sense points such as a motion sensor, and distance sensor.

=== Commander Node ===
This node shall be responsible to put it all together and serve as a single commanding node to get sensor input and control the lights.  This node shall provide the interface for the user, so try to provide user options to configure features such as automatic lights, or remote controlled operation.

<BR/>

== Requirements ==
=== Technical ===
*  You must use a '''<code>switch / case </code>''' code section in your code.
*  You must use a state machine in you code.
*:  This could be as simple as a state machine for "Manual Lights" vs. "Automatic Lights"
*  You must utilize functions that use pass-by-value and pass-by-reference.
*  Project should be self-contained
**  Project should be enclosed, with no wires visible.
**  Project should operate either by a battery or USB power, but NOT require a computer's USB port.
**:  Should not require the Hercules Terminal to operate
**  All buttons should be labeled.

=== Deliverables ===
At the end of the project, the following items need to be submitted :
*  Full source-code of all the projects
*  Individual evaluations about team members and their contribution
*:  This will be confidential, and you can submit as one per person (at Canvas).

==== Project Report ====
You must submit a full, documented report for your project.  The following are minimum sections required in your PDF submitted report:
*  Introduction
*:  What does your project do?
*:  Try to sell your project in this section.
*  Schematics
*:  List the hardware you used.
*:  Use "LibreOffice Draw" to draw the schematics
*  Implementation
*:  Show your software workings using a flow-chart
*:  Use bullets and pictures to show the "how" part.
*:  Discuss the nodes, and their wireless protocol (table of commands).
*  Testing
*:  What kind of tests did you perform?
*:  What kind of problems did you solve?
*  Conclusion
*:  What did you learn?
*:  What worked, and what didn't work?
*:  How would you improve your project?

<BR/>
== Challenges & Hints ==
=== Challenges ===
Over the course of the project, you will encounter some real-world problems such as :

*  How will you design your project to be user friendly?
*  How will you collaborate in your large team?
*  How will you balance your budget and keep parts cost to a minimum?
*  How will you design your network protocol such that each team understands a command and response system well?
*  How will you make your project more creative?  How will it stand out?
*  What if you command a light output node that is not responding?
*:  How will you report this to the user and what would you do?

=== Wireless ===
As of the wireless mesh network's version 1 source code, the wireless packet can be 32-bytes long, out of which 8 bytes are used by the network header and 24 bytes are free to be used.  Please take a look at the '''<code>mesh_packet_t</code>''' structure to understand the data of the wireless packet.  The only relevant fields you need to know about are :
* <code>data_len</code> : Size of the valid data bytes
* <code>data[0] - data[23]</code> : Actual data bytes.

{| class="wikitable"
 !colspan="9"| Wireless Packet Structure
 |-
 !colspan="4" | 4 Byte Header
 !colspan="2" | 2 Byte Network Address
 !colspan="2" | 2 Byte Physical Address
 | 24 Byte User Data
 |-
 | B0
 | B1
 | B2
 | B3
 | B4
 | B5
 | B6
 | B7
 | B8 - B31
 |-
 !colspan="4" | data_len
 !colspan="4" | Do not use
 | data[0] - data[23]
|}

=== Debugging Techniques ===
*  For the commander, implement a "ping" packet that is sent to everyone once a second.
*:  If an ACK is received, turn on an LED, otherwise turn it off (one LED per remote node).
*:  This will immediately help diagnose connection issues.
*  Any security ?
**  What if I get on your network and sabotage your project?
**  Can you implement a method such that a command is not so easy for anyone to send?
*  Beware of Mr. Sabotage :
** In your class, there will be an attacker, which will use "replay attack" technique to attack your project.
** Mr. Sabotage will hop from one channel to another to look for presence of the wireless data.
** If Mr. Sabotage can read a packet, it will replay it back randomly to confuse your project.

<BR/>

== Sample Code ==
'''Important Note'''
You need to open up '''sys_config.h''' and change your '''WIRELESS_CHANNEL''' to a unique frequency.  This will avoid data collisions between you and other groups.  Each of your nodes should also configure the '''WIRELESS_NODE_ADDR''' to further avoid wireless data collisions.  If you change the '''sys_config.h''' file, you should also perform '''Project'''-->'''Clean''' and rebuild your software code.


=== Light Sensor Node ===
<syntaxhighlight lang="c">
#include "wireless.h"

void process_command(char command);

int main(void)
{
    char our_addr = 100;
    mesh_set_node_addr(our_addr);

    while (1) {
        /* Check if we get a packet within 1 second : */
        mesh_packet_t pkt;
        if (wireless_get_rx_pkt(&pkt, 1000)) {
            /* Assuming first data byte is our command: */
            char cmd = pkt.data[0];
            process_command(cmd);
        }
    }
    return 0;
}

void process_command(char command)
{
    enum {
        lights_on = 1;
        lights_off = 2;
    }

    switch(command) {
        case lights_on:
            /* TODO Turn on lights */
        break;

        case lights_off:
            /* TODO Turn off lights */
        break;

        default:
            /* TODO Take action for invalid command */
        break;
    }
}
</syntaxhighlight>

<BR/>
=== Commander Node ===
<syntaxhighlight lang="c">
#include "wireless.h"

int main(void)
{
    /* Same enum as lights controller */
    enum {
        lights_on = 1;
        lights_off = 2;
    }

    const char our_addr = 200;
    const char lights_addr = 100;
    const char max_hops = 2;
    mesh_set_node_addr(our_addr);

    while (1) {
        /* Turn lights on/off every 3 seconds */
        char cmd = 0;

        cmd = lights_on;
        wireless_send(lights_addr, mesh_pkt_ack, &cmd, 1, max_hops);
        if (wireless_get_ack_pkt(&pkt, 100)) {
            printf("Lights should be ON\n");
        }
        else {
            printf("ERROR: No acknowledge from %i (lights)\n", lights_addr);
        }
        delay_ms(3000);

        cmd = lights_off;
        wireless_send(lights_addr, mesh_pkt_ack, &cmd, 1, max_hops);
        printf( "%s\n", wireless_get_ack_pkt(&pkt, 100) ? "Lights OFF" : "Error");
        delay_ms(3000);
    }
    return 0;
}
</syntaxhighlight>

<BR/>
=== Ping! ===
<syntaxhighlight lang="c">
#include "io.hpp"
#include "wireless.h"
#include "soft_timer.h"


int main(void)
{
    const char max_hops = 2;
    mesh_packet_t pkt;

    enum {
        our_addr = 100,
        lights_addr = 200,
        sensor_addr = 210,
    };

    // Use a software timer "object" with 3000ms duration.
    SoftTimer ping_timer;
    ping_timer.reset(3000);

    while (1) {
        // If timer expires, restart it again and ping everyone.
        if (ping_timer.expired()) {
            ping_timer.restart();

            // Send NULL data to the lights node :
            wireless_send(lights_addr, mesh_pkt_ack, "\0", 1, max_hops);

            // Turn LED #1 on or off based on if we get ACK packet within 100ms
            if (wireless_get_ack_pkt(&pkt, 100)) {
                LE.on(1);
            }
            else {
                LE.off(1);
            }
        }
    }

    return 0;
}
</syntaxhighlight>

<BR/>
=== Send+Receive Data Variables ===
You can send data variables from one board to another.  Next example demonstrates how variables can be sent, and received by the remote side.  We also send an "ID" as the first data byte to identify what type of data is coming in.  '''Note that the wireless can only transport 24-bytes through a single packet.'''

<syntaxhighlight lang="c">
#include <stdint.h>
#include "wireless.h"

/* Sender will send a packet with multiple variables */
void sender(void)
{
    /* We will send 9 bytes in our wireless packet : */
    uint8_t pkt_id = 1;  /* 1 byte  */
    uint32_t var1 = 123; /* 4 bytes */
    float var2 = 1.23;   /* 4 bytes */

    /* Create the packet.  See docs of wireless_form_pkt() */
    mesh_packet_t pkt;
    uint8_t hops = 1;
    wireless_form_pkt(&pkt, addr, mesh_pkt_ack, hops,
                      3,
                      &pkt_id, sizeof(pkt_id),
                      &var1, sizeof(var1),
                      &var2, sizeof(var2));

    /* TODO Should probably check if packet was formed correctly before sending */
    wireless_send_formed_pkt(&pkt);
}

void receiver(void)
{
    mesh_packet_t pkt;
    if (wireless_get_rx_pkt(&pkt, 100)) {
        /* Check packet type before we access the data
         * Packet ID was the first byte form sender()
         */
        if (1 == pkt.data[0]) {
            uint32_t var1 = 0;
            float var2 = 0;
            wireless_deform_pkt(&pkt, 3,
                                NULL, sizeof(uint8_t), /* Skip 1st byte which was ID */
                                &var1, sizeof(var1),   /* 2nd data was uint32_t from sender() */
                                &var2, sizeof(var2));  /* 3rd data was float from sender */
        }
    }
}
</syntaxhighlight>


<BR/>
=== Request Data ===
This example shows how a commander can request data variable from a sensor node.

<syntaxhighlight lang="c">
#include <stdint.h>
#include "wireless.h"

void commander(void)
{
    /* Send an application ack packet.
     * We will demand that sender sends an ACK itself rather than auto-ack
     */
    char cmd = 1;
    char hops = 1;
    char addr = 100;
    wireless_send(100, mesh_pkt_app_ack, &cmd, 1, hops);

    mesh_packet_t pkt;
    if (wireless_get_ack_pkt(&pkt, 100)) {
        /* TODO: Maybe use wireless_deform_pkt() to get our data? */
    }
}

void sensor(void)
{
    mesh_packet_t pkt;
    if (wireless_get_rx_pkt(&pkt, 100)) {
        /* Check if we were asked for an application ACK */
        if (wireless_is_ack_required(&pkt)) {
            /* Send packet back to network source: pkt.nwk.src */
            wireless_form_pkt(&pkt, pkt.nwk.src, mesh_pkt_ack_rsp, 1,
                              1, &sensor_val, sizeof(sensor_val));
            wireless_send_formed_pkt(&pkt);
        }
    }
}
</syntaxhighlight>

<BR/>
== Troubleshooting ==
'''My boards cannot communicate.'''
*  Double check '''sys_config.h''' to make sure wireless channels are the same.
*  Did you use correct source and destination address?  Double check the wireless address set at '''sys_config.h'''
*  Are the wireless boards too far away from each other?
*  Try doing '''Project''' --> '''Clean''' and build/compile your code again.
'''Sometimes wireless doesn't work'''
*  This is normal.  The wireless mesh software will retry packets a few times, but this is an expected behavior and your software needs to be able to cope with this behavior.