Skip to content

API reference

The Python host binding, generated from its docstrings (DOC-001). The binding only sets traits: what a widget shows is computed by its front end, the same from every host.

Base classes

anywidget_instruments_automotive.AutomotiveWidget

Bases: InstrumentWidget

Base class of the widgets of anywidget-instruments-automotive.

It keeps the common traits of anywidget-instruments (label, tooltip, visible, disabled, size, style, theme) and adds:

max_age Seconds after which a value not updated is shown as stale; 0: never (ROB-001). hud Held by a :class:Cluster, the widget is shown in its head-up display mode (HUD-004).

Every widget is an indicator: mode is always "indicator" (API-002).

anywidget_instruments_automotive.QuantityWidget

Bases: AutomotiveWidget

A widget showing a physical quantity (API-005, UNIT-001 .. UNIT-017).

value In input_unit; None until a value is known (ROB-002). min, max Ends of the scale, in input_unit. unit Displayed unit; "": the one unit_system assigns (UNIT-003). input_unit Unit of value, min, max and limits; "": the metric unit of the quantity (UNIT-010). unit_system "metric", "imperial" or "us" (UNIT-001).

anywidget_instruments_automotive.DialWidget

Bases: QuantityWidget

A needle on an arc scale, and the value as text below it (DIAL-001 .. DIAL-005).

zones Coloured arcs, {"from", "to", "kind"} in input_unit; kind is "danger", "warning", "cold" or "charge" (DIAL-005). resolution Step of the readout, in the displayed unit. animate The needle glides to a new value; False: it jumps (DIS-003).

Dials

anywidget_instruments_automotive.Speedometer

Bases: DialWidget

Vehicle speed on a dial with a digital readout (DIAL-101, SPD-001 .. SPD-004).

The readout is rounded up to resolution after conversion, never down. The widget cannot guarantee the accuracy of the value it is given and does not replace the vehicle's speedometer (SPD-004): see the safety notice.

limit Speed limit in input_unit, marked on the scale; the readout is highlighted above it (SPD-003).

anywidget_instruments_automotive.Tachometer

Bases: DialWidget

Engine speed in rpm (DIAL-102 .. DIAL-104).

redline Start of the red zone; None: no red zone. shift_light Engine speed at and above which the shift light is lit. ready The vehicle can move: at 0 rpm the dial says READY (hybrid and electric drivetrains).

anywidget_instruments_automotive.FuelGauge

Bases: DialWidget

Fuel level from empty to full, with a reserve zone and the fuel pump symbol.

reserve Upper end of the reserve zone, in percent of a full tank; the pump symbol lights amber in it (DIAL-105). filler_side "left" or "right": the side of the filler flap (DIAL-106).

anywidget_instruments_automotive.TemperatureGauge

Bases: DialWidget

Coolant or oil temperature, with cold and hot zones (DIAL-107, DIAL-108).

cold Upper end of the cold zone; None: none. hot Start of the hot zone, where the temperature tell-tale lights red.

Tell-tales

anywidget_instruments_automotive.TellTale

Bases: AutomotiveWidget

A tell-tale: the symbol of a function, lit in the colour of its meaning.

Parameters:

Name Type Description Default
function str

One of :data:TELLTALE_FUNCTIONS ("engine", "oil_pressure", "high_beam"...). It sets the symbol, the name and the colour: red for a danger, amber for a warning, green for a function on, blue for the main beam (TEL-001).

'engine'
state str | None

"off", "on" or "blinking"; None (the default) until a state is known, shown as no value rather than as off (ROB-002).

None

state property writable

state: str | None

The state of the tell-tale: an alias of value.

anywidget_instruments_automotive.TellTaleCluster

Bases: AutomotiveWidget

A row of tell-tales: the direction indicators first, side by side, then the lit ones, red, then amber, then green and blue (TEL-006, TEL-009).

value is a list of tell-tales, each a dict {"function", "state", "label"} (label optional), a (function, state) pair or a :class:TellTale, whose function, state and label are copied. size is the size of one tell-tale.

set_telltale

set_telltale(function: str, state: str | None) -> None

Set the state of every tell-tale of function in the cluster.

Digital displays

anywidget_instruments_automotive.TripComputer

Bases: AutomotiveWidget

The figures of a trip (DIG-001 .. DIG-004).

value holds the raw figures, in metric units: speed (km/h), fuel_rate (L/h), distance (km), fuel_used (L), elapsed (s) and, optionally, range (km). The front end shows the instant consumption per hour below 5 km/h, no average before 0.1 km, and every figure in the units of unit_system; unit sets the unit of the consumptions ("L/100 km", "mpg (US)", "mpg (imperial)", "km/L").

With energy="electric" it shows the energy consumption from power (kW, negative when regenerating) and energy_used (kWh) instead, in kWh/100 km or mi/kWh (EV-006).

update

update(**figures: float | None) -> None

Set some figures of the trip, keeping the others.

anywidget_instruments_automotive.Odometer

Bases: QuantityWidget

Total and trip distance, in a mechanical-counter style (DIG-005).

value is the total and trip the trip distance, in input_unit (km by default); the counters never round a distance up.

anywidget_instruments_automotive.GearIndicator

Bases: AutomotiveWidget

The engaged gear, P, R, N, D or 1 to 8 (DIG-006).

suggestion ("up" or "down") shows a shift arrow (DIG-007). A gear number may be given as an int.

Electric and hybrid drivetrains

anywidget_instruments_automotive.PowerMeter

Bases: DialWidget

The power of the drivetrain in kW (EV-003 .. EV-005).

Positive while it drives the wheels, negative while it regenerates: the part of the scale below zero is the regeneration zone, and the meter says REGEN. ready: at 0 kW the meter says READY.

anywidget_instruments_automotive.StateOfChargeGauge

Bases: DialWidget

The charge of the traction battery, 0 to 100 % (EV-001, EV-002).

low Upper end of the low zone, in percent; the battery symbol lights amber in it. charging The battery is charging: a charging symbol and the text CHARGING.

anywidget_instruments_automotive.PowerFlow

Bases: AutomotiveWidget

Which of the engine, the battery and the wheels deliver and receive power.

value holds powers in kW: engine (≥ 0), battery (> 0 discharging, < 0 charging) and wheels (> 0 driven, < 0 braking with regeneration). The front end draws the flows as arrows and names them, with the mode: EV, HYBRID, ENGINE, CHARGING, REGEN or IDLE.

Layout

anywidget_instruments_automotive.Cluster

Bases: AutomotiveWidget

An instrument panel: dials on the sides, tell-tales between, displays below.

Parameters:

Name Type Description Default
children Iterable[AutomotiveWidget | Mapping[str, Any]]

The widgets of the panel: widgets of this library, or trait dictionaries with a _kind. A change to a widget shows in the panel.

()
Traits

hud Head-up display mode: mirrored, on black, figures in one colour with the tell-tale colours kept, no animation, and only the speedometer and the widgets whose own hud is true (HUD-001 .. HUD-006). theme, unit_system, brightness Applied to every widget held; a widget with a unit of its own keeps it (CLU-002, UNIT-004). max_items Most widgets shown; None: eight (DIS-001).

children property writable

children: list[AutomotiveWidget | Mapping[str, Any]]

The widgets of the panel, in order.

Names from the trait contract

Name Content
TELLTALE_FUNCTIONS Every tell-tale function
TELLTALE_STATES "off", "on", "blinking"
UNITS Every unit name the front end accepts (UNIT-017)
UNIT_SYSTEMS "metric", "imperial", "us"
GEARS The gears of a GearIndicator
TRIP_FIELDS The raw figures of a trip