canopen-sim
Simulated CANopen devices that behave: a servo drive that walks through its power
state machine, ramps to a target velocity and can be put into a fault by injecting an over-temperature fault, which you clear
on the control channel and then acknowledge with a fault reset; an I/O module whose inputs follow its outputs or a signal you define; a
multi-turn encoder that counts. They run on a virtual CAN bus (any platform) or on a real
SocketCAN interface such as vcan0 (Linux), and speak NMT with heartbeat, SDO
(expedited, segmented and block), PDOs (event, timer and SYNC driven, with mapping), SYNC
and EMCY. So you can develop and test a CANopen master, a gateway or your own
commissioning scripts without a drive on the bench, also in CI.
The test suite cross-checks the simulator against the independent
canopen Python library, including a full
drive commissioning with its BaseNode402 (enable, run a velocity, fault, reset, run again).
$ canopen-sim serve --profile generic-drive --id 3 --interface socketcan --channel vcan0 &
generic-drive id 3 generic-drive vcan0
control 127.0.0.1:47100
$ canopen-sim state
node id profile nmt_state faults errors
generic-drive 3 generic-drive pre_operational - -
$ canopen-sim inject over_temperature # the drive goes to FAULT and sends EMCY 0x4310
$ canopen-sim clear
Install
Requires Python 3.10 or newer. Runtime dependencies: python-can and PyYAML.
pip install canopen-sim
From source, with the test dependencies (including canopen for the cross-checks):
git clone https://github.com/steitec/canopen-sim
cd canopen-sim
pip install -e '.[dev]'
pytest
Quick start
On Linux, set up a virtual SocketCAN interface once per boot:
sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0
Then serve a device on it and watch the traffic with candump from can-utils:
canopen-sim serve --profile generic-drive --id 3 --interface socketcan --channel vcan0
candump vcan0 # in a second terminal
Without --interface, serve runs on python-can's virtual bus, which exists only
inside one process: candump, another process or another tool cannot see it (serve
prints a note saying so). It is what the pytest fixture and Bench in Python use. To
reach a node from other processes you need --interface socketcan, on Linux. On Windows
and macOS only the virtual bus is available. A bench with several devices
(or a fixed bus) is a YAML file:
# bench.yaml
bus: {interface: socketcan, channel: vcan0}
nodes:
- {profile: generic-drive, id: 3, name: axis, heartbeat_ms: 500}
- {profile: generic-io, id: 5, name: io}
control: {port: 47100} # optional; 127.0.0.1 only
canopen-sim serve --bench bench.yaml
The control channel (default port 47100) is for fault injection and has no authentication. It binds to the loopback interface only; keep it that way.
Test a master with pytest
The package installs a pytest plugin. The canopen_bench fixture starts a bench for each
test on its own virtual channel; remote_node() gives you a node of the canopen library
built from the exported EDS:
import canopen
def test_drive_runs_faults_and_recovers(canopen_bench):
drive = canopen_bench.remote_node("axis", cls=canopen.BaseNode402)
drive.nmt.state = "PRE-OPERATIONAL"
drive.setup_402_state_machine() # reads the PDO layout via SDO
drive.nmt.state = "OPERATIONAL"
...
canopen_bench.inject("over_temperature")
... # wait for drive.state == "FAULT"
assert [error.code for error in drive.emcy.active] == [0x4310]
canopen_bench.clear()
drive.state = "SWITCH ON DISABLED" # fault reset
The complete, runnable version is examples/test_example.py.
Point the fixture at your own bench with --canopen-bench FILE or the ini key
canopen_bench; without either you get one generic-drive on node 1.
canopen_bench_factory starts more benches from a file, a dict or a profile name. The
canopen package is needed only for remote_node() and network().
Faults
Inject a fault at runtime with canopen-sim inject KIND [key=value ...] [--node NAME],
over the control channel, or with bench.inject(...) in Python. clear [KIND] removes
one fault or all. Parameters go as key=value; count=N limits a catalogue fault to N
firings.
Catalogue (every node):
| fault | parameters | effect |
|---|---|---|
mute |
the node sends nothing at all | |
no_heartbeat |
heartbeat frames are suppressed | |
restart |
one-shot: the node resets now (boot-up message follows) | |
double_bootup |
one-shot: the next boot-up message goes out twice | |
sdo_abort |
code (default 0x08000000), index |
requests (to that index) are answered with this SDO abort code |
sdo_delay |
seconds (default 0.5) |
SDO answers come late |
sdo_drop |
a request gets no answer, the server state is unchanged | |
sdo_bad_toggle |
a segment answer has the toggle bit inverted | |
pdo_dropout |
every (default 2), pdo |
every n-th TPDO frame is lost |
pdo_bad_length |
length, pdo |
TPDO frames are truncated |
pdo_freeze |
pdo |
the TPDO keeps the data of the moment of injection |
emcy |
code (default 0xFF00), register (default 0x80), data (hex, up to 5 bytes) |
the node sends this EMCY and keeps it active until cleared |
pdo selects TPDO 1 to 4; without it the fault applies to all.
Drive (generic-drive):
| fault | EMCY code | error register bit | effect |
|---|---|---|---|
over_temperature |
0x4310 | temperature | enters the fault reaction, then FAULT; error code 0x603F set |
over_current |
0x2220 | current | the same |
following_error |
0x8611 | manufacturer-specific | the same; also raised by the model when the following error exceeds 0x6065 |
clear removes the cause and sends EMCY 0x0000; the drive leaves FAULT on the next
rising edge of controlword bit 7, like a real one.
I/O module (generic-io): parameters channel=N (1-based, default 1) and
type=digital|analog.
| fault | EMCY code | effect |
|---|---|---|
wire_break |
0xFF01 (manufacturer-specific) | the input reads 0 |
short_circuit |
0x2320 | a digital input reads 1, an analog input full scale |
over_range |
0x3110 | an analog input reads full scale (type=analog only) |
Encoder (generic-encoder):
| fault | parameters | effect |
|---|---|---|
sensor_error |
the position stops; EMCY 0x5051 (multi-turn) or 0x5050 (single-turn) | |
position_jump |
delta=<units> |
the position jumps once; no EMCY |
freeze |
the position stops; no EMCY |
Profiles
$ canopen-sim list
$ canopen-sim map generic-drive # objects, default PDO mappings, sources and limits
$ canopen-sim export-eds generic-drive --id 3 -o drive.eds
| profile | what it is | device type | default PDOs |
|---|---|---|---|
generic-drive |
servo drive: power state machine, profile velocity, profile position, homing (methods 35 and 37), increments and increments/s; object set as documented in public manufacturer manuals | 0x00020192 | TPDO1 statusword + velocity actual, TPDO2 statusword + position actual; RPDO1 controlword + target velocity, RPDO2 controlword + target position |
generic-io |
8 digital inputs, 8 digital outputs, 2 analog inputs, 2 analog outputs; outputs loop back to the inputs unless a signal or a fault drives them | 0x000F0191 | TPDO1 digital inputs, TPDO2 analog inputs; RPDO1 digital outputs, RPDO2 analog outputs |
generic-encoder |
multi-turn rotary encoder, 4096 steps per revolution, position integrated from a set speed; preset and counting direction | 0x00020196 | TPDO1 position (timer 100 ms and on change), TPDO2 position + speed (every SYNC) |
Each profile names what it follows in sources and states what it does not do in
limits (shown by canopen-sim map):
- generic-io follows CiA 401-1 v3.1.0 (PAS). Limits: only 8-bit digital and 16-bit analog objects, no polarity, filter or interrupt-mask objects (except the analog global interrupt enable below); wire break uses a manufacturer-specific EMCY code because CiA 401 defines none. Analog input interrupt: object 0x6423 (BOOLEAN, rw, PDO-mappable) defaults to FALSE, so changes of the analog inputs do not trigger event-driven TPDOs until a master sets it TRUE (digital inputs are not affected; event timer and SYNC transmissions still work). When the node enters OPERATIONAL while 0x6423 is FALSE it sends the warning EMCY 0x0080 (error register generic bit) and stays OPERATIONAL; the warning is cleared (EMCY 0x0000) on the next model tick after 0x6423 is set TRUE. The event TPDOs sent once on entering OPERATIONAL include the analog values. An NMT reset forgets the warning.
- generic-encoder follows CiA 406 v4.1.0 (PAS) and is modelled as class C1: operating
parameters, resolution, preset, position and speed plus the C1 objects 0x6500 (operating
status, mirrors the code-sequence bit), 0x6501 (single-turn resolution) and 0x6502
(distinguishable revolutions: 65536 for multi-turn, 1 for single-turn, a fixed simulator
value; the position wraps at resolution times 65536, capped at 2^32). No alarms or
warnings objects, no total measuring range (0x6002), no cyclic timer (0x6200), no cams or diagnostics; no
acceleration, jitter or quantisation noise. The speed value 0x6030:1 is in steps per
second (the configured rpm times the resolution divided by 60) and is clamped to
INTEGER16, so fast or high-resolution settings saturate at -32768..32767. The device type
is derived from the model (0x00020196 multi-turn, 0x00010196 single-turn) unless the
profile sets
device_typeexplicitly. - generic-drive follows the CANopen manuals of Kollmorgen (AKD), SEW-EURODRIVE and
Synapticon (SOMANET) as published, not CiA 402 itself (editions listed in
docs/source-check.md). Limits: no load or motor model, the following error is a fixed lag (20 ms times the velocity), no halt bit (controlword bit 8), no cyclic synchronous modes, only homing methods 35 and 37; temperature and current faults are injected, not computed.
Every device has the mandatory communication objects (0x1000 to 0x1018, including
store/restore with the save/load signatures, in memory only) and the vendor ID is 0
unless a profile overrides it. Vendor ID 0 means no assigned CANopen vendor ID, which
CiA 301 treats as invalid; set your own in a profile override if your master needs one.
Describe your own device in a YAML profile (see src/canopen_sim/profiles/ for the
format) and pass it to --profile or a bench.
CLI reference
| command | what it does |
|---|---|
canopen-sim list |
list the bundled profiles |
canopen-sim map PROFILE [--id N] |
objects, default PDO mappings, sources and limits of a profile or YAML file |
canopen-sim export-eds PROFILE [--id N] [-o FILE] |
write the profile's EDS file |
canopen-sim serve (--bench FILE | --profile NAME [--id N]) [--interface socketcan|virtual] [--channel NAME] [--control-port N] |
run a bench until SIGINT/SIGTERM |
canopen-sim inject KIND [key=value ...] [--node NODE] |
inject a fault (see Faults) |
canopen-sim clear [KIND] [--node NODE] |
clear a fault, or all |
canopen-sim state [--json] [--node NODE] |
nodes, NMT states, faults and EMCY codes |
inject, clear and state also take --control-host and --control-port
(default 127.0.0.1:47100). --node is needed when the bench has several nodes. The
control protocol is one JSON object per line over TCP (inject, clear, get, list,
plus a node key); see src/canopen_sim/control.py.
Honest limits
- Not certified. canopen-sim is not certified by CiA and has not passed a conformance test.
- Not tested against real devices. It was cross-checked against the
canopenPython library only, and checked by hand against public specifications and manuals. - A virtual CAN bus is not a CAN bus.
vcanhas no arbitration, no bit errors and no real bus-off; the virtual python-can bus does not either. Timing is not real-time: frames are produced by Python threads every few milliseconds. - The drive follows manufacturer manuals, not CiA 402. Its object set and statusword behaviour come from public manuals of real drives; where they differ from the standard, the manuals won.
- Nodes inside one bench do not receive each other's frames: the bench has one bus handle
and no internal loopback. Use a separate bus handle (
bench.network(), another process on socketcan, or a real master) to talk to a node. - The drive's following error is a fixed-lag model, and the halt bit (controlword bit 8) is not implemented. Statusword bit 4 (voltage enabled) is not reported.
- The I/O wire-break fault uses the manufacturer-specific EMCY code 0xFF01; CiA 401 defines none.
- EDS export is checked by importing it with the
canopenPython library, not against CiA 306. - The control channel has no authentication. It binds to the loopback interface; do not expose it.
- J1939, CANopen FD, LSS, node guarding and CiA 302 (network management) are out of scope.
Trademarks and licence
CANopen® and CiA® are registered trademarks of CAN in Automation (CiA) e.V. This project is not certified by or affiliated with CiA.
MIT, see LICENSE. python-can is licensed LGPL-3.0 and stays a separate package
that canopen-sim imports; it is not bundled or modified here.
Metadata
Release files for canopen-sim 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| canopen_sim-0.1.0.tar.gz | 89.7 kB | With provenance | Details for canopen_sim-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| canopen_sim-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for canopen_sim-0.1.0-py3-none-any.whl |
Total release size: 154.6 kB
Release files / canopen_sim-0.1.0.tar.gz
| Download URL | canopen_sim-0.1.0.tar.gz |
|---|---|
| Size | 89.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5abd51c2b1f097634e3d38f2045491559fd24df5e7d96204089c52ae50041b40
|
|
BLAKE2b-256 checksum How to use checksums |
0e98a0e0068a09147f8456a8d195588bb7cf610e287473dff2c9288f8c723ade
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / canopen_sim-0.1.0-py3-none-any.whl
| Download URL | canopen_sim-0.1.0-py3-none-any.whl |
|---|---|
| Size | 64.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3332d37d696fa448481d9a3301354bed46ed01dd84454d3494caa062792094eb
|
|
BLAKE2b-256 checksum How to use checksums |
542d7c96f87a70d0e8398d3203a48ebacb47efb343c0cb5088beba23e102ecb9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for canopen-sim 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for canopen_sim-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.