A Glance widget to display Cowboy bike data from Home Assistant.
Overview • Quick Start • Widget Options • References
A drop-in Glance custom-api widget to display Cowboy bike stats from Home Assistant.
The widget is designed primarily for a small Glance column and includes:
- a centered bike hero image
- a battery progress bar with state-based colors
- switchable hero metric via
hero-primary-metric - core stats for
MileageandTime Driven - optional extra stats for
Battery Health,Saved CO2, andInternal PCB - optional status rows for
Battery,Security,Crash, andFirmware
Rendering is hardened for common failure cases:
- Home Assistant unavailable
- missing required entity IDs
- missing or invalid state values
- broken bike image URLs
- missing unit metadata
- Copy
widgets/cowboy.ymlinto your Glancewidgets/folder - Set
HASS_URLandHASS_API_KEYin your.envor Glance environment - Adjust the entity IDs in
optionsto match your Home Assistant setup - Include the widget in
glance.yml
HASS_URL=http://homeassistant.local:8123
HASS_API_KEY=your_home_assistant_long_lived_access_tokenpages:
- name: Mobility
columns:
- size: small
widgets:
- $include: widgets/cowboy.ymlReference config: examples/glance.yml
HASS_API_KEY is a Home Assistant long-lived access token:
- Open Home Assistant
- Click your username in the bottom-left corner
- Open
Security - Scroll to
Long-Lived Access Tokens - Create a token and use it as
HASS_API_KEY
Your entity IDs may differ depending on your bike name and Home Assistant setup. Always copy the exact IDs from Home Assistant instead of assuming the defaults match your system.
Recommended start (hero-primary-metric: battery, core stats on, optional extras off)
- type: custom-api
title: Cowboy
cache: 30m
url: ${HASS_URL}/api/states
headers:
Authorization: "Bearer ${HASS_API_KEY}"
Content-Type: "application/json"
options:
battery-entity: sensor.cowboy_remaining_battery
range-entity: sensor.cowboy_remaining_range
mileage-entity: sensor.cowboy_mileage
time-driven-entity: sensor.cowboy_time_driven
battery-health-entity: sensor.cowboy_battery_health
internal-pcb-battery-entity: sensor.cowboy_remaining_battery_internal_pcb
saved-co2-entity: sensor.cowboy_saved_co2
battery-inserted-entity: binary_sensor.cowboy_battery
stolen-entity: binary_sensor.cowboy_stolen
crashed-entity: binary_sensor.cowboy_crashed
update-available-entity: binary_sensor.cowboy_update_available
bike-image-url: https://cdn.shopify.com/s/files/1/1772/1703/files/classic-black.png?v=1739294119&width=1440
hero-primary-metric: battery
show-battery: true
show-range: true
show-mileage: true
show-time-driven: true
show-battery-health: false
show-internal-pcb-battery: false
show-saved-co2: false
show-battery-inserted: false
show-stolen: false
show-crashed: false
show-update-available: false
template: |
# Requests, fallbacks, and rendering states are handled inside the template
...| Option | Type | Default | Description |
|---|---|---|---|
battery-entity |
string | sensor.cowboy_remaining_battery |
Remaining battery sensor |
range-entity |
string | sensor.cowboy_remaining_range |
Remaining range sensor |
mileage-entity |
string | sensor.cowboy_mileage |
Total mileage sensor |
time-driven-entity |
string | sensor.cowboy_time_driven |
Total time driven sensor |
battery-health-entity |
string | sensor.cowboy_battery_health |
Optional battery health sensor |
internal-pcb-battery-entity |
string | sensor.cowboy_remaining_battery_internal_pcb |
Optional internal PCB battery sensor |
saved-co2-entity |
string | sensor.cowboy_saved_co2 |
Optional saved CO2 sensor |
battery-inserted-entity |
string | binary_sensor.cowboy_battery |
Optional battery inserted binary sensor |
stolen-entity |
string | binary_sensor.cowboy_stolen |
Optional theft status binary sensor |
crashed-entity |
string | binary_sensor.cowboy_crashed |
Optional crash status binary sensor |
update-available-entity |
string | binary_sensor.cowboy_update_available |
Optional firmware update binary sensor |
bike-image-url |
string | shipped example image | Hero image URL |
hero-primary-metric |
string | battery |
Main hero value, allowed values: battery, range |
show-battery |
bool | true |
Show battery-based hero logic |
show-range |
bool | true |
Show range in the hero or the secondary hero line |
show-mileage |
bool | true |
Show mileage card |
show-time-driven |
bool | true |
Show time driven card |
show-battery-health |
bool | false |
Show battery health card |
show-internal-pcb-battery |
bool | false |
Show internal PCB card |
show-saved-co2 |
bool | false |
Show saved CO2 card |
show-battery-inserted |
bool | false |
Show battery status row |
show-stolen |
bool | false |
Show security status row |
show-crashed |
bool | false |
Show crash status row |
show-update-available |
bool | false |
Show firmware status row |
hero-primary-metric: batteryshows battery percentage above the bar andRemaining rangebelow ithero-primary-metric: rangeshows remaining range above the bar andBatterybelow it- the colored bar always reflects battery percentage
- if the bike image URL fails, the hero falls back to a simple
Cowboylabel - if Home Assistant returns invalid values, the widget hides unusable values instead of rendering broken output
- battery is clamped to
0..100 - battery health and internal PCB are clamped to
0..100 - range, mileage, time driven, and saved CO2 do not render negative values
- binary states accept both
on/offandtrue/false
-
Dashboard platform:
glanceapp/glance
Widget implementation targets Glancecustom-apibehavior and config style. -
Cowboy integration:
elsbrock/cowboy-ha
Home Assistant integration used as the primary data source.
MIT License © 2026
