Device profiles

On top of the standard CANopen functionality which includes the DS301 application layer there can be additional profiles specifically for certain applications.

CiA 402 CANopen device profile for motion controllers and drives

This device profile has a control state machine for controlling the behaviour of the drive. Therefore one needs to instantiate a node with the BaseNode402 class

Create a node with BaseNode402:

import canopen
from canopen.profiles.p402 import BaseNode402

some_node = BaseNode402(3, 'someprofile.eds')
network = canopen.Network()
network.add_node(some_node)

The Power State Machine

The PowerStateMachine class provides the means of controlling the states of this state machine. The static method on_PDO1_callback() is added to the TPDO1 callback.

State changes can be controlled by writing a specific value to register 0x6040, which is called the “Controlword”. The current status can be read from the device by reading the register 0x6041, which is called the “Statusword”. Changes in state can only be done in the ‘OPERATIONAL’ state of the NmtMaster

PDOs with the Controlword and Statusword mapped need to be set up correctly, which is the default configuration of most DS402-compatible drives. To make them accessible to the state machine implementation, run the the BaseNode402.setup_402_state_machine() method. Note that this setup routine will read the current PDO configuration by default, causing some SDO traffic. That works only in the ‘OPERATIONAL’ or ‘PRE-OPERATIONAL’ states of the NmtMaster:

# run the setup routine for TPDO1 and it's callback
some_node.setup_402_state_machine()

Write Controlword and read Statusword:

# command to go to 'READY TO SWITCH ON' from 'NOT READY TO SWITCH ON' or 'SWITCHED ON'
some_node.sdo[0x6040].raw = 0x06

# Read the state of the Statusword
some_node.sdo[0x6041].raw

During operation the state can change to states which cannot be commanded by the Controlword, for example a ‘FAULT’ state. Therefore the BaseNode402 class (in similarity to NmtMaster) automatically monitors state changes of the Statusword which is sent by TPDO. The available callback on that TPDO will then extract the information and mirror the state change in the BaseNode402.state attribute.

Similar to the NmtMaster class, the states of the BaseNode402 class state attribute can be read and set (command) by a string:

# command a state (an SDO message will be called)
some_node.state = 'SWITCHED ON'
# read the current state
some_node.state

Available states:

  • ‘NOT READY TO SWITCH ON’

  • ‘SWITCH ON DISABLED’

  • ‘READY TO SWITCH ON’

  • ‘SWITCHED ON’

  • ‘OPERATION ENABLED’

  • ‘FAULT’

  • ‘FAULT REACTION ACTIVE’

  • ‘QUICK STOP ACTIVE’

Available commands

  • ‘SWITCH ON DISABLED’

  • ‘DISABLE VOLTAGE’

  • ‘READY TO SWITCH ON’

  • ‘SWITCHED ON’

  • ‘OPERATION ENABLED’

  • ‘QUICK STOP ACTIVE’

API

class canopen.profiles.p402.BaseNode402(node_id, object_dictionary)[source]

A CANopen CiA 402 profile slave node.

Parameters:
  • node_id (int) – Node ID (set to None or 0 if specified by object dictionary)

  • object_dictionary (str, canopen.ObjectDictionary) – Object dictionary as either a path to a file, an ObjectDictionary or a file like object.

check_statusword(timeout=None)[source]

Report an up-to-date reading of the Statusword (0x6041) from the device.

If the TPDO with the Statusword is configured as periodic, this method blocks until one was received. Otherwise, it uses the SDO fallback of the statusword property.

Parameters:

timeout – Maximum time in seconds to wait for TPDO reception.

Raises:

RuntimeError – Occurs when the given timeout expires without a TPDO.

Returns:

Updated value of the statusword property.

Return type:

int

property controlword

Send a state change command using PDO or SDO.

Parameters:

value (int) – Controlword value to set.

Raises:

RuntimeError – Read access to the controlword is not intended.

homing(timeout=None, restore_op_mode=False)[source]

Execute the configured Homing method on the node.

Parameters:
  • timeout (int) – Timeout value (default: 30, zero to disable).

  • restore_op_mode (bool) – Switch back to the previous operation mode after homing (default: no).

Returns:

If the homing was complete with success.

Return type:

bool

is_homed(restore_op_mode=False)[source]

Switch to homing mode and determine its status.

Parameters:

restore_op_mode (bool) – Switch back to the previous operation mode when done.

Returns:

If the status indicates successful homing.

Return type:

bool

is_op_mode_supported(mode)[source]

Check if the operation mode is supported by the node.

The object listing the supported modes is retrieved once using SDO, then cached for later checks.

Parameters:

mode (str) – Same format as the op_mode property.

Returns:

If the operation mode is supported.

Return type:

bool

on_TPDOs_update_callback(mapobject)[source]

Cache updated values from a TPDO received from this node.

Parameters:

mapobject (canopen.pdo.Map) – The received PDO message.

property op_mode

The node’s Operation Mode stored in the object 0x6061.

Uses SDO or PDO to access the current value. The modes are passed as one of the following strings:

  • ‘NO MODE’

  • ‘PROFILED POSITION’

  • ‘VELOCITY’

  • ‘PROFILED VELOCITY’

  • ‘PROFILED TORQUE’

  • ‘HOMING’

  • ‘INTERPOLATED POSITION’

  • ‘CYCLIC SYNCHRONOUS POSITION’

  • ‘CYCLIC SYNCHRONOUS VELOCITY’

  • ‘CYCLIC SYNCHRONOUS TORQUE’

  • ‘OPEN LOOP SCALAR MODE’

  • ‘OPEN LOOP VECTOR MODE’

Raises:
  • TypeError – When setting a mode not advertised as supported by the node.

  • RuntimeError – If the switch is not confirmed within the configured timeout.

reset_from_fault()[source]

Reset node from fault and set it to Operation Enable state.

setup_402_state_machine(read_pdos=True)[source]

Configure the state machine by searching for a TPDO that has the StatusWord mapped.

Parameters:

read_pdos (bool) – Upload current PDO configuration from node.

Raises:

ValueError – If the the node can’t find a Statusword configured in any of the TPDOs.

setup_pdos(upload=True)[source]

Find the relevant PDO configuration to handle the state machine.

Parameters:

upload (bool) – Retrieve up-to-date configuration via SDO. If False, the node’s mappings must already be configured in the object, matching the drive’s settings.

Raises:

AssertionError – When the node’s NMT state disallows SDOs for reading the PDO configuration.

property state

Manipulate current state of the DS402 State Machine on the node.

Uses the last received Statusword value for read access, and manipulates the controlword for changing states. The states are passed as one of the following strings:

  • ‘NOT READY TO SWITCH ON’ (cannot be switched to deliberately)

  • ‘SWITCH ON DISABLED’

  • ‘READY TO SWITCH ON’

  • ‘SWITCHED ON’

  • ‘OPERATION ENABLED’

  • ‘FAULT’ (cannot be switched to deliberately)

  • ‘FAULT REACTION ACTIVE’ (cannot be switched to deliberately)

  • ‘QUICK STOP ACTIVE’

  • ‘DISABLE VOLTAGE’ (only as a command when writing)

Raises:
  • RuntimeError – If the switch is not confirmed within the configured timeout.

  • ValueError – Trying to execute a illegal transition in the state machine.

property statusword

Return the last read value of the Statusword (0x6041) from the device.

If the object 0x6041 is not configured in any TPDO it will fall back to the SDO mechanism and try to get the value.