MojoScale Studio Docs
API Reference

j1939

SAE J1939 engine-network access over ESP32 TWAI/CAN.

All modules Open Studio
Studio Docs Buses & Protocols

import j1939

The j1939 module reads vehicle, genset, and heavy-equipment signals from a J1939 CAN bus. It decodes common engine signals such as engine speed, coolant temperature, oil pressure, battery voltage, fuel rate, engine hours, and active faults. ESP32 and ESP32-S3 provide the TWAI controller used by this module. A physical CAN transceiver is still required between the ESP32 TX/RX pins and CANH/CANL.

Quick example

import j1939

network = j1939.Network(tx=5, rx=4, bitrate=250000, mode="listen_only")
network.watch(["engine_speed", "coolant_temperature", "oil_pressure"])

def on_update(signal):
    print(signal["name"], signal["value"], signal["unit"])

network.on_signal(on_update)
network.start()

print(network.value("engine_speed"))

importj1939

SAE J1939 engine-network access over ESP32 TWAI/CAN.

The j1939 module reads vehicle, genset, and heavy-equipment signals from a J1939 CAN bus. It decodes common engine signals such as engine speed, coolant temperature, oil pressure, battery voltage, fuel rate, engine hours, and active faults. ESP32 and ESP32-S3 provide the TWAI controller used by this module. A physical CAN transceiver is still required between the ESP32 TX/RX pins and CANH/CANL.

API 35 available

j1939.Network(tx: int, rx: int, bitrate: int = None, mode: str = None, address: int = None, auto_recover: bool = None, rx_queue: int = None, tx_queue: int = None) -> j1939_network

Create a J1939 network object.

Use this object to start TWAI/CAN reception, watch decoded signals, receive signal callbacks, inspect PGNs, request PGNs, and inspect active DM1 faults. Use ``mode="listen_only"`` for passive monitoring. Use ``mode="normal"`` with ``address`` when the device needs to transmit requests.

Parameters
Name Type Pass as Required Description
tx int positional or keyword Yes ESP32 TWAI transmit GPIO connected to the CAN transceiver TXD pin.
rx int positional or keyword Yes ESP32 TWAI receive GPIO connected to the CAN transceiver RXD pin.
bitrate int positional or keyword No Optional CAN bitrate in bits per second. J1939 commonly uses 250000. Some systems use 500000.
mode str positional or keyword No Optional controller mode. Use "normal", "listen_only", or "no_ack".
address int positional or keyword No Optional local J1939 source address used when transmitting request messages.
auto_recover bool positional or keyword No Optional bool. Automatically initiate TWAI recovery after bus-off.
rx_queue int positional or keyword No Optional receive queue depth for incoming CAN frames.
tx_queue int positional or keyword No Optional transmit queue depth for outgoing CAN frames.
Returns

j1939_network j1939_network object.

j1939.Network().start() -> bool

Start the TWAI controller and begin processing J1939 frames.

j1939.Network().stop() -> bool

Stop reception/transmission and uninstall the TWAI driver.

j1939.Network().restart() -> bool

Stop and start again with the same configuration.

j1939.Network().recover() -> bool

Start TWAI recovery after bus-off.

j1939.Network().watch(signal_or_list, source=None) -> bool

Decode one signal or a list of signal names. Optional source filters to one ECU address.

Parameters
Name Type Pass as Required Description
signal_or_list any positional or keyword Yes Required value.
source int positional or keyword No Optional value. Defaults to None.

j1939.Network().unwatch(signal_or_list) -> bool

Stop decoding one signal or a list of signal names.

Parameters
Name Type Pass as Required Description
signal_or_list any positional or keyword Yes Required value.

j1939.Network().watch_all() -> bool

Decode every built-in and custom signal definition.

j1939.Network().on_signal(callback) -> bool

Register a callback for every watched signal update. Callback receives a dict.

Parameters
Name Type Pass as Required Description
callback callback positional or keyword Yes Required value.

j1939.Network().on(signal, callback, source=None) -> bool

Register a callback for one signal. This also watches the signal.

Parameters
Name Type Pass as Required Description
signal any positional or keyword Yes Required value.
callback callback positional or keyword Yes Required value.
source int positional or keyword No Optional value. Defaults to None.

j1939.Network().value(signal, source=None) -> any

Return the latest value for a signal, or None when not yet received.

Parameters
Name Type Pass as Required Description
signal any positional or keyword Yes Required value.
source int positional or keyword No Optional value. Defaults to None.

j1939.Network().signal(signal, source=None) -> dict

Return the latest full signal dict with name, value, raw, unit, pgn, spn, source, timestamp, age_ms, and valid.

Parameters
Name Type Pass as Required Description
signal any positional or keyword Yes Required value.
source int positional or keyword No Optional value. Defaults to None.

j1939.Network().values(source=None) -> dict

Return latest values for watched signals.

Parameters
Name Type Pass as Required Description
source int positional or keyword No Optional value. Defaults to None.

j1939.Network().define(name, pgn, start_bit, bit_length, byte_order="little", signed=False, scale=1, offset=0, unit="", spn=None, minimum=None, maximum=None, unavailable=None, error=None, replace=False) -> bool

Add a custom bit-positioned signal definition.

Parameters
Name Type Pass as Required Description
name str positional or keyword Yes Required value.
pgn int positional or keyword Yes Required value.
start_bit int positional or keyword Yes Required value.
bit_length int positional or keyword Yes Required value.
byte_order any positional or keyword No Optional value. Defaults to "little".
signed bool positional or keyword No Optional value. Defaults to False.
scale float positional or keyword No Optional value. Defaults to 1.
offset float positional or keyword No Optional value. Defaults to 0.
unit str positional or keyword No Optional value. Defaults to "".
spn int positional or keyword No Optional value. Defaults to None.
minimum any positional or keyword No Optional value. Defaults to None.
maximum any positional or keyword No Optional value. Defaults to None.
unavailable any positional or keyword No Optional value. Defaults to None.
error any positional or keyword No Optional value. Defaults to None.
replace bool positional or keyword No Optional value. Defaults to False.

j1939.Network().define_bytes(name, pgn, start_byte, byte_length, byte_order="little", signed=False, scale=1, offset=0, unit="", spn=None, minimum=None, maximum=None, unavailable=None, error=None, replace=False) -> bool

Add a byte-aligned custom signal definition. start_byte is one-based.

Parameters
Name Type Pass as Required Description
name str positional or keyword Yes Required value.
pgn int positional or keyword Yes Required value.
start_byte int positional or keyword Yes Required value.
byte_length int positional or keyword Yes Required value.
byte_order any positional or keyword No Optional value. Defaults to "little".
signed bool positional or keyword No Optional value. Defaults to False.
scale float positional or keyword No Optional value. Defaults to 1.
offset float positional or keyword No Optional value. Defaults to 0.
unit str positional or keyword No Optional value. Defaults to "".
spn int positional or keyword No Optional value. Defaults to None.
minimum any positional or keyword No Optional value. Defaults to None.
maximum any positional or keyword No Optional value. Defaults to None.
unavailable any positional or keyword No Optional value. Defaults to None.
error any positional or keyword No Optional value. Defaults to None.
replace bool positional or keyword No Optional value. Defaults to False.

j1939.Network().undefine(name) -> bool

Remove a custom signal definition. Built-in definitions are not removed.

Parameters
Name Type Pass as Required Description
name str positional or keyword Yes Required value.

j1939.Network().definition(name) -> dict

Return one signal definition.

Parameters
Name Type Pass as Required Description
name str positional or keyword Yes Required value.

j1939.Network().definitions() -> list

Return all built-in and custom signal definitions.

j1939.Network().available() -> list

Return signal names that have been observed on the bus.

j1939.Network().on_pgn(pgn, callback) -> bool

Register a callback for a completed PGN payload. Callback receives a message dict.

Parameters
Name Type Pass as Required Description
pgn int positional or keyword Yes Required value.
callback callback positional or keyword Yes Required value.

j1939.Network().on_message(callback) -> bool

Register a callback for every completed J1939 message.

Parameters
Name Type Pass as Required Description
callback callback positional or keyword Yes Required value.

j1939.Network().request(pgn_or_name, destination=0xff) -> bool

Send Request PGN 59904 for a PGN number or signal name.

Parameters
Name Type Pass as Required Description
pgn_or_name str positional or keyword Yes Required value.
destination int positional or keyword No Optional value. Defaults to 0xff.

j1939.Network().request_periodically(pgn_or_name, interval=60000, destination=0x00) -> bool

Repeatedly request a PGN.

Parameters
Name Type Pass as Required Description
pgn_or_name str positional or keyword Yes Required value.
interval int positional or keyword No Optional value. Defaults to 60000.
destination int positional or keyword No Optional value. Defaults to 0x00.

j1939.Network().cancel_request(pgn_or_name) -> bool

Cancel periodic requests for a PGN number or signal name.

Parameters
Name Type Pass as Required Description
pgn_or_name str positional or keyword Yes Required value.

j1939.Network().on_fault(callback) -> bool

Register a DM1 active-fault callback. Callback receives a fault dict.

Parameters
Name Type Pass as Required Description
callback callback positional or keyword Yes Required value.

j1939.Network().active_faults(source=None) -> list

Return current active fault dicts.

Parameters
Name Type Pass as Required Description
source int positional or keyword No Optional value. Defaults to None.

j1939.Network().request_previous_faults(destination=0x00) -> bool

Request DM2 previously active faults.

Parameters
Name Type Pass as Required Description
destination int positional or keyword No Optional value. Defaults to 0x00.

j1939.Network().sources() -> list

Return observed J1939 source addresses.

j1939.Network().on_source(callback) -> bool

Register a callback for newly observed source addresses.

Parameters
Name Type Pass as Required Description
callback callback positional or keyword Yes Required value.

j1939.Network().state() -> str

Return stopped, running, bus_off, or recovering.

j1939.Network().stats() -> dict

Return frame/message counters and TWAI error counters.

j1939.Network().on_error(callback) -> bool

Register runtime error callback. Callback receives a dict with code and message.

Parameters
Name Type Pass as Required Description
callback callback positional or keyword Yes Required value.

j1939.Network().clear() -> bool

Clear cached signal values, observed signals, faults, and transport state.

j1939.Network().flush() -> bool

Clear pending TWAI receive frames.

j1939.Network().info() -> dict

Return configuration and runtime summary.