Skip to content

Add initial README.md for mqtt_example #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add initial README.md for mqtt_example #5

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 73 additions & 1 deletion mqtt_example/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,73 @@
# Esp32 quiz device
# ESP32 Quiz Device

A portable keychain-sized quiz device built with ESP32, featuring an LCD display and a 3D printed case. This device is designed as a conference tool for participants to engage in quizzes during events. The codebase also serves as an example for conference workshops.

## Features

- Collects single choice answers from participants
- Transmits responses via MQTT protocol
- Works with a separate Python backend to determine winners

## Requirements

- ESP32 development board
- LCD display
- Docker (for development environment)
- VS Code or other IDE with Dev Container support
- Chrome-based browser (for macOS users)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

USB passthrough is tricky, maybe we should just use the web-flash? (and ask everyone to install chrome)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then we can use the same devcontainer for all systems. I'll update the README. Could you prepare the common devcontainer, please? (I'm not sure if just renaming the OSX container and removing the other ones is enough)


## Environment Variables

The following environment variables must be set to build and run the project:

```
WIFI_SSID
WIFI_PASSWORD
MQTT_BROKER_URL
MQTT_USER
MQTT_PASSWORD
```

### Example Build

```bash
# Set required environment variables
export WIFI_SSID="your_wifi_ssid"
export WIFI_PASSWORD="your_wifi_password"
export MQTT_BROKER_URL="your_mqtt_broker_url"
export MQTT_USER="your_mqtt_username"
export MQTT_PASSWORD="your_mqtt_password"

# Build the project
cargo build
```

Note: All environment variables must be set before building, otherwise you'll encounter compilation errors. The project uses the `env!` macro which requires these variables to be defined at compile time.

## Development Setup

This project supports development containers for consistent development environments across different systems.

### Using Dev Containers

1. Choose the appropriate dev container for your system:
- `.devcontainer/linux/devcontainer.json` for Linux
- `.devcontainer/mac/devcontainer.json` for macOS
- `.devcontainer/wsl2/devcontainer.json` for Windows WSL2

2. Open the project in VS Code or another IDE that supports Dev Containers.

3. When opening for the first time, the container will build automatically. This process may take several minutes.

### macOS USB Port Forwarding

On macOS, USB ports are not forwarded to the container by default. You'll need to use Web USB:

1. The container will start a web page for flashing
2. Open this page in a Chrome-based browser (which supports Web USB)
3. Use the following command to flash the device:

```
web-flash --chip=esp32 target/xtensa-esp32-espidf/debug/esp32-mqtt
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you change the line in .cargo/config.toml, then you can just run cargo run or press "run" button in IDE, without having to change the binary path when changing profile. Also you can set env variables in IDE run configurations.

I don't think we will be compiling and running this on the workshop anyway. Better if people hacked on the smaller spi example. This one would just be used as demonstration of some features.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree, I will update my PR later.

```

Loading