Start on Thread Tutorial

[bradjc]

Create a section of the book for the thread tutorial.

We already had a module for writing a sensor app. I repurposed that. We no longer need the exercises/app duplicate so this removes that.

---

4/22/24 Update

The tutorial will create a temperature sensor that can read the local temperature while also providing the preferred temperature to a central controller (think controlling the temperature of a shared workspace from your desk).

User input will be given using the nrf52840dk push buttons. Participants will first build a "local implementation" that is not networked. For this, they will have a temperature graph (@bradjc mentioned this idea) on half the screen and a "desired temperature" on the other half. This value can be increased or decreased using the push buttons.

After implementing this, participants will add networking capabilities to transmit their preferred temperature to the central controller. The central controller will average the individual preferences and send the room's current setpoint to the end device. The screen will now display the temperature graph, the user's preference, and the global averaged set point (in addition to the temperature graph).

Finally, we will demonstrate some form of Tock's robustness in which either the openthread or sense/control application seg faults, but the screen still displays relevant information (still need to settle on this).

The major steps will be as follows:

1. Read temperature sensor (this will be the internal sensor on the nrf52840, but this will suffice)
2. Read push button presses
3. Display data on screen (desired temperature and temperature graph)
4. Setup Thread networking
5. Robustness demonstration

I will update this comment with a todo list soon.

[tyler-potyondy]

Here is an initial draft / outline for the Thread tutorial. This is a somewhat brief and early version, but should be a good starting point for discussion. We will be discussing this further in the network working group call tomorrow and I will post any relevant updates.

THREAD TUTORIAL OUTLINE

GOAL

The purpose of this tutorial is to demonstrate Tock's Thread network stack, emphasize the Thread stack's ease of use for wireless network research, and the robustness Tock provides.

PART 1: Introduction to Tock

• Provide an overview of Tock (design, isolation properties, and OS advantages)
• Guide participants in flashing Tock, configuring Tockloader, and configuring libtock-c

PART 2: Tock Thread App

For this portion of the tutorial, we will have 4 nrf52840dk running OpenThread and serving as routers. We will guide the participants in developing a Tock Thread application that attaches to the OpenThread routers. To serve as a visual aid, we will use a Thread topology manager so participants can view their devices attaching to the router in real time.

(as a note, I am planning to write a topology visualization tool for this portion of the tutorial. The nordic topology visualizer is somewhat clunky and is not visually appealing.)

PART 3: Tock Multi-tenancy and Robustness

For this portion, we will demonstrate a separate application that reads the nrf52840dk temperature sensor and then sends the temperature data over the Thread network. (I am not entirely sure how this will look at this juncture and this will somewhat depend on the final Thread implementation Leon and I are still working on).

We will then conclude with a demonstration of Tock's robustness in light of "buggy" code. I suspect the wireless sensor network community in attendance will be less concerned with the security Tock provides. Likewise, I think we should frame this as a "buggy" app that enters an infinite loop rather than a malicious app.

[bradjc]

Guide participants in flashing Tock, configuring Tockloader, and configuring libtock-c

I would like to see us get the tutorial ready in advance, and try to make this homework done in advance. It seems like every time we spend a considerable amount of time on this.

For this portion of the tutorial, we will have 4 nrf52840dk running OpenThread and serving as routers. We will guide the participants in developing a Tock Thread application that attaches to the OpenThread routers. To serve as a visual aid, we will use a Thread topology manager so participants can view their devices attaching to the router in real time.

Sounds cool!

We will then conclude with a demonstration of Tock's robustness in light of "buggy" code. I suspect the wireless sensor network community in attendance will be less concerned with the security Tock provides. Likewise, I think we should frame this as a "buggy" app that enters an infinite loop rather than a malicious app.

We did something like this at a tutorial in the past (I think it was Sensys?), and the main difficulty with this is success looks like nothing is happening. It's not very engaging in practice. If we could come up with something that illustrates the same point in a way that is easier to connect with that would be helpful.

[alevy]

We will then conclude with a demonstration of Tock's robustness in light of "buggy" code. I suspect the wireless sensor network community in attendance will be less concerned with the security Tock provides. Likewise, I think we should frame this as a "buggy" app that enters an infinite loop rather than a malicious app.

We did something like this at a tutorial in the past (I think it was Sensys?), and the main difficulty with this is success looks like nothing is happening. It's not very engaging in practice. If we could come up with something that illustrates the same point in a way that is easier to connect with that would be helpful.

One thought: make it security egg-hunt---like some of us may have done as homework in a security class (typically with SQL injections). So we put some basic Thread app on one device and the goal of the this part of the tutorial is to craft and send a malicious Thread payload that crashes the app from each participant's board. So there is something kind of fun in doing this, and the result is that the app keeps respawning and some other functionality on the board (maybe a monitoring app displayed on the projector, or a clock, or a blinking light, or something) keeps running uninterrupted.

---

This plays two roles:

1. It demonstrates the resiliency of a multi-tenant OS (which I agree with Brad, turns out to not be that impressive to see on its own)
2. Demonstrates the importance of security to a non-security focused audience (maybe they would typically tend towards---"oh cool! let's throw the Internet on this thing", and this would be showing the potential pitfalls if done naively)

[bradjc]

So we put some basic Thread app on one device and the goal of the this part of the tutorial is to craft and send a malicious Thread payload that crashes the app from each participant's board.

This sounds great.

maybe a monitoring app displayed on the projector, or a clock

Hmm...motivating me to restart the screen work.

[brghena]

I like the "malicious payload" idea a lot here. Something about receiving buffer data and length, but then the length is a lie maybe?

The other mechanisms you've got if you're just using nRF52840DK boards is 4 buttons or 4 LEDs. At least button presses are more interactive than temperature sensing.

If you were to use something like a Microbit instead (the nRF52833 still has OpenThread support), you'd get the 5x5 LED matrix screen as an option.

[tyler-potyondy]

@bradjc Having participants complete the Tock / libtock-c setup prior to the tutorial would be ideal. Spending time sorting this out seems wasteful. I'm curious, have we tried this before? Is it reasonable to have a "complete before the tutorial..." list we send to attendees?

I suspect the normal getting started guide is sufficient for the setup, but there may be ways we can streamline this further. Considering how familiar we all are with Tock and the tooling, we are likely not the best audience to judge pain points etc. I will talk with some of the undergrads working with Pat and me that are new to the project to see if they found any parts of the setup particularly troublesome or ambiguous.

In regards to @alevy malicious packet idea, I think this is an excellent idea for demonstrating robustness. We will need to think of a way to frame this as a hypothetical "assume there is a bug in openthread such that...". I will give this some more thought, but I think this will be an excellent way to conclude the tutorial!

Thanks for the thoughts and feedback. I will keep thinking through these ideas and beginning codifying this into an actual tutorial.

[bradjc]

@bradjc Having participants complete the Tock / libtock-c setup prior to the tutorial would be ideal. Spending time sorting this out seems wasteful. I'm curious, have we tried this before? Is it reasonable to have a "complete before the tutorial..." list we send to attendees?

It's always been an idea, but when it's all hands on deck just to get a tutorial that works, trying to help people prepare in advance isn't a priority. I think we can do it if we aren't scrambling. Of course not everyone will have set it up in advance, but maybe people could help each other if at least some had.

[alevy]

Of course not everyone will have set it up in advance, but maybe people could help each other if at least some had.

If nothing else, it would help alleviate pressure on the typically terrible conference WiFi.

Perhaps just writing/maintaining the section on setting up a development environment as though it would just be done during the tutorial itself, and then linking to that chapter ahead of time so people can do it on their own beforehand.

[brghena]

That's right. The Tock repo is big enough that we had it on flash drives we passed around last time. It was never going to download for 30 people at once on conference wifi

[bradjc]

That's right. The Tock repo is big enough that we had it on flash drives we passed around last time. It was never going to download for 30 people at once on conference wifi

Oof. And new libtock-c is not trivial to compile the first time either on a slow connection.

[tyler-potyondy]

I had not thought about the slow conference WiFi. Getting a setup guide distributed to all attendees ahead of time will be a priority. I'll circle back to working on this in the next few weeks.

@brghena flashdrives as a fallback is also an excellent idea (considering I'm confident a few people will forget to get everything downloaded / setup ahead of time).

[brghena]

We also had some really really cheap laptops that we brought as backups for people who couldn't get the toolchain working. I think they were less than $100 each. Pat bought them, so he would remember more. Not sure if you want to lug that to another country, but a possibility at least.

[alevy]

What's the goal for this? Is @tyler-potyondy going to update it? If so, does he have write permissions to the relevant branch? If not, should we merge this with some "this is a placeholder" text such that @tyler-potyondy can open pull requests against the main branch?

[bradjc]

Open PRs against this branch maybe?

[lschuermann]

Ready just in time. :sweat_smile: