Skip to content

⚙ Getting Started

Before building, you need to configure your credentials and format your SD card.

⚙ Configuration

💾 Formatting the microSD Card

The microSD card must be formatted as FAT32.

Warning

Formatting the card will erase all of its contents. Back up any important files before proceeding.

  • Windows:

    1. Insert the microSD card into your computer.
    2. Open File Explorer, right-click on the SD card drive, and select Format.
    3. Choose FAT32 from the "File system" dropdown menu.
    4. Click Start.

  • macOS:

    1. Insert the microSD card.
    2. Open Disk Utility.
    3. Select the SD card from the list on the left.
    4. Click Erase.
    5. Choose MS-DOS (FAT) from the "Format" dropdown.
    6. Click Erase.

  • Linux:

    1. Insert the microSD card.
    2. Open a terminal and run lsblk to identify the device name (e.g., /dev/sdX).
    3. Unmount the card if it's auto-mounted: sudo umount /dev/sdX*.
    4. Format the card: sudo mkfs.vfat -F 32 /dev/sdX1 (assuming the partition is /dev/sdX1).

🔑 Configure Credentials

  1. Create secrets.h: In the include/ directory, create a file named secrets.h.
  2. Add Credentials: Copy the contents of include/secrets.h.tmpl into your new secrets.h file and update the values. This file contains the credentials for the Wi-Fi Manager Access Point and the FTP server.

include/secrets.h

#pragma once

// --- WiFi Credentials ---
// Not currently used.
#define WIFI_SSID "YourWiFiNetworkName"
#define WIFI_PASSWORD "YourWiFiPassword"

// --- AP Mode ---
// #define WIFI_AP_SSID "AutoConnectAP-FrameFi"
// #define WIFI_AP_PASSWORD "password"

// --- Web Server ---
// #define WEB_SERVER_USER "admin"
// #define WEB_SERVER_PASSWORD "password"

// --- FTP Mode ---
// #define FTP_USER "user"
// #define FTP_PASSWORD "password"

// --- MQTT ---
// #define MQTT_CLIENT_ID "FrameFi" // Must be unique on the MQTT network
// #define MQTT_HOST "192.168.1.100"
// #define MQTT_PORT 1883
// #define MQTT_USER "user"
// #define MQTT_PASSWORD "password"

Note

This project uses WiFiManager to handle Wi-Fi connections via a captive portal, so you don't need to hardcode your network credentials. The WIFI_SSID and WIFI_PASSWORD fields in secrets.h are placeholders for a potential future feature and are not currently used.

📡 Wi-Fi and MQTT Setup

When you first boot the device, it will create a Wi-Fi Access Point (AP) that you can connect to from your computer or phone to configure its Wi-Fi connection.

Tip

Configure FTP and MQTT settings first in the Setup page before configuring Wi-Fi to avoid terminating WiFiManager.

param

  • SSID: By default, the AP name is FrameFi-<MAC>, where <MAC> is the last 6 characters of the device's MAC address. This is configured by leaving WIFI_AP_SSID commented out in secrets.h. To set a custom SSID, uncomment WIFI_AP_SSID and provide your own name.
  • Password: By default, the AP is open and does not require a password. To set a password, uncomment WIFI_AP_PASSWORD in secrets.h and provide a password.

In the WiFiManager Configure WiFi page, you can also configure the following:

  • Wi-Fi Credentials: Set the SSID and password for the Wi-Fi network the device is to connect to.

param

In the WiFiManager setup page, you can also configure the following:

  • FTP Credentials: Set the username and password for the FTP server. The values in secrets.h are used as the default values on the portal.
  • MQTT Settings: Configure the MQTT broker, port, username, and password. The values in secrets.h are used as the default values on the portal.

Tip

Hit the back button twice to get back to the main page after saving FTP and MQTT settings.

param

🔒 Secrets Management

This project uses sops for encrypting and decrypting secrets. The following files are encrypted:

  • include/secrets.h
  • scripts/.env

The above files are ignored by git to prevent the accidental comitting of secrets.

*.enc files are saved encrypted secrets for making it easier to save credentials.

Decrypting Secrets

To decrypt the files, run the following command:

task decrypt

sops -d include/secrets.h.enc > include/secrets.h
sops -d --input-type dotenv --output-type dotenv scripts/.env.enc > scripts/.env

Encrypting Secrets

Note

Before encrypting any files, you must add your GPG key's fingerprint or other public key information to the .sops.yaml file at the root of the project. This authorizes you to encrypt and decrypt the files.

To encrypt the files after making changes, run the following command:

task encrypt

sops -e include/secrets.h > include/secrets.h.enc
sops -e --input-type dotenv --output-type dotenv scripts/.env > scripts/.env.enc

🔗 References