---
title: Getting Started
layout: default
permalink: /getting-started
nav_order: 2
---

## Table of Contents
{: .no_toc .text-delta }

1. TOC
{:toc}
---

# Getting Started
{: .no_toc }

There are a number of steps that must be completed when first getting started with Stabilizer.
1. Update the Stabilizer Application
    1. Build the application by compiling the source code.
    1. Upload the application and programming it onto the device.
1. Set up MQTT for telemetry and configuration.

The following sections will walk you through completing each of these steps.

# Update Stabilizer

Firmware is compiled and loaded onto Stabilizer to program a specific application.

After receiving the Stabilizer hardware, you will need to flash firmware onto the device to use your
desired application.

## Building Firmware

1. Clone or download [stabilizer](https://github.com/quartiq/stabilizer)
```bash
git clone https://github.com/quartiq/stabilizer
```
1. Get [rustup](https://rustup.rs/)
    * The minimum supported Rust version (MSRV) is 1.52.0
1. Install target support
```bash
rustup target add thumbv7em-none-eabihf
```
1. Build Firmware with an optionally-specified MQTT broker IP.
```bash
BROKER="10.34.16.10" cargo build --release
```

## Uploading Firmware

Firmware is loaded onto stabilizer utilizing an ST-Link (V2-1 or greater) JTAG programmer.
* If a programmer is not available, please see the [alternative method](#alternative-using-usb)

Ensure the ST-Link is connected to Stabilizer as shown below.

![JTAG Connection]({{site.baseurl}}/assets/stabilizer-jtag.jpg)

All of the instructions below assume you have properly [`built the firmware`](#building-firmware).

Substitute `dual-iir` below with the application name you are flashing.

1. Install [cargo-binutils](https://github.com/rust-embedded/cargo-binutils/)
```bash
cargo install cargo-binutils
rustup component add llvm-tools-preview
```

1. Generate the binary file
```bash
cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin`
```

1. Copy `dual-iir.bin` into the ST-Link drive on your computer.


### Alternative: Using USB

If an ST-Link V2-1 or above is not available, you can upload firmware using a micro USB cable
plugged in to the front of Stabilizer.

1. Install the DFU USB tool [`dfu-util`](http://dfu-util.sourceforge.net)
1. Connect to the Micro USB connector below the RJ45
1. Short JC2/BOOT
1. Perform the Device Firmware Upgrade (DFU)
```bash
dfu-util -a 0 -s 0x08000000:leave -D dual-iir.bin
```

### Alternative: Firmware Development / Debug

The below instructions are useful for debugging or developing firmware

For an interactive flash experience with live logging, utilize `probe-run` as follows.

1. Install `probe-run`
```bash
cargo install probe-run
```
1. Build and run firmware on the device
```bash
cargo run --release --bin dual-iir
```
1. When using debug (non `--release`) mode, decrease the sampling frequency significantly.
  The added error checking code and missing optimizations may lead to the code
  missing deadlines and panicing.

# Set up and test MQTT

## Set up the Broker
Stabilizer requires an MQTT broker that supports MQTTv5. [Mosquitto](https://mosquitto.org/) has
been used during development, but any MQTTv5 broker is supported.

> _Note_: Mosquitto version 1 only supports MQTTv3.1. If using Mosquitto, ensure version 2.0.0 or
> later is used.

Stabilizer utilizes a static IP address for broker configuration. Ensure the IP address was
[configured](#building-firmware) properly to point to your broker before continuing.

We recommend running Mosquitto through [Docker](https://docker.com) to easily run Mosquitto on
Windows, Linux, and OSX. After docker has been installed, run the following command from
the `stabilizer` repository:
```
docker run -p 1883:1883 --name mosquitto -v `pwd`/mosquitto.conf:/mosquitto/config/mosquitto.conf -v /mosquitto/data -v /mosquitto/log eclipse-mosquitto:2
```

> _Note_: The above command assumes a bash shell. If using powershell, replace `` `pwd` `` with
> `${pwd}`

This command will create a container named `mosquitto` that can be stopped and started easily via
docker.

## Test the Connection
Once your broker is running, test that Stabilizer is properly connected to it.

To do this, we will check that Stabilizer is reporting telemetry on the following topic:
```
dt/sinara/dual-iir/00-11-22-33-44-55/telemetry
```
> **Note**: The telemetry topic will be different based on the programmed application and the MAC address
   of the device.

Download [MQTT-Explorer](http://mqtt-explorer.com/) to observe which topics have been posted to the
Broker.

![MQTT Explorer Configuration]({{site.baseurl}}/assets/mqtt-explorer.png)

> **Note**: Use the same broker address that you defined in the firmware for MQTT explorer.

Telemetry messages should come in approximately every 10 seconds when Stabilizer has connected to
the broker.  Once you observe incoming telemetry, Stabilizer has been properly configured and is
operational.