ESPHome Ruby Library
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.
Installation
Install the gem and add to the application's Gemfile by executing:
bundle add esphome
If bundler is not being used to manage dependencies, install the gem by executing:
gem install esphome
Usage
Use the CLI to continously monitor entity states and the log:
$> esphome-monitor <host-name> <encryption-key>
ESPHome
Laundry Room Motion Sensor (2025.5.1 - Jun 28 2025, 14:27:10)
================================================================================
Switch - Bluetooth : [11:25:26] false
Sensor - Illuminance : [11:25:26] 38.4 lx
Number - Max Range : [11:25:26] 5400 mm
Number - Min Range : [11:25:26] 100 mm
BinarySensor - Presence : [11:25:26] false
TextSensor - Radar Bluetooth MAC Address: [11:25:26] unknown
TextSensor - Radar Firmware Version : [11:25:26] 2.04.23101915
Sensor - Target 1 Angle : [11:25:26] 0 °
Sensor - Target 1 Distance : [11:25:26] 0 mm
Sensor - Target 1 Speed : [11:25:26] 0 mm/s
Sensor - Target 1 X : [11:25:26] 0 mm
Sensor - Target 1 Y : [11:25:26] 0 mm
Sensor - Target 2 Angle : [11:25:26] 0 °
Sensor - Target 2 Distance : [11:25:26] 0 mm
Sensor - Target 2 Speed : [11:25:26] 0 mm/s
Sensor - Target 2 X : [11:25:26] 0 mm
Sensor - Target 2 Y : [11:25:26] 0 mm
Sensor - Target 3 Angle : [11:25:26] 0 °
Sensor - Target 3 Distance : [11:25:26] 0 mm
Sensor - Target 3 Speed : [11:25:26] 0 mm/s
Sensor - Target 3 X : [11:25:26] 0 mm
Sensor - Target 3 Y : [11:25:26] 0 mm
Number - Timeout : [11:25:26] 1 s
Sensor - Uptime : [11:25:26] 248262 s
Sensor - WiFi Signal Strength : [11:25:27] -60 dBm
[11:25:26][I][app:115]: ESPHome version 2025.5.1 compiled on Jun 28 2025, 14:27:10
[11:25:26][I][app:117]: Project ccutrer.ld2450 version 1.0
[11:25:26][I][i2c.idf:102]: Results from i2c bus scan:
[11:25:26][I][i2c.idf:108]: Found i2c device at address 0x44
Unsupported Entities
- Alarm Control Panel
- Camera
- Event
- Media Player
- Services
- Siren
- Update
- Valve
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/ccutrer/esphome-ruby.
License
The gem is available as open source under the terms of the MIT License.