# SLICES-FR Summer School Ariel OS Tutorial
## Before Starting
Have a quick glance at the available resources:
- [Ariel OS README][ariel-os-website]
- [Ariel OS manual][ariel-os-book]
- [Ariel OS API docs][ariel-os-rustdoc-docs]
Then, follow the [Getting Started guide of Ariel OS][ariel-os-getting-started] to install the required software and set up your machine. This tutorial will not use ESP devices, so that step can be skipped. Additionally, as we are only going to use remote boards instead of flashing them locally, installing `probe-rs` is also not required.
You *do* need to keep the `ariel-os` repository around for this tutorial.
> You should now be able to compile the `hello-world` example.
To be able to run firmware on IoT-LAB/SLICES-FR, [create an account][iot-lab-login], then follow [the prerequisites][iot-lab-guide-prerequisites] to install and configure the required software.
Optionally, you can also follow the rest of [the guide][iot-lab-guide] to make sure you are able to run a short experiment on the testbed. It would also be useful to go through the first half of the [Build System page][ariel-os-build-system] to get familiar with laze's terminology (tasks, modules, and contexts).
## Running Firmware on IoT-LAB/SLICES-FR
Unless you have already done so in the prerequisites, follow [the guide][iot-lab-guide] to learn how to use Ariel OS in combination with IoT-LAB.
> The `examples/log` example demonstrates logging, which prints on the debug output. On IoT-LAB, this uses the UART peripheral, the serial output being then [tunneled to the web interface][iot-lab-design]. More information about the debug console in Ariel OS can be [found in the manual][ariel-os-debug-console].
==In the rest of this tutorial, you will need to pass `-s debug-uart` to laze so that the debug output uses the UART peripheral. You may need to use the "Reset" button to restart the firmware in case early log lines get dropped.==
## In-Tree Applications
Although Ariel OS applications are usually better [developed out-of-tree][ariel-os-oot], the rest of this tutorial is to be followed in-tree, as we will heavily rely on the existing tests and examples from the repository.
In-tree applications (in the `tests` and `examples` directories) usually have the following layout:
```
.
├── src/
│ ├── main.rs
│ └── pins.rs
├── Cargo.toml
└── laze.yml
```
As its name implies, `main.rs` is the main Rust file. `pins.rs` is a module that is declared in `main.rs` where pins are defined for each MCU/board when needed. `Cargo.toml` is the [Cargo manifest][cargo-manifest] where crate metadata and dependencies are defined. Finally, the `laze.yml` file allows to specify [laze modules][ariel-os-laze-modules] the application depends on or conflicts with.
## Async Executors and the Timer Queue
Ariel OS embraces async Rust and [provides a system async executor][ariel-os-async-support] automatically started at startup.
1. This for instance allows to use async timers: [`ariel_os::time::Timer`][ariel-os-api-timer].
Starting from the `hello-world` example, add a loop that prints the `"Hello World!"` message every two seconds, then test it on IoT-LAB.
> As the `ariel_os::time` module is feature-gated (it is only enabled when the right [Cargo feature][cargo-features] is enabled), you will need to enable the `time` Cargo feature in the `hello-world` example's `Cargo.toml`:
>
> ```toml
> [dependencies]
> ariel-os = { …, features = ["time"] }
> ```
1. Now, define another async task (an async function "decorated" with the `#[ariel_os::task]` attribute), which prints another message of your choice every second, and test it on IoT-LAB.
## Random Number Generators
1. Look at the `examples/random` example, and modify it to simulate d20 rolls.
## I2C
1. Look at the `tests/i2c-controller` test, and modify it to read the `WHO_AM_I` register of an [HTS221 sensor][hts221-datasheet] connected as documented on the IoT-LAB page of your board.
You will need to:
- Adjust the pins and peripheral instances in the `pins.rs` file (refer to the [IoT-LAB page of your board][iot-lab-guide-supported-boards]).
- Specify the correct values for the sensor I2C address, the `WHO_AM_I` register address, and the ID expected by the test.
> I2C device addresses are 7-bit, you will need to bitshift the (write) address given by the datasheet.
## Multithreading
1. You can try out multithreading by running the `examples/threading` example. Have a look at the documentation to learn more about the [`#[ariel_os::thread]` attribute macro][ariel-os-api-thread-macro]. You will need to increase the stack size of the thread where the `stacksize` is specified to 2048 bytes.
## Bluetooth Low Energy (BLE)
> BLE support is currently experimental and undocumented. Only nRF52 MCUs are supported.
1. Have a look at [IoT-LAB's documentation of the Saclay site][iot-lab-saclay-site] and determine which supported boards are physically in the same room.
1. *If no other advertiser is already running in the room*, run the `examples/ble-advertiser` on a supported board. The default address currently is `0xff8f1a05e4ff`.
1. Run the `examples/ble-scanner` example on another supported board.
1. Look at the output and try to spot the advertiser address (you may need to reset the scanner to empty the set of already-seen addresses).
## Using Off-the-Shelf Crates as Dependencies
Until now we have mostly used facilities provided by the OS itself, Rust and Cargo however make it very easy to use third-party crates.
1. Start from the `tests/i2c-controller` test and use the [`hts221-async` crate][hts221-async-crate] to read the temperature from the connected HTS221 sensor.
You will need to:
- Add that crate as a dependency in that example's manifest. Currently you will need to use the following fork:
```toml
[dependencies]
hts221-async = { git = "https://github.com/drogue-iot/hts221-async.git", branch = "chore/go-stable" }
```
- Instantiate an `hts221_async::Hts221` driver, passing an instance of an [`I2cDevice`][ariel-os-api-i2cdevice] (as already created in that example) to it.
- Initialize the driver by calling `Hts221::initialize()`.
- Obtain the sensor reading using `Hts221::read()`.
- Print the temperature (e.g., using `info!()`).
> In the future, Ariel OS will provide a sensor abstraction, so that sensors can be accessed in a homogeneous manner and can easily be substituted with other similar sensors.
[ariel-os-website]: https://ariel-os.org/
[ariel-os-rev]: https://github.com/ariel-os/ariel-os/commit/ae20c9fe892761b5b05b033ee92900a9db9da8c0
[ariel-os-book]: https://ariel-os.github.io/ariel-os/dev/docs/book/
[ariel-os-getting-started]: https://ariel-os.github.io/ariel-os/dev/docs/book/getting-started.html
[ariel-os-oot]: https://ariel-os.github.io/ariel-os/dev/docs/book/getting-started.html#starting-an-application-project-from-a-template-repository
[ariel-os-build-system]: https://ariel-os.github.io/ariel-os/dev/docs/book/build-system.html
[ariel-os-laze-modules]: https://ariel-os.github.io/ariel-os/dev/docs/book/build-system.html#laze-modules
[ariel-os-rustdoc-docs]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/index.html
[ariel-os-debug-console]: https://ariel-os.github.io/ariel-os/dev/docs/book/debug-console.html
[ariel-os-async-support]: https://ariel-os.github.io/ariel-os/dev/docs/book/async-support.html
[ariel-os-api-timer]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/time/struct.Timer.html
[ariel-os-api-thread-macro]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/attr.thread.html
[ariel-os-api-i2cdevice]: https://ariel-os.github.io/ariel-os/dev/docs/api/ariel_os/i2c/controller/type.I2cDevice.html
[iot-lab-guide-prerequisites]: https://github.com/ariel-os/ariel-os/wiki/Running-Ariel-OS-on-IoT%E2%80%90LAB#prerequisites
[iot-lab-guide-supported-boards]: https://github.com/ariel-os/ariel-os/wiki/Running-Ariel-OS-on-IoT%E2%80%90LAB#boards-supported-on-iot-lab
[iot-lab-guide]: https://github.com/ariel-os/ariel-os/wiki/Running-Ariel-OS-on-IoT%E2%80%90LAB
[iot-lab-login]: https://www.iot-lab.info/testbed/login
[iot-lab-design]: https://www.iot-lab.info/docs/getting-started/design/
[iot-lab-saclay-site]: https://www.iot-lab.info/docs/deployment/saclay/
[hts221-datasheet]: https://www.st.com/resource/en/datasheet/hts221.pdf
[hts221-async-crate]: https://docs.rs/hts221-async/latest/hts221_async/
[cargo-manifest]: https://doc.rust-lang.org/cargo/reference/manifest.html
[cargo-features]: https://doc.rust-lang.org/cargo/reference/features.html