Skip to content

About

A Glance custom-api widget for Cowboy bike stats powered by Home Assistant.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

glance-cowboy

A Glance widget to display Cowboy bike data from Home Assistant.

Glance custom-api Data source cowboy-ha Home Assistant data YAML MIT License

Overview • Quick Start • Widget Options • References

Cowboy widget preview


Overview

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 Mileage and Time Driven
  • optional extra stats for Battery Health, Saved CO2, and Internal PCB
  • optional status rows for Battery, Security, Crash, and Firmware

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

Quick Start

  1. Copy widgets/cowboy.yml into your Glance widgets/ folder
  2. Set HASS_URL and HASS_API_KEY in your .env or Glance environment
  3. Adjust the entity IDs in options to match your Home Assistant setup
  4. Include the widget in glance.yml
HASS_URL=http://homeassistant.local:8123
HASS_API_KEY=your_home_assistant_long_lived_access_token
pages:
  - name: Mobility
    columns:
      - size: small
        widgets:
          - $include: widgets/cowboy.yml

Reference config: examples/glance.yml

HASS_API_KEY is a Home Assistant long-lived access token:

  1. Open Home Assistant
  2. Click your username in the bottom-left corner
  3. Open Security
  4. Scroll to Long-Lived Access Tokens
  5. 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.


Widget Options

Cowboy (widgets/cowboy.yml)

Recommended start (hero-primary-metric: battery, core stats on, optional extras off)

Cowboy widget recommended configuration

- 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

Behavior Notes

  • hero-primary-metric: battery shows battery percentage above the bar and Remaining range below it
  • hero-primary-metric: range shows remaining range above the bar and Battery below it
  • the colored bar always reflects battery percentage
  • if the bike image URL fails, the hero falls back to a simple Cowboy label
  • 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/off and true/false

References

  • Dashboard platform: glanceapp/glance
    Widget implementation targets Glance custom-api behavior and config style.

  • Cowboy integration: elsbrock/cowboy-ha
    Home Assistant integration used as the primary data source.


MIT License © 2026

About

A Glance custom-api widget for Cowboy bike stats powered by Home Assistant.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors