ESP32-based hardware monitor for CasaOS systems with OLED display, LED indicators, and Home Assistant integration via MQTT.

• Real-time System Monitoring: Displays CPU usage, temperature, memory stats, and network metrics
• RAID Status Monitoring: Shows RAID array status, progress, and health
• OLED Display: 128x64 display alternating between system and RAID information every 30 seconds
• LED Status Indicators: Green (OK) and Red (Error/Shutdown) LEDs for at-a-glance status
• Physical Shutdown Button: Long-press (2 seconds) to initiate ZimaBoard shutdown
• MQTT Integration: Publishes metrics to MQTT broker for remote monitoring
• Home Assistant Auto-Discovery: Automatic creation of 18 entities in Home Assistant
• Remote Shutdown: Trigger ZimaBoard shutdown from Home Assistant or any MQTT client

• ESP32 development board
• SSD1306 OLED display (128x64, I2C, address 0x3C)
• 2x LEDs (Green and Red)
• 1x Push button
• Appropriate resistors for LEDs
• Breadboard or custom PCB

PIN_LED_GREEN = 16  // Green status LED
PIN_LED_RED   = 17  // Red status LED
PIN_BUTTON    = 18  // Shutdown button (active low, internal pullup)
I2C SDA       = 21  // OLED data
I2C SCL       = 22  // OLED clock

The following libraries are automatically installed via PlatformIO:

• Adafruit SSD1306 @ ^2.5.11
• Adafruit GFX Library @ ^1.11.10
• ArduinoJson @ ^7.0.0
• PubSubClient @ ^2.8

git clone <repository-url>
cd zimaboard-monitor

Copy the sample secrets file and fill in your credentials:

cp src/secrets-sample.h src/secrets.h

Edit src/secrets.h with your configuration:

// WiFi Configuration
static const char* WIFI_SSID     = "YourWiFiSSID";
static const char* WIFI_PASSWORD = "YourWiFiPassword";

// CasaOS Configuration
static const char* CASA_USERNAME = "admin";
static const char* CASA_PASSWORD = "your-casaos-password";
static const char* CASA_HOST     = "192.168.1.122";  // Your ZimaBoard IP
static const uint16_t CASA_PORT  = 80;

// MQTT Configuration
static const char* MQTT_BROKER   = "192.168.1.123";  // Your MQTT broker IP
static const uint16_t MQTT_PORT  = 1883;
static const char* MQTT_USERNAME = "";  // Leave empty if no authentication
static const char* MQTT_PASSWORD = "";  // Leave empty if no authentication

Using PlatformIO:

# Build the project
pio run

# Upload to ESP32
pio run -t upload

# Monitor serial output
pio device monitor

• Long Press (2 seconds): Initiates ZimaBoard shutdown via CasaOS API
• Visual feedback on OLED shows hold duration
• Release before 2 seconds cancels the action
• After shutdown request, device enters "off" state (red LED stays on)

The display alternates between two screens every 30 seconds:

CasaOS RAID
-------------------
Name: md0
Level: 5
State: active
Prog: 100.0%
Disks: 4
ETA: 0s

CasaOS UTIL
-------------------
CPU: 45.2%  62C
MEM: 38.5%
Used: 3.08G / 8.00G
NET: eth0 up
Rx: 1.2GB Tx: 890MB

Published every 30 seconds (alternating with RAID metrics):

{
  "cpu_usage": 45.2,
  "cpu_temp": 62,
  "mem_usage_percent": 38.5,
  "mem_used_gb": 3.08,
  "mem_total_gb": 8.0,
  "net_interface": "eth0",
  "net_state": "up",
  "bytes_recv": 1280000000,
  "bytes_sent": 934000000
}

Published every 30 seconds (alternating with system metrics):

{
  "name": "md0",
  "level": 5,
  "status": "active",
  "percentage": 100.0,
  "disk_count": 4,
  "finish_time": 0
}

Publish to trigger shutdown:

mosquitto_pub -h 192.168.1.248 -t "zimaboard/monitor/shutdown/cmd" -m "PRESS"

The device automatically publishes MQTT discovery messages for Home Assistant.

System Sensors (9):

• sensor.cpu_usage - CPU utilization percentage
• sensor.cpu_temperature - CPU temperature in °C
• sensor.memory_usage - Memory utilization percentage
• sensor.memory_used - Memory used in GB
• sensor.memory_total - Total memory in GB
• sensor.network_interface - Active network interface name
• sensor.network_state - Network state (up/down)
• sensor.bytes_received - Network bytes received
• sensor.bytes_sent - Network bytes sent

RAID Sensors (6):

• sensor.raid_name - RAID array name
• sensor.raid_level - RAID level (0, 1, 5, etc.)
• sensor.raid_status - RAID array status
• sensor.raid_progress - Rebuild/resync progress percentage
• sensor.raid_disk_count - Number of disks in array
• sensor.raid_finish_time - Estimated time to completion (seconds)

Controls (3):

• binary_sensor.device_status - Device connectivity status
• button.shutdown - Remote shutdown button

No manual configuration needed! Entities appear automatically under:

Settings → Devices & Services → MQTT → ZimaBoard Monitor

type: entities
title: ZimaBoard Monitor
entities:
  - entity: sensor.cpu_usage
  - entity: sensor.cpu_temperature
  - entity: sensor.memory_usage
  - entity: sensor.raid_status
  - entity: sensor.raid_progress
  - entity: button.shutdown

Subscribe to all topics:

mosquitto_sub -h 192.168.1.248 -v -t "zimaboard/monitor/#"

• Verify I2C address (try 0x3D if 0x3C doesn't work)
• Check SDA/SCL connections
• Ensure OLED has power

• Verify SSID and password in secrets.h
• Check WiFi signal strength
• Monitor serial output for connection attempts

• Verify CasaOS credentials
• Ensure CasaOS is accessible at the configured IP:PORT
• Check firewall settings on ZimaBoard

• Verify MQTT broker is running: mosquitto -v
• Check broker IP address and port
• If using authentication, verify username/password
• Check firewall allows port 1883

• Ensure MQTT integration is configured in Home Assistant
• Check MQTT broker logs for connection from HA
• Wait up to 5 minutes for discovery to process
• Restart Home Assistant if needed

In src/main.cpp, modify:

const unsigned long SCREEN_INTERVAL_MS = 30UL * 1000UL;  // 30 seconds

const uint32_t SHUTDOWN_LONGPRESS_MS = 2000;  // 2 seconds

Edit topic constants at the top of src/main.cpp:

const char* MQTT_AVAIL_TOPIC = "zimaboard/monitor/availability";
// ... etc

• POST /v1/users/login - Authentication
• GET /v2/local_storage/raid?all=true - RAID status
• GET /v1/sys/utilization - System metrics
• POST /v1/sys/state/off - Shutdown request

MIT

Contributions welcome! Please open an issue or submit a pull request.

Cian911