This is a Ruby library to interact directly with ESPHome using the native API. It can be used as a library as part of another application, or as a CLI for directly interacting with devices if the device doesn't have a web server or MQTT connection.
Install the gem and add to the application's Gemfile by executing:
bundle add esphomeIf bundler is not being used to manage dependencies, install the gem by executing:
gem install esphomeUse the CLI to continously monitor entity states and the log:
$> esphome-monitor <host-name> <encryption-key>ESPHome
Laundry Room Motion Sensor 2025.7.5 - Aug 18 2025, 16:55:47
================================================================================
Bluetooth : off [14:30:30]
Factory Reset Radar : PRESS
Illuminance : 47.1 lx [14:30:30]
Max Range : 5400 mm [14:30:30]
Min Range : 300 mm [14:30:30]
Presence : not occupied [14:30:30]
Radar Bluetooth MAC Address : unknown [14:30:30]
Radar Firmware Version : 2.04.23101915 [14:30:30]
Restart : PRESS
Restart Radar : PRESS
Target 1 Angle : 0 ° [14:30:30]
Target 1 Distance : 0 mm [14:30:30]
Target 1 Speed : 0 mm/s [14:30:30]
Target 1 X : 0 mm [14:30:30]
Target 1 Y : 0 mm [14:30:30]
Target 2 Angle : 0 ° [14:30:30]
Target 2 Distance : 0 mm [14:30:30]
Target 2 Speed : 0 mm/s [14:30:30]
Target 2 X : 0 mm [14:30:30]
Target 2 Y : 0 mm [14:30:30]
Target 3 Angle : 0 ° [14:30:30]
Target 3 Distance : 0 mm [14:30:30]
Target 3 Speed : 0 mm/s [14:30:30]
Target 3 X : 0 mm [14:30:30]
Target 3 Y : 0 mm [14:30:30]
Timeout : 1 s [14:30:30]
Uptime : 77611 s [14:30:31]
WiFi Signal Strength : -72 dBm [14:30:34]
[14:30:29] Connected
[14:30:30] [I][app:149]: ESPHome version 2025.7.5 compiled on Aug 18 2025, 16:55:47
[14:30:30] [I][app:151]: Project ccutrer.ld2450 version 1.0
[14:30:30] [I][i2c.idf:104]: Results from bus scan:
[14:30:30] [I][i2c.idf:110]: Found device at address 0x44
Serial proxies are supported. You can either use the esphome-serial-proxy command to connect directly to an ESPHome device and connect stdin/stdout to the serial port, or you can use it from a Ruby library to obtain an IO-like interface:
gem "esphome", "~> 1.1"
require "esphome/serial_proxy"
io = ESPHome::SerialProxy.open("device", "encryption_key", baud: 4800, data_bits: 8, parity: :odd, stop_bits: 1)
io.write("some_data")
io.readpartial(64)
io.close
# OR
io = ESPHome::SerialProxy.open(URI.parse("esphome://:encryption_key@device/"), baud: 4800, data_bits: 8, parity: :odd, stop_bits: 1)
io.write("some_data")
io.readpartial(64)
io.close
# OR
ESPHome::SerialProxy.open("device", "encryption_key", "uart_instance_name", baud: 115_200) do |io|
io.write("ATI\r")
io.flush
io.close
end- Alarm Control Panel
- Camera
- Event
- Media Player
- Services
- Siren
- Update
- Valve
These entities can be parsed and state shown, but not have all possible commands sent to them:
- Fan
- Light
You can enable completion of device names (looked up from the ESPHome dashboard) by adding these lines to .bashrc:
complete -C esphome-monitor esphome-monitor
complete -C esphome-serial-proxy esphome-serial-proxyBug reports and pull requests are welcome on GitHub at https://github.com/ccutrer/esphome-ruby.
The gem is available as open source under the terms of the MIT License.
