# CommonSense

Firmware for the CommonSense project.

## Compile and Run

The firmware depends on the S132 softdevice. Before running the firmware, the
softdevice has to flashed to the chip.

### Flashing the Softdevice

1. Erase the chip
   ```bash
   $ probe-rs erase --chip nRF52832_xxAA
   ```
2. Flash the softdevice
   ```bash
   $ probe-rs download --verify --binary-format hex --chip nRF52832_xxAA s132_nrf52_7.3.0_softdevice.hex
   ```

### Compile and Run

1. Install the required tools. Consult `Dockerfile` for specifics
2. Build the firmware
   ```bash
   $ cargo build --release
   ```
3. Flash / run the firmware
   ```bash
   $ cargo fr
   $ # OR
   $ cargo run --release
   ```

### Compile and Run using Docker

1. Build the docker image
   ```bash
   $ docker build . -t commonsense
   ```
2. Build the firmware
   ```bash
   $ docker run --rm -v $PWD:$PWD -w $PWD -u $(id -u):$(id -g) commonsense cargo build --release
   ```
3. Flash / run the firmware
   ```bash
   $ docker run --privileged -v /dev/bus/usb/:/dev/bus/usb --rm -v $PWD:$PWD -w $PWD -u $(id -u):$(id -g) commonsense cargo fr
   $ # OR
   $ docker run --privileged -v /dev/bus/usb/:/dev/bus/usb --rm -v $PWD:$PWD -w $PWD -u $(id -u):$(id -g) commonsense cargo run --release
   ```

## Notes

- If flashing fails after being successful the first time, take a look at this:
  https://users.rust-lang.org/t/probe-rs-fails-to-work-after-first-time-use-successful/103234
- This may be useful for unit testing: https://crates.io/crates/embedded-test
- Currently this project is being developed on the nrf52-dk board with the
  nrf52832 chip. When mature enough, it will be ported to the nrf52810 to run
  on the actual hardware. Locations to modify:
  - `memory.x` - consult the
    [nrf-softdevice](https://github.com/embassy-rs/nrf-softdevice)
    documentation for more information
  - `Cargo.toml` - change the `nrf52832` feature to `nrf52810`
  - `.cargo/config.toml` - change the `nrf52832` chip to `nrf52810`
- TODO: Find out how to properly set up the license (the softdevice is
  proprietary)
- If the device locks up, use the
  [nrf-recover](https://docs.rs/crate/nrf-recover/latest) utility
- [Pinning to use nRF52DK as programmer](https://devzone.nordicsemi.com/f/nordic-q-a/14058/external-programming-using-nrf52-dk)
- For examples of how to use embassy to program nRF chips, see https://github.com/embassy-rs/embassy/tree/main/examples (and look for nrfXXX)

## Troubleshooting

### Core locking up

One possible cause for the core to lock up is to have a flash memory
configuration that doesn't match the selected softdevice.

#### Background

When the device powers up, it looks for certain things at certain positions
in memory, namely the interrupt vector table and the program entrypoint.
The interrupt vector table and entrypoint it finds are from the softdevice.
After initialization, the softdevice then attempts to hand over control to the
user program. The user program again has an interrupt vector table and an
entrypoint that are expected to be at a certain position in memory.
Specifically, they are expected to be right after the softdevice. If they are
not there, the device enters a hard fault state and locks up the core.

This means that the flash memory configuration in `memory.x` has to be correct
for the program to start up properly:

```
MEMORY
{
  FLASH : ORIGIN = 0x00000000 + <softdevice size>, LENGTH = <flash memory size> - <softdevice size>
  ...
}
```

The softdevice size can be found in the release notes of the softdevice. This
is a pdf that is downloaded along with the hex file from the nordic website.
The flash memory size depends on the model of microcontroller used.

#### Solution

1. Make sure `memory.x` is configured correctly for the selected softdevice. E.g., for `S112` running on an `nRF52832` chip:
    ```
    MEMORY
    {
      FLASH : ORIGIN = 0x00000000 + 100K, LENGTH = 512K - 100K
      RAM : ORIGIN = 0x20000000 + 30K, LENGTH = 64K - 30K
    }
    ```
2. Recover the device from it's locked state. This erases the flash memory:
    ```
    $ probe-rs erase --chip nRF52832_xxAA --allow-erase-all
    ```
4. Compile and flash the program:
    ```
    $ cargo run --bin blinky --release
    ```
    The program will not run successfully at this time, as it requires the softdevice to be flashed as well.
2. Flash the desired softdevice, e.g., `S112`:
    ```
    $ probe-rs download --verify --binary-format hex --chip nRF52832_xxAA s112_nrf52_7.3.0_softdevice.hex
    ```