bhyve-mqtt

This app is designed to subscribe to the Orbit B-Hyve API and broadcast the messages out over MQTT topics. It also supports sending commands to control your B-Hyve devices through MQTT.

Features

• Connects to the Orbit B-Hyve API
• Publishes device status and details to MQTT topics
• Controls sprinkler zones via MQTT commands
• Supports turning zones on/off
• Automatically reconnects when connections are lost

Requirements

• Node.js v22 or higher (the Docker image and CI run Node 22 LTS)
• MQTT broker (like Mosquitto, HiveMQ, etc.)
• Orbit B-Hyve account and devices

Installation

git clone https://github.com/billchurch/bhyve-mqtt.git
cd bhyve-mqtt
cp .env-sample .env
# Edit .env with your credentials
npm install
npm start

Docker Usage

Pre-built images are available on both Docker Hub and GitHub Container Registry:

• Docker Hub: billchurch/bhyve-mqtt
• GitHub Container Registry: ghcr.io/billchurch/bhyve-mqtt

Supported Platforms

The Docker images are built for multiple architectures, supporting:

• linux/amd64: Windows, Intel Macs, standard Linux servers
• linux/arm64: Apple Silicon Macs, Raspberry Pi 4 (64-bit OS)
• linux/arm/v7: Raspberry Pi 3 and 4 (32-bit OS)
• linux/arm/v6: Older Raspberry Pi models (Pi Zero, Pi 1)

Docker will automatically pull the correct image for your platform when you run:

# From Docker Hub
docker pull billchurch/bhyve-mqtt:latest

# From GitHub Container Registry
docker pull ghcr.io/billchurch/bhyve-mqtt:latest

Version tags follow semantic versioning (e.g., 1.2.3, 1.2, 1).

Building Locally

If you prefer to build the image yourself:

# Build the image
docker build -t bhyve-mqtt .

# Run with your environment file
docker run --env-file myenvfile bhyve-mqtt

Environment Configuration

| key | description | |-----------------------|-------------------------------------------------------------------------------------------------| | ORBIT_EMAIL | Your Orbit B-Hyve account email | | ORBIT_PASSWORD | Your Orbit B-Hyve account password | | MQTT_BROKER_ADDRESS | MQTT broker URL (eg. mqtt://localhost:1883) | | MQTT_USER | MQTT broker username (optional – required if MQTT_PASSWORD is set) | | MQTT_PASSWORD | MQTT broker password (optional – required if MQTT_USER is set) | | MAX_RETRIES | (Optional) Maximum connection retry attempts (default: 10) | | RECONNECT_PERIOD | (Optional) Milliseconds between reconnection attempts (default: 5000) | | MQTT_KEEPALIVE_SECONDS| (Optional) Keepalive interval in seconds for MQTT heartbeats (default: 60, minimum valid: 10) |

The service now validates configuration at startup. Missing required variables or setting only one of MQTT_USER/MQTT_PASSWORD causes an immediate, descriptive exit instead of failing later in the connection flow.

MQTT Schema

Status Topics (published by bhyve-mqtt)

• bhyve/online - string - true when service is connected, false when disconnected (sent as LWT)

• bhyve/alive - string - Timestamp of last successful API connection

• bhyve/devices - json - Array of device IDs

• bhyve/device/{deviceID}/details - json - Complete device information RETAINED

• bhyve/device/{deviceID}/status - json - Current watering status

• bhyve/device/{deviceID}/zone/{num} - json - Zone configuration and status

• bhyve/device/{deviceID}/message - json - Events from the API for specific device

• bhyve/message - json - General events from the API

Command Topics (send to these topics)

• bhyve/device/{deviceID}/zone/{num}/set - json - Control a specific zone:

  { "state": "ON", "time": 5 }  // Turn on for 5 minutes

  { "state": "OFF" }  // Turn off

• bhyve/device/refresh - any - Request refresh of all device data

• bhyve/device/{deviceID}/refresh - any - Request refresh for specific device

Updating

For Node.js Installations

When updating to a newer version via git pull:

# Navigate to the project directory
cd bhyve-mqtt

# Pull the latest changes
git pull

# Install/update dependencies (IMPORTANT!)
npm install

# Restart the service
npm start

Important: Always run npm install after pulling updates. This ensures:

• New dependencies are installed
• Updated dependencies are upgraded to correct versions
• Security patches are applied

If you're using a process manager like pm2 or systemd:

# For pm2
pm2 restart bhyve-mqtt

# For systemd
sudo systemctl restart bhyve-mqtt

For Docker Installations

# Pull the latest image
docker pull billchurch/bhyve-mqtt:latest
# or
docker pull ghcr.io/billchurch/bhyve-mqtt:latest

# Stop and remove the old container
docker stop bhyve-mqtt
docker rm bhyve-mqtt

# Start with the new image
docker run -d --name bhyve-mqtt --env-file .env billchurch/bhyve-mqtt:latest

For Docker Compose:

docker compose pull
docker compose up -d

Code Quality

npm test runs ESLint over the project (no runtime test suite at the moment):

npm run test   # eslint . --max-warnings 0
npm run lint:fix

Uses bhyve-api

This project now uses the bhyve-api npm module, which is a separate project that handles the core Orbit B-Hyve API communication.

Docker Setup

This project includes a production-ready Dockerfile that implements security best practices and optimized image size through multi-stage builds.

Building the Docker Image

Build the image with:

docker build -t bhyve-mqtt .

You can tag the image with a version:

docker build -t bhyve-mqtt:1.0 .

Running the Container

The simplest way to run the container is using an environment file:

# Create your environment file
cp .env-sample .env
# Edit .env with your credentials
nano .env

# Run with environment variables from file
docker run -d --name bhyve-mqtt --env-file .env bhyve-mqtt

Alternatively, specify environment variables directly:

docker run -d --name bhyve-mqtt \
  -e [email protected] \
  -e ORBIT_PASSWORD=your-password \
  -e MQTT_BROKER_ADDRESS=mqtt://your-broker:1883 \
  -e MQTT_USER=your-mqtt-user \
  -e MQTT_PASSWORD=your-mqtt-password \
  bhyve-mqtt

Container Management

View logs:

docker logs bhyve-mqtt

Follow logs in real-time:

docker logs -f bhyve-mqtt

Stop the container:

docker stop bhyve-mqtt

Restart the container:

docker restart bhyve-mqtt

Remove the container:

docker rm -f bhyve-mqtt

Docker Compose

For easier management, you can use Docker Compose. Create a docker-compose.yml file:

services:
  bhyve-mqtt:
    image: bhyve-mqtt:latest
    container_name: bhyve-mqtt
    restart: unless-stopped
    env_file:
      - .env

Then run:

docker compose up -d