Trash Pickup Reminder CLI

A Go CLI application for trash pickup reminders via AWTRIX 3 displays.

Features

• 📅 Fetches monthly trash pickup schedules from public API
• 💾 Smart caching (month-based, never refetches)
• 📺 Two display modes:
  • Status: Persistent display showing next pickup
  • Alarm: Tomorrow-only notification with button dismiss
• 🎨 Visual color-coded indicators for trash types
• 🔄 Designed for cron-based automation
• 🚀 Zero dependencies except MQTT and CLI framework

Installation

Download Pre-built Binary

Download the latest release for your platform from the releases page.

Available platforms:

• Linux (amd64, arm64, arm)
• macOS (amd64, arm64)
• Windows (amd64)

Extract the archive and move the binary to your PATH:

# Linux/macOS
tar -xzf bdg_Linux_x86_64.tar.gz
sudo mv bdg /usr/local/bin/

# Or just run from current directory
./bdg --help

Prerequisites

• AWTRIX 3 compatible display (Ulanzi)
• MQTT broker access

Build from Source

# Clone the repository
git clone https://github.com/llxff/bdg.git
cd bdg

# Install dependencies
go mod download

# Build
task build
# OR
go build -o bin/bdg .

The binary will be created at bin/bdg.

Usage

Examples

Status Display

The status command shows a persistent view with color-coded chips representing each trash type and the date of the next pickup:

• Color chips: 4×7 pixel rectangles, one per trash type (Bio, Gelbe Tonne, Papier, etc.)
• Date text:
  • "TOM" in red for tomorrow
  • Weekday abbreviations (MON, TUE, etc.) for next 7 days
  • "DD.MM" format for dates beyond 7 days

Alarm Notification

The alarm command sends a prominent notification when pickup is tomorrow:

• Red background with blinking text
• Lists all trash types scheduled for tomorrow
• Requires button press to dismiss (hold=true)
• Silent exit if pickup is not tomorrow

---

Version Information

Check the installed version:

./bdg version

Self-Update

Update to the latest release:

./bdg update

Force update even if already on latest version:

./bdg update --force

Status Command

Updates the AWTRIX display with a persistent status showing the next pickup day.

./bdg status \
  --city-id=123 \
  --area-id=456 \
  --mqtt-broker=tcp://192.168.1.10:1883 \
  --mqtt-prefix=awtrix_abc123

Recommended cron schedule: Every hour

0 * * * * /path/to/bdg status --city-id=123 --area-id=456 --mqtt-broker=tcp://192.168.1.10:1883 --mqtt-prefix=awtrix_abc123

Alarm Command

Sends a notification ONLY if the next pickup is tomorrow. Otherwise exits silently.

./bdg alarm \
  --city-id=123 \
  --area-id=456 \
  --mqtt-broker=tcp://192.168.1.10:1883 \
  --mqtt-prefix=awtrix_abc123

Recommended cron schedule: Once daily at 8 PM

0 20 * * * /path/to/bdg alarm --city-id=123 --area-id=456 --mqtt-broker=tcp://192.168.1.10:1883 --mqtt-prefix=awtrix_abc123

Flags

Flag	Required	Default	Description
--city-id	✅	-	City ID from trash API
--area-id	✅	-	Area ID from trash API
--mqtt-broker	✅	-	MQTT broker URL (e.g., tcp://192.168.1.10:1883)
--mqtt-prefix	✅	-	AWTRIX MQTT prefix
--mqtt-username	❌	-	MQTT username (if authentication required)
--mqtt-password	❌	-	MQTT password (if authentication required)
--cache-dir	❌	~/.cache/bdg	Local cache directory
--ignore-trash	❌	[]	Trash types to ignore (repeatable)

Finding Your City and Area IDs

1. Visit the BDG waste calendar and select your municipality and street
2. Open your browser's developer tools (F12) and go to the Network tab
3. Look for API calls to https://bdg.jumomind.com/webservice.php?idx=termins
4. Extract city_id and area_id from the URL parameters

Ignoring Trash Types

To ignore specific trash types (e.g., bio waste):

./bdg status \
  --city-id=123 \
  --area-id=456 \
  --mqtt-broker=tcp://192.168.1.10:1883 \
  --mqtt-prefix=awtrix_abc123 \
  --ignore-trash=BARNIM_BIO \
  --ignore-trash=BARNIM_PAP

Using MQTT Authentication

If your MQTT broker requires authentication:

./bdg status \
  --city-id=123 \
  --area-id=456 \
  --mqtt-broker=tcp://192.168.1.10:1883 \
  --mqtt-prefix=awtrix_abc123 \
  --mqtt-username=your_username \
  --mqtt-password=your_password

Security Note: Avoid exposing credentials in cron jobs or shell history. Consider using environment variables or a configuration file in production.

Display Behavior

Status Display

• Shows color-coded chips for each trash type (4×7 pixel rectangles)
• Displays date information:
  • Tomorrow: "TOM" in red
  • Within 7 days: Weekday abbreviation (MON, TUE, etc.) in white
  • More than 7 days: Date format (DD.MM) in white
• Multiple pickups on the same day show multiple color chips
• Published to: [PREFIX]/custom/trash

Alarm Notification

• Only triggered if pickup is tomorrow
• Red background with blinking text
• Shows all trash types for tomorrow
• Requires button press to dismiss (hold: true)
• Published to: [PREFIX]/notify

Caching

The app caches API responses per month in ~/.cache/bdg/YYYY-MM.json:

• ✅ Never refetches existing months
• ✅ Automatically fetches next month if needed (when today + 7 days crosses month boundary)
• ✅ Stores raw JSON from API
• ✅ Thread-safe atomic writes

To clear cache: rm -rf ~/.cache/bdg/

Development

Running Tests

task test
# OR
go test -v -race -coverprofile=coverage.txt -covermode=atomic ./...

View coverage:

go tool cover -html=coverage.txt

Linting

Install golangci-lint:

# macOS
brew install golangci-lint

# Linux
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

Run linter:

task lint
# OR
golangci-lint run ./...

Project Structure

bdg/
├── cmd/              # CLI commands (root, status, alarm)
├── internal/
│   ├── api/          # HTTP client for trash API
│   ├── cache/        # File-based caching
│   ├── domain/       # Core business logic (pure functions)
│   ├── mqtt/         # MQTT publisher
│   └── awtrix/       # AWTRIX payload builders
└── main.go           # Entry point

See AGENTS.md for detailed architecture and contribution guidelines.

Troubleshooting

"Connection refused" when publishing to MQTT

• Verify MQTT broker is running: telnet <broker-ip> 1883
• Check firewall rules
• Ensure broker URL format: tcp://IP:PORT

"No upcoming pickups found"

• Verify city-id and area-id are correct
• Check if all trash types are in --ignore-trash list
• Clear cache and refetch: rm -rf ~/.cache/bdg/

AWTRIX display not updating

• Check MQTT prefix matches your AWTRIX device
• Verify MQTT broker connectivity from AWTRIX device
• Check AWTRIX logs for incoming messages

Cache issues

• Cache location: ~/.cache/bdg/
• Format: YYYY-MM.json (e.g., 2025-12.json)
• Delete specific month: rm ~/.cache/bdg/2025-12.json

License

MIT License - See LICENSE file for details.

Releases

Releases are automatically built and published using GoReleaser when a new tag is pushed:

# Create a new version tag
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

This will trigger the GitHub Actions workflow to:

• Build binaries for Linux, macOS, and Windows
• Create checksums
• Generate release notes from CHANGELOG.md
• Publish the release to GitHub

Local Release Testing

Test the release process locally:

# Check GoReleaser configuration
task release-check

# Build snapshot (without publishing)
task release

Contributing

See CONTRIBUTING.md for contribution guidelines.