Device Setup

How to set up and configure devices.

Device Setup

This guide walks you through setting up a physical DeadLetter ESP32 device (the sender).
The device is responsible for encrypting messages and pinning the registry trust anchor.

You will configure the device using the deadletter-setup CLI tool over USB.

Requirements

• ESP32 DeadLetter device flashed with firmware
• USB cable
• One computer running macOS, Linux, or Windows
• Access to your Registry and Backend gateway IP addresses

Step 1 — Download Device Setup Tool

Download the correct binary for your platform from the DeadLetter download server:

macOS

curl http://YOUR_VPS_IP/dist/deadletter-setup-mac -o deadletter-setup
chmod +x deadletter-setup
sudo mv deadletter-setup /usr/local/bin/

Linux

curl http://YOUR_VPS_IP/dist/deadletter-setup-linux -o deadletter-setup
chmod +x deadletter-setup
sudo mv deadletter-setup /usr/local/bin/

Windows (PowerShell)

curl http://YOUR_VPS_IP/dist/deadletter-setup-windows.exe -o deadletter-setup.exe

Step 2 — Verify Checksum (Critical)

Always verify the checksum before executing:

curl http://YOUR_VPS_IP/dist/SHA256SUMS.txt
sha256sum deadletter-setup

Ensure the output matches the entry in SHA256SUMS.txt.

Step 3 — Plug In the ESP Device

Connect the ESP32 to your computer using USB.

The setup tool will automatically detect available serial ports.

Step 4 — Configure Registry & Backend

Run:

deadletter-setup --registry REGISTRY_IP:PORT --backend BACKEND_IP:PORT

Example:

deadletter-setup --registry 192.168.1.200:8081 --backend 192.168.1.200:8080

If multiple devices are connected you will be prompted to select one.

Step 5 — Trust Fingerprint Ceremony

During setup the device prints a Root Trust Fingerprint:

Root Trust Fingerprint:
aa:bb:cc:dd:ee:ff:...

This fingerprint must be verified out-of-band with the receiver.

Do NOT copy fingerprints from documentation or screenshots.

This is the moment your trust anchor is pinned permanently.

Step 6 — Completion

If successful you will see:

✓ Configuration Complete - Device Rebooting

The device is now ready to securely send DeadLetter messages.

Troubleshooting

The ESP device is now cryptographically bound to your registry. All trust flows from this step.