Home Assistant · custom integration

Everything your bike knows, on the dashboard.

cowboy-ha pulls your Cowboy e-bike into Home Assistant as a real device — battery, range, mileage, trips, crash and theft state, GPS position and firmware, all as native entities you can chart, template and automate against.

Open in HACS Source

MIT licensed In the default HACS catalog Home Assistant 2024.12+ No cloud besides Cowboy's

Ottocowboy · polling 60s

Battery

Range left

0km

Mileage

0km

CO₂ saved

0kg

Last trip · device_tracker

Home12.4 km · 34 minHome

The spec sheet

One device per bike, grouped the way Home Assistant groups it. Names follow your HA language; the keys below are what you'll find in the source.

sensorRide & battery

Remaining batterybattery_state_of_charge% · battery

Remaining rangeremaining_rangekm · distance

Battery healthbattery_health%

Mileagetotal_distancekm · total

Time driventotal_durationduration

Saved CO₂total_co2_savedg

Last seenseen_attimestamp

Last ride modelast_ride_modeenum

Auto-lockauto_lockmin · duration

Remaining battery (internal PCB)pcb_battery_state_of_chargehidden by default

sensorTrips

Distance todaytoday_distancekm · total

Last trip distancelast_trip_distancekm

Last trip durationlast_trip_durationduration

Last trip endedlast_trip_ended_attimestamp

Last trip CO₂ savedlast_trip_co2_savedg

Last trip calorieslast_trip_calorieskcal · energy

Last trip titlelast_trip_titletext

binary_sensorState

Stolenstolensafety

Crashedcrashedsafety

Batterybattery_insertedplug

Update availableupdate_availablesuperseded · disabled

device_tracker updatePosition & firmware

Your bike’s namethe tracker takes the device name · GPS, with accuracydevice_tracker

Firmwareinstalled vs. deployed release, with notesupdate

sensorDiagnostic

Last crashlast_crash_started_attimestamp

Warranty endswarranty_ends_attimestamp

Speed limitdisplayed_speedkm/h · speed

In Home Assistant

A normal device page — no custom cards required. Everything is a standard entity, so the logbook, history, statistics and voice assistants pick it up for free.

Settings › Devices & services › Cowboy

The Cowboy device page in Home Assistant, showing device info, a sensor list with battery, mileage, battery health and range, a diagnostic device tracker, and a logbook of recent state changes.

A device page from a real install, captured in 2024 — it predates the trip sensors and the firmware entity, and some names there were renamed by hand.

Install

Three minutes, no YAML. The integration ships in the default HACS catalog, so there's no custom repository to add.

STEP 01

Add it from HACS

In HACS, search for Cowboy and download it. Then restart Home Assistant.

Rather do it by hand? Copy custom_components/cowboy into your Home Assistant config folder — the README has the commands.

STEP 02

Sign in

Settings → Devices & services → Add integration → Cowboy. The first field is labelled Username — it wants the email address your Cowboy account uses.

The bike shows up as its own device with every entity attached. Nothing else to configure.

STEP 03

Automate

Everything is a plain entity, so ordinary triggers, templates and history graphs work — no special handling anywhere.

For example, a nudge when the battery runs low:

# Tell me before the bike is flat
triggers:
  - trigger: numeric_state
    entity_id: sensor.otto_remaining_battery
    below: 20
actions:
  - action: notify.mobile_app_phone
    data:
      message: "Charge the bike — {{ states('sensor.otto_remaining_range') }} km left"

Entity ids start with your bike’s name in the Cowboy app — otto here. Swap in yours.

Worth knowing

The honest small print — how credentials are handled, what happens with more than one bike, and how often it talks to Cowboy.

Your session survives restarts

Cowboy keeps only the last 10 sessions per account. Signing in on every Home Assistant restart used to push your phone out of that list and log you out of the app, so the session is stored and reused instead.

It stays valid for about a year. If it expires or is rejected, the integration signs in again by itself and only asks you for credentials if that fails too.

Where the password lives

The password is kept in the config entry so the session can be renewed without you. It isn't used for anything else, and nothing is sent anywhere except Cowboy's own API.

Removing the integration logs the session out. Restarting Home Assistant does not.

More than one bike

Cowboy requires one account per bike, so households with two bikes have two logins. Add the integration a second time with the other account's credentials — each bike becomes its own device with its own entities.

Polling, not pushing

Bike data is polled every minute by default, adjustable from 1 to 60 minutes under Configure on the integration card.

Trip data is on its own fixed 15-minute cycle and firmware releases are checked hourly — neither follows that setting, so Distance today can lag the battery reading by a quarter of an hour.

Firmware is reported, not flashed — the update entity tells you what's available; installing still happens in the Cowboy app.

Built on top

Once the entities exist, anything that speaks to Home Assistant can use them. Things other people have made:

glance-cowboy by nichtlegacy

A drop-in custom-api widget for Glance that renders these entities as a dashboard card — battery bar, mileage, time driven, and optional status rows for security, crash and firmware.

Made something? Open an issue and it can go here.