🔥 Valor Fireplace CLI

A command-line tool to control your Valor Fireplace (powered by Mertik) directly from your terminal.

Features

• ✅ Fahrenheit or Celsius - Choose your preferred temperature unit
• ✅ Easy commands (on, off, status, temp, mode)
• ✅ Direct fireplace control via TCP/IP
• ✅ No dependencies on Homebridge
• ✅ Standalone binary

Hardware Requirements

To use this CLI tool (or the official Valor mobile app), your Valor Fireplace must have the Valor WiFi Upgrade Kit installed:

• Required Hardware: Valor WiFi Upgrade for V-module Kit - GV60WiFi
• Compatible Models: Valor L1, L1 See Thru, L2, L3, LT1, LT2, LX1, LX2, H5, H6, and P2 Heaters
• Official Mobile App: Valor 1.0 Remote App
• Installation Guide: GV60WIFI Upgrade Instructions (PDF)

This WiFi module enables TCP/IP control over your local network, which is what this CLI tool uses to communicate with your fireplace. Once the GV60WiFi module is installed and connected to your network, you can use either the official Valor mobile app or this command-line tool.

Quick Start

Install from npm (recommended)

npm install -g valor-fireplace-cli

This installs the valor-cli command globally. Skip ahead to Configure Your Fireplace.

Or install from source

git clone https://github.com/omarshahine/valor-fireplace-cli.git
cd valor-fireplace-cli
npm install
npm run build

Configure Your Fireplace

# Copy the example configuration
cp .fireplace-config.example .fireplace-config

# Edit with your fireplace's IP address
nano .fireplace-config

Set your fireplace's IP address in .fireplace-config:

FIREPLACE_IP=192.168.1.XXX  # Replace with your fireplace's IP
TEMPERATURE_UNIT=F          # F for Fahrenheit, C for Celsius

Use It

# If installed via npm
valor-cli status
valor-cli temp 72
valor-cli on
valor-cli off

# If running from source, the wrapper script is handy
./fp status
./fp temp 72

Commands

Control

Command	Description	Example
status	Get fireplace status	valor-cli status
on	Turn on (starts at 68°F/20°C)	valor-cli on
off	Turn off safely	valor-cli off
temp <value>	Set temperature	valor-cli temp 72
mode <mode>	Set mode	valor-cli mode eco

Diagnostics

Command	Description	Example
probe	TCP liveness check with RTT (exit 0 if reachable)	valor-cli probe
raw <hex>	Send arbitrary bytes for protocol exploration	valor-cli raw 303303
watch	Tail status with timestamps until Ctrl+C	valor-cli watch --interval=5000

Use probe when the WiFi module's LEDs go red/green to check if local TCP control still works. Use raw and watch to investigate unmapped opcodes or capture state transitions — see PROTOCOL.md.

Available Modes

• temperature - Temperature control mode
• manual - Manual flame height control
• eco - Energy saving mode
• off - Turn off

Status Output

valor-cli status decodes the live status packet, including a heuristic warning when the controller appears to be in a Mertik GV60 ignition lockout (failed-ignition state that requires on-site intervention). Output includes:

• Current temperature, target temperature, mode
• Burner output as a percent (0-100%) — actual modulated flame level
• Pilot lit / shutting down / igniting / aux on flags
• Fan speed (0-4)
• Decorative light on/off plus brightness percent
• Raw status bits in hex for diagnostics
• Schedule/timer overlay indication when a remote program is driving the setpoint

See PROTOCOL.md for the full wire-level reference and decoded packet layout.

Configuration

Method 1: Config File (Recommended)

Create or edit .fireplace-config:

# Fireplace IP address
FIREPLACE_IP=192.168.1.141

# Temperature Unit: F (Fahrenheit) or C (Celsius)
# Default: F
TEMPERATURE_UNIT=F

The CLI looks for .fireplace-config first in the current directory and each parent directory, and falls back to $HOME/.fireplace-config. Drop one in your home directory if you want valor-cli to work from anywhere on a system-wide install.

Temperature Unit Options:

• TEMPERATURE_UNIT=F - Display and input temperatures in Fahrenheit (41-97°F)
• TEMPERATURE_UNIT=C - Display and input temperatures in Celsius (5-36°C)

Method 2: Environment Variable

export FIREPLACE_IP=192.168.1.141

Add to your ~/.zshrc for persistence:

echo 'export FIREPLACE_IP=192.168.1.141' >> ~/.zshrc
source ~/.zshrc

Method 3: Command Argument

valor-cli status 192.168.1.141

Temperature Guide

Fahrenheit (Default)

Comfortable Settings:

• 68°F - Cool comfort
• 72°F - Standard warmth
• 75°F - Warm
• 77°F - Extra warm

Valid Range: 41°F to 97°F

Celsius

Comfortable Settings:

• 20°C - Cool comfort
• 22°C - Standard warmth
• 24°C - Warm
• 25°C - Extra warm

Valid Range: 5°C to 36°C

Note: The fireplace uses Celsius internally. When using Fahrenheit, temperatures are automatically converted. All calculations remain accurate regardless of your display preference.

📖 For more details about temperature units, see TEMPERATURE_UNITS.md

Examples

Basic Usage

# Check status
valor-cli status

# Turn on and set temperature
valor-cli on
valor-cli temp 72

# Change mode
valor-cli mode eco

# Turn off
valor-cli off

With Wrapper Script

./fp status
./fp temp 72
./fp mode temperature

Status Output

Fireplace Status:
──────────────────────────────────────
Mode:               Temperature
Current Temp:       68°F
Target Temp:        72°F
Guard Flame:        On
Igniting:           No
Shutting Down:      No
Aux On:             No
Reachable:          Yes
──────────────────────────────────────

Project Structure

valor-fireplace-cli/
├── src/                    # TypeScript source code
│   ├── cli.ts             # Main CLI interface
│   ├── controllers/       # Fireplace control logic
│   ├── models/            # Data models and status parsing
│   └── utils/             # Temperature conversion, config reader
├── dist/                  # Compiled JavaScript
├── fp                     # Quick wrapper script ⭐
├── .fireplace-config      # Configuration file
├── package.json           # NPM configuration
├── tsconfig.json          # TypeScript config
├── README.md              # Documentation
└── LICENSE                # Apache 2.0

Development

Build

npm run build

Clean Build

npm run clean && npm run build

Install Globally

npm link
valor-cli status

Distribution

This project is standalone and can be:

1. Cloned and used locally:

   git clone https://github.com/yourusername/valor-fireplace-cli.git
   cd valor-fireplace-cli
   npm install
   npm run build
   ./fp status

2. Installed globally:

   npm install -g valor-fireplace-cli
   valor-cli status

3. Shared as source:

   • Zip the folder
   • Recipients need Node.js >= 20
   • Run npm install && npm run build

Technical Details

• Protocol: TCP socket connection on port 2000
• Hardware: Valor WiFi Module (GV60WiFi) using Mertik protocol
• Temperature Range: 41-97°F (5-36°C internally)
• Connection Timeout: 5 minutes
• Status Refresh: 15 seconds
• Ignition Time: 30-40 seconds
• Shutdown Time: 30 seconds

Advanced Features

Temperature Unit Configuration

See TEMPERATURE_UNITS.md for detailed information about using Celsius or Fahrenheit.

Customization

• Modify source code in src/ directory
• Rebuild with npm run build
• Temperature ranges can be adjusted in src/utils/temperatureConverter.ts

Troubleshooting

Can't Connect

• Check fireplace is powered on
• Verify IP address is correct
• Ensure on same network
• Try: ping 192.168.1.141

Command Not Found

npm run build
npm link

Invalid Temperature

• Fahrenheit: Valid range is 41-97°F
• Celsius: Valid range is 5-36°C
• Check your TEMPERATURE_UNIT setting in .fireplace-config

Need to Rebuild?

npm run clean
npm install
npm run build

System Requirements

• Node.js >= 20
• TypeScript >= 4.4.4
• macOS, Linux, or Windows with WSL

Credits

This project is built upon the excellent work from:

• homebridge-mertik-fireplace by tritter

License

Apache-2.0

Author

Omar Shahine

---

Your fireplace, your command line. 🔥