### Install Mosquitto MQTT broker and clients

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/guides/mqtt/

Install the Mosquitto MQTT broker and its command-line clients on Linux or Raspberry Pi using apt.

```bash
sudo apt install mosquitto mosquitto-clients
```

--------------------------------

### Install Git and Clone the OpenSprinkler Firmware Repository

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/ospi/firmware-installation/

Run these commands on a Raspberry Pi with Raspberry Pi OS to install Git and clone the OpenSprinkler-Firmware repository with submodules.

```bash
sudo apt-get install git
cd ~
git clone --recurse-submodules https://github.com/OpenSprinkler/OpenSprinkler-Firmware.git
```

--------------------------------

### Build OpenSprinkler for OSPi

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/ospi/firmware-installation/

Build the firmware for the OSPi target. The script generates an executable named 'OpenSprinkler' and may offer to install a systemd service. It may enable I2C and set bus speed to 400 kHz; reboot if required.

```bash
sudo ./build.sh ospi
```

--------------------------------

### Change to the Firmware Directory

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/ospi/firmware-installation/

Navigate into the cloned OpenSprinkler-Firmware folder.

```bash
cd OpenSprinkler-Firmware
```

--------------------------------

### Build firmware with PlatformIO CLI

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/firmware-compilation/

Builds the firmware for OpenSprinkler v3 (os3x_esp8266) and v4 (os4_esp32c6_n8) using the PlatformIO CLI. For v4, use firmware.bin32n8 for OTA upload; firmware.factory.bin is for factory or USB-C flashing.

```sh
# OpenSprinkler v3
pio run -e os3x_esp8266

# OpenSprinkler v4 (ESP32-C6-N8)
pio run -e os4_esp32c6_n8
```

--------------------------------

### Run OpenSprinkler Manually

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/ospi/firmware-installation/

If the startup-service prompt was declined, run the firmware manually with this command.

```bash
sudo ./OpenSprinkler
```

--------------------------------

### Change to the Firmware Directory for Update

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/ospi/firmware-installation/

Navigate to the firmware folder before running the updater.

```bash
cd ~/OpenSprinkler-Firmware
```

--------------------------------

### Clone repository with submodules

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/firmware-compilation/

Clones the OpenSprinkler-Firmware repository including required submodules and enters the source directory.

```bash
git clone --recurse-submodules https://github.com/OpenSprinkler/OpenSprinkler-Firmware.git
cd OpenSprinkler-Firmware
```

--------------------------------

### Manual Update Commands

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/ospi/firmware-installation/

Run these commands from ~/OpenSprinkler-Firmware to manually update the firmware if updater.sh is unavailable or for troubleshooting.

```bash
git pull --ff-only
sudo ./build.sh ospi
sudo systemctl restart OpenSprinkler.service
```

--------------------------------

### Run the Firmware Updater

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/ospi/firmware-installation/

The updater performs a fast-forward-only Git pull, synchronizes submodules, rebuilds the firmware, and restarts the OpenSprinkler service.

```bash
sudo ./updater.sh
```

--------------------------------

### Factory reset: delete entire firmware folder

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/troubleshooting/

Alternative factory reset method that removes the entire OpenSprinkler-Firmware folder. Requires navigating to the parent directory first. After deletion, reinstall the firmware.

```bash
sudo rm -rf ~/OpenSprinkler-Firmware
```

--------------------------------

### Subscribe to a topic with mosquitto_sub

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/guides/mqtt/

Subscribe to an MQTT topic using the mosquitto_sub command-line tool to receive messages.

```bash
mosquitto_sub -h <broker_ip> -t "my_topic"
```

--------------------------------

### Debug build: uncomment ENABLE_DEBUG in defines.h

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/troubleshooting/

Open defines.h in an editor and uncomment the #define ENABLE_DEBUG line near the top to enable debug messages.

```c
#define ENABLE_DEBUG
```

--------------------------------

### Publish a message with mosquitto_pub

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/guides/mqtt/

Publish a message to a specified MQTT topic using the mosquitto_pub command-line tool.

```bash
mosquitto_pub -h <broker_ip> -t "my_topic" -m "message_content"
```

--------------------------------

### MQTT Command Subscription

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/guides/mqtt/

MQTT clients can control OpenSprinkler by publishing command messages to the configured subscribe topic. The payload must follow the HTTP API format: <endpoint>?<parameter1>=<value>&<parameter2>=<value>. Commands are fire-and-forget; no acknowledgement is published.

```APIDOC
## MQTT Command Subscription

### Description
Subscribe to a user-defined MQTT topic to receive commands. An MQTT client publishes a command message to the subscribe topic to control OpenSprinkler operations.

### Method
MQTT Publish

### Endpoint
`subscribe_topic` (configured in MQTT settings)

### Parameters
#### Payload
- **endpoint** (string) - Required - Two-letter code (without leading "/") as in the HTTP API.
- **parameters** (query string) - Required - Parameters separated by `&`, including `pw` (lowercase MD5 hash of device password) unless Ignore Password is enabled.

### Request Example
```
mosquitto_pub -h your_mqtt_broker -p 1883 -t subscribe_topic -m "cv?pw=xxx&rsn=1"
```

### Response
No response is published. Commands are fire-and-forget; invalid or rejected commands produce no MQTT reply.

### Supported Commands
- **Change Controller Variables** (`cv`) with parameters:
  - `rsn`: Reset all stations (include those waiting to run).
  - `rbt`: Reboot controller.
  - `en`: Operation enable/disable.
  - `rd`: Set rain delay time (in hours).
- **Manual Station Run** (`cm`)
- **Manually Start a Program** (`mp`)
- **Start Run-Once Program** (`cr`)

### Notes
- Maximum subscribe topic length: 24 characters.
- MQTT packet-size limit: 256 bytes on OpenSprinkler v3 and v4 (topic and protocol overhead count toward this limit). OSPi/Linux has no such limit.
- Oversized commands are silently discarded.
```

--------------------------------

### Send MQTT command with mosquitto_pub

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/guides/mqtt/

Use this command to publish an MQTT message to the subscribe topic. The payload follows the HTTP API format, e.g., 'cv?pw=xxx&rsn=1' to reset all stations. Replace 'your_mqtt_broker', 'subscribe_topic', and the password hash with your values.

```bash
mosquitto_pub -h your_mqtt_broker -p 1883 -t subscribe_topic -m "cv?pw=xxx&rsn=1"
```

--------------------------------

### Remove Legacy SysV Init Script

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/ospi/firmware-installation/

If systemctl reports the service does not exist, use these commands to stop and remove the legacy init script.

```bash
sudo /etc/init.d/OpenSprinkler.sh stop
sudo rm /etc/init.d/OpenSprinkler.sh
sudo update-rc.d OpenSprinkler.sh remove
```

--------------------------------

### Disable and Remove OpenSprinkler Service

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/ospi/firmware-installation/

Stop the unified firmware and remove it from system startup.

```bash
sudo systemctl disable --now OpenSprinkler.service
sudo rm /etc/systemd/system/OpenSprinkler.service
sudo systemctl daemon-reload
```

--------------------------------

### Debug build: restart background service

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/troubleshooting/

Restarts the OpenSprinkler background service after debug mode is done. Must be run as root (sudo).

```bash
sudo systemctl start OpenSprinkler.service
```

--------------------------------

### Debug build: stop background service

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/troubleshooting/

Stops the OpenSprinkler background service before running a debug build. Must be run as root (sudo).

```bash
sudo systemctl stop OpenSprinkler.service
```

--------------------------------

### Remove Richard Zimmerman's sprinklers_pi Program

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/ospi/firmware-installation/

Stop and remove the legacy sprinklers_pi program.

```bash
sudo /etc/init.d/sprinklers_pi stop
sudo rm /etc/init.d/sprinklers_pi
sudo update-rc.d sprinklers_pi remove
```

--------------------------------

### Remove Dan's Python OSPi Program

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/ospi/firmware-installation/

Stop and remove the legacy Dan's Python OSPi program.

```bash
sudo /etc/init.d/ospi stop
sudo rm /etc/init.d/ospi
sudo update-rc.d ospi remove
```

--------------------------------

### Factory reset: delete done.dat

Source: https://opensprinkler.github.io/OpenSprinkler-Firmware/troubleshooting/

Deletes the done.dat file in the firmware folder to trigger a factory reset on OSPi. Requires navigating to the firmware folder first. After deletion, reboot the Pi.

```bash
sudo rm -f done.dat
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.