# ChirpStack Tutorial

## Overview

This tutorial series will show you how to set up a near-production ChirpStack LoRaWAN Network Server and all the supporting infrastructure necessary for receiving data from sensors in the field.

It is organized into four main sections: ChirpStack server, gateway, embedded device, and metrics.

### ChirpStack

You will start by installing ChirpStack on a cloud server, along with its dependencies: PostgreSQL, Redis, and Mosquitto MQTT. You will make the ChirpStack web interface available over the internet via the Nginx web server with a free certificate from Let's Encrypt.

Next, you will set up Mosquitto MQTT to be able to make secure connections with LoRaWAN gateways by creating your own certificate authority (CA) and configuring Mosquitto to use that CA. You will also set up ChirpStack to be able to generate certificates for gateways with the CA.

### Gateway

Your next step will be to set up the LoRaWAN gateway, which in this case is a Raspberry Pi with WM1302 hat. You will install the ChirpStack Gateway Bridge on the Pi and set it up to communicate with the ChirpStack server via secure MQTT. Then you will install the Semtech SX1302 Hardware Abstraction Layer on the Pi to interact with the WM1302 hat and forward LoRaWAN packets to the ChirpStack Gateway Bridge.

### Embedded Device

Once the LoRaWAN gateway is running, you will set up a Heltec CubeCell microcontroller using the Arduino integrated development environment (IDE). The CubeCell will connect to the gateway, which will send the data to the ChirpStack server.

You will then set up a BME280 temperature/pressure/humidity sensor to send data using the Cayenne Low Power Payload (LPP) protocol.

### Metrics Collection and Visualization

You will then set up an InfluxDB server to integrate with ChirpStack and store the sensor metrics, and finally you will set up Grafana to visualize the metrics.

## Software Components

The flexibility of ChirpStack's components can be overwhelming to a newcomer, but fortunately not every component is needed. This tutorial will use the following subset of components:

```mermaid
flowchart TD
  subgraph Embedded Device
  CubeCell
  end
  CubeCell -- LoRaWAN --> pf
  subgraph Gateway
  pf(Semtech Packet Forwarder) -- UDP --> gb(ChirpStack Gateway Bridge)
  end
  gb -- MQTT over TLS --> mb(Mosquitto MQTT Broker)
  subgraph Cloud Server
  mb -- MQTT --> cs(ChirpStack)
  cs -- HTTPS --> InfluxDB
  cs --- pg[(PostgreSQL)]
  cs --- redis[(Redis)]
  InfluxDB -- HTTPS --> Grafana
  end
```

## Necessary Experience

Experience with the following is recommended but not required if you are able to learn on your own:

- LoRaWAN
- Debian/Ubuntu-flavored Linux
  - General editing/copying/moving files
  - File ownership and permission
  - User and group management
  - SystemD unit files
  - Git cloning
  - Adding a custom Apt repo
  - `ufw` firewall
- Raspberry Pi
  - Installing the OS and getting access over the network
  - SPI/I2C setup
- Arduino IDE
  - C programming language (basic/intermediate)
  - With custom boards
- Computer networking
  - Purchasing a domain name
  - Renting compute from a cloud vendor
  - Secure shell (SSH)
  - Nginx reverse proxy
  - TLS certificate generation
    - Let's Encrypt
      - DNS-01 protocol
    - Self-generated certificate authority
      - [`cfssl`](https://github.com/cloudflare/cfssl)
  - Mosquitto MQTT
    - Topic naming format; particularly wildcards

## Hardware

The following hardware is necessary:

- Raspberry Pi 3/4 (5 might work)
  - Power supply
  - Seeed Studio WM1302 SPI module (WM1302-SPI-US915-M) with Raspberry Pi hat
- Heltec Cubecell HTCC-AB01
  - USB-C to USB-A cable
  - Breadboard
  - BME280 sensor with header pins (presoldered or solder it yourself)
  - Jumper wires
  - (Optional) 3.7V battery with JST connector
  - (Optional) 1W 6V solar panel