Scripting API

Simulation scripts import their API from can_explorer.scripting:

from can_explorer.scripting import Node, on_message, on_signal, on_start, on_stop, on_variable

See Simulation and scripting for how scripts are loaded and run.

Nodes

Node()

Base class of simulated bus nodes. Subclass it in a simulation script.

Attributes available in handlers: name, variables (shared with other nodes and panels) and time (seconds since the simulation started).

name = '' class-attribute instance-attribute

variables property

Shared variables (Variables) of the simulation, also visible to the other nodes and to panels.

time property

Seconds since the simulation started.

message(name, bus=None)

Create a buffer with the signals of a database message, to fill and send.

Parameters:

Name	Type	Description	Default
name	str	Message (or LIN frame) name in the loaded signal database.	required
bus	Optional[str]	Name of another connection whose database defines the message.	None

Raises:

Type	Description
ScriptError	No database is loaded, or it has no such message.

send(message, data=None, *, extended=None, fd=False, remote=False, bus=None, **signals)

Send a frame.

Examples:

self.send(buffer)                          # A MessageBuffer from message()
self.send('EngineData', EngineSpeed=1000)  # Other signals use their initial value
self.send(0x123, b'\x01\x02')              # Raw data
self.send(0x10, remote=True)               # Remote frame (a header on LIN)

Parameters:

Name	Type	Description	Default
message	MessageBuffer | str | int	A MessageBuffer, a database message name or a frame identifier.	required
data	bytes | Iterable[int] | None	Raw data bytes when message is an identifier.	None
extended	Optional[bool]	Extended identifier; defaults to identifiers above 0x7FF.	None
fd	bool	Send a CAN FD frame (with bitrate switch).	False
remote	bool	Send a remote frame.	False
bus	Optional[str]	Name of another connection to send on (e.g. the other side of a gateway); by default the simulation's own connection. Message names are looked up in that connection's database.	None
**signals	Any	Signal values when message is a database message name.	{}

Raises:

Type	Description
ScriptError	The simulation is not running, the message is unknown or cannot be encoded, or the frame cannot be sent.

every(period, callback, *args)

Call callback(*args) periodically until the simulation stops or the timer is cancelled.

Parameters:

Name	Type	Description	Default
period	float	Period in seconds. The schedule does not drift.	required
callback	Handler	Function or method to call.	required
*args	Any	Arguments passed to the callback.	()

after(delay, callback, *args)

Call callback(*args) once.

Parameters:

Name	Type	Description	Default
delay	float	Delay in seconds.	required
callback	Handler	Function or method to call.	required
*args	Any	Arguments passed to the callback.	()

log(*values)

Write the values, separated by spaces, to the simulation console.

Gateway()

Bases: Node

Forwards frames received on one bus to another, like a gateway ECU between two networks.

Subclass it and set the class attributes:

class BodyGateway(Gateway):
    source = 'Powertrain'        # Connection names; '' is the simulation's own connection
    target = 'Body'
    ids = [0x100, 'VehicleSpeed']  # Identifiers or database names of the source bus; None: all frames
    both_directions = False      # Also forward frames of `ids` from the target to the source

Only received frames are forwarded, so frames sent by the gateway itself (or any other node) never loop. Override transform(msg, to_bus) to change frames on the way (e.g. another identifier) or to drop them (return None).

source = '' class-attribute instance-attribute

target = '' class-attribute instance-attribute

ids = None class-attribute instance-attribute

both_directions = False class-attribute instance-attribute

transform(msg, to_bus)

The frame to send on to_bus; by default an unchanged copy of the received frame.

Handler decorators

on_start(function)

Called when the simulation starts.

on_stop(function)

Called when the simulation stops.

on_message(*selectors, bus=None)

Called with a ReceivedMessage for frames with the given identifiers or database message names.

Without selectors the handler receives every frame. A node does not receive the frames it sends itself. bus is the name of another connection to receive its frames (decoded with its database); by default the frames of the simulation's own connection.

on_signal(message, signal, bus=None)

Called with (value, message) when the decoded value of a signal changes (and when first received).

bus is the name of another connection, as for on_message.

on_variable(name)

Called with the new value when a shared variable changes (set by a node or a panel).

Messages

ReceivedMessage(msg, runtime, bus=None)

A frame delivered to a node. signals decodes it with the signal database on first access.

name property

Message name from the signal database, None when unknown.

signals property

Physical signal values (numbers; use labels for the text of value tables).

labels property

Signal values with value table texts where defined.

MessageBuffer(definition, frame_id, extended, fd)

Signal values of a database message, sent with Node.send(). Missing values start at their initial value.

Signals are accessed as items (buffer['EngineSpeed']) or attributes (buffer.EngineSpeed).

signal_names property

update(values=None, **signals)

encode()

Timers, variables and errors

Timer(node, period, callback, args, repeat)

A one-shot or periodic timer created with Node.after() or Node.every().

running property

cancel()

Variables(on_change)

Shared variables of a simulation (like CANoe system variables): set by nodes, panels or the user.

get(name, default=None)

Value of a variable, or default when it was never set.

set(name, value)

Set a variable; @on_variable handlers and panels are notified when the value changes.

ScriptError

Bases: Exception

Errors caused by a script, e.g. sending an unknown message.