Woops. Looks like this page doesn't exist ¯\_(ツ)_/¯.
Go to homepage
Built with from Grav and Hugo
A configuration framework for ECMC Motion Control Module for EPICS.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -10,4 +10,4 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, -Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
check the module loads for version dev, Epics R7+ and ECMC version dev, note MASTER_ID=-1 which runs ECMC in master-less mode. Make proper adjustments to match your needs in terms of versions.
dev
R7+
MASTER_ID=-1
iocsh -7 -r "ecmccfg,dev 'ECMC_VER=dev,MASTER_ID=-1'"
The variable “ECMC_CONFIG_RETURN_VAL” then can be used to set record fields, name or alias for instance..
In DAQ mode, motion functionalities are disabled and the following commands are blocked:
This mode is intended to be used for pure DAQ use cases.
Example of starting ecmc in DAQ mode:
$(ECMCCFG_INIT)$(SCRIPTEXEC) ${ecmccfg_DIR}startup.cmd, "IOC=$(IOC),ECMC_VER=develop,MODE=DAQ"
NOTE: The default record update rate is set to 10ms in initAlll.cmd. For DAQ applications it could be needed to change this parameter to update records faster by changing the ECMC_SAMPLE_RATE_MS variable:
epicsEnvSet("ECMC_SAMPLE_RATE_MS",1)
In this mode all features are supported, but motor record will not be created for motion axes.
Setting the parameter ENG_MODE=1 will result in loading of extra PVs usefull for commissioning, i.e. controller parameters for motion axes.
file
code
${SCRIPTEXEC} "${ECMC_CONFIG_ROOT}loadYamlPlc.cmd" "FILE=./plc1File.yaml, ECMC_TMPDIR=/tmp/"
${SCRIPTEXEC} ${ecmccfg_DIR}setAppMode.cmd
${SCRIPTEXEC} ${ecmccfg_DIR}loadYamlPlc.cmd "FILE=./plc1File.yaml"
This is the respective plc file
ax${AXIS_NO}.enc.actpos:=(ax{{ var.ty1 }}.enc.actpos+ax{{ var.ty2 }}.enc.actpos)/2;
Note the mixed use to MACROs ${AXIS_NO} and local variables {{ var.ty1 }} to boost flexibility.
${AXIS_NO}
{{ var.ty1 }}
Always verify where the switches are connected in the electrical drawings.
All switches in the “input” section needs to be linked. If not used, then the simulation registers, “ONE” and “ZERO”, can be used:
Example, Use bit 1 in the ONE register of slave 1:
ec0.s1.ONE.1
If no ethercat slave is defined, slave number “-1” can be used: ec<master_id>.s-1.ONE.
This will affect the motorRecord only, thus ECMC internally is still moving in the wrong direction. You have been warned!
From v8+ yaml files are linted for syntactic errors, observe the iocsh for warnings and errors. Additionally the schema of the yaml file is checked by Cerberus. This check will point out errors in the structure of the configuration as well as certain type errors.
Syncronization configurations
Configuration of scaling
Defining the direction of motion
Configuration of homing
numerator
type: 0
uint16
bits: 16
The resulting code will toggle two different outputs, the state of the last output will be printed.
NOTE: Macros cannot be used in the filename when including a file. Instead the dir should be defined in the INC param when loading the PLC, see above.
Adding a DBG macro can be usefull to be able to turn on/off printouts. Typically during commsioning it can be usefull to have many printouts but later when system goes into production, it could be a good idea to turn (some) printouts off.
Example of a printout that can be turned on/off (default off)
${DBG=#}println('Value: ', ${M}.s${BO_S_ID}.binaryOutput${BO_CH});
Will result in the below if setting the DBG='' (and some other macros, see above):
println('Value: ', ec0.s10.binaryOutput01);
Unfortunately debugging of function libs is not as easy as normal PLC:s since exprtk returns less infomation at compile failure.
In order to troubleshoot, load the code as a normal PLC instead. This way you will get more diagnostics. Also remember, ecmc varaibles cannot be accessed in plc libs.
iocsh call
iocsh
ethercat download
With this command the value of a register can be set on the slave.
If the type is not explicitly given, first issue ethercat -p <slaveID> sdos. This will allow implicit type handling.
type
ethercat -p <slaveID> sdos
Example: Set value of register 0x8010, sub-register 0x07 from slave 7 to 314.
0x8010
0x07
7
314
ethercat download -m0 -p7 0x8010 0x07 314
ethercat states
With this command a specific state of a slave can be forced, or at least an attempt to enter the specific state is made.
This is helpful when a slave is stuck, e.g. with an error. Rather than cycle the power of the entire controller, the slave can be set to ‘REBOOT’. This might be enough to recover.
Alternatively, cycling to ‘INIT’ and back to ‘OP’ might also be attempted.
A power cycling of the of the EtherCAT components is the last resort!
Remember, red is not necessarily a bad sign! It can also indicate that certain channels are not connected. Whether those channels should be connected is beyond the scope of this guide.
red
Next step is to diagnose from a dedicated shell, or from within the iocsh.
If all slaves are in ‘OP’ state, at least data is exchanged between the hardware and the master.
Blindly restarting the IOC, with only partially working EtherCAT hardware, WILL RESULT IN TOTAL FAILURE OF THE IOC!!!
Check the hardware BEFORE restarting the IOC!
The status bits can then be masked away by:
Also see troubleshooting/tuning section.
In the standard setup at PSI over current protection modules are used to feed 24V to both the ethercat communication bus (E-bus) and the power bus of the ethercat slaves. If the over current protection is not enabled then the ethercat slaves will not receive power.
First time, (and only first time), a system is in use, the overcurrent modules needs to be enabled in order to allow current to flow. Enabling is done by push buttons in the LED area of the module. The long horizontal LEDs are in fact buttons that can be used to activate or tripp the over current protection.
Before pressing the buttons, check the electrical drawings. Make sure it’s safe to power on the system.
The EL9221-5000 has one channel and therefore only the top button is needed to be pressed.
The EL9227-5500 is a 2 channel module and normally both channels needs to be enabled by pressing both the top and bottom long LED. if only one are pressed it could result in that the power to the communication is fine but the power to the i/o bus is lacking. This can result in starnge issues. Both EL9227-5500 and EL9221-5000 have dedicated panels whre status of the over current protection can be seen.
If more than one ecmc ioc is running on the server, then make sure the ecmc_rt threads run on differnt cores.
Also other threads might take a lot of resources, for instace the epics thread “cbLow”:
afterInit "epicsThreadSetAffinity cbLow 6"
cbLow is created at iocInit, therefore the “epicsThreadSetAffinity” must be executed with the “afterInit” command.
Due to the complexity an EtherCAT bus topology can assume, troubleshooting can be challenging. This guide should provide the basic means to diagnose simple errors and is by no means complete!
For general issues, a very short troubleshooting guide is provided here.
A very powerful tool is provided through the command line. See a summary, incl. some examples of what possible here.
For motion related issues, a very short troubleshooting guide is provided here.
Tune drive control loops
For hardware related issues, a very short troubleshooting guide is provided here.
Trigger manual motion (without motion ecmc-axis).
This procedure is for experts only. You run the risk of destroying expansive devices! Limit switches are not obeyed! YOU HAVE BEEN WARNED!
For this however, the IOC needs to be reconfigured to not link the hardware to an axis!
dbgrep "*s007*"
-Drv01-Cmd
-Drv01-Spd
1
After changing this value you also need to change the drive scaling in the axis yaml file.
First check the dedicated hardware drive panel for diagnostics. If the drive is in warning or error state the diagnose the problem with the tool described in hardware.
Possible reasons:
Tuning systems with backlash can be difficult. Sometimes a small D-part helps to reduce spikes in the centralized ecmc position loop controller output.
Validates requested oversampling factor
Checks if requested oversampling factor is valid otherwise exits EPICS/ECMC
Anders Sandstroem
Validates the resulting sampling time for oversampling slaves.
Checks if the resulting sampling time for oversampling slaves is higher or equal to the minimum time.
Validates current settings
Checks if requested run current and standby current is less than max current and larger than 0.
Validates requested voltage
Ensure requested nominal voltage is less than max voltage and larger than 0
Add general PVs
Script for adding general and master diagnostics EPICS PVs
Niko Kivel, Anders Sandstroem
Script for general diagnostics
Script for setting default diagnostics
Initialization script
Script for setting up the basic EPICS environment.
Init main script
init axis environment
Script for setting up the basic AXIS environment.
Issue a warning
Generic verification script for expressions
Generic verification script
Script for adding axis related EPICS PVs.
Adds motorRecord to the IOC.
This script is typically called by \b addAxis.cmd
Script for configuring a physical axis.
Configures a physical axis in ECMC, based on previously set environment variables.
This script is typically called by \b addAxis.cmd, often via \b ecmc_axis-records.cmd
Script for adding axis diagnostic EPICS PVs.
Adds diagnostic PVs to the IOC.
Script for loading motor record related databases
Script for loading motor record related databases and creating motor record axis object
This script is typically called by \b ecmc_axis.cmd, often via \b ecmc_axis-records.cmd
Script for configuring axis synchronization
Configures ECMC for axis synchronization, based on previously set environment variables.
This script is typically called by \b applyAxisSynchronization.cmd
Script for adding encoder related EPICS PVs.
Script for adding an encoder to a previously created axis.
Script for adding an extra encoder
Configures a encoder object in ECMC, based on previously set environment variables.
This script is typically called by \b addEncoder.cmd
This script is typically called by \b addVirtualAxis.cmd
Script for configuring a virtual axis.
Configures a virtual axis in ECMC, based on previously set environment variables.
This script is typically called by \b addVirtualAxis.cmd, often via \b ecmc_virt_axis-records.cmd
Script for defining ${ECMC_PREFIX}
Gathers relevant information about MasterID, SlaveID, … to create naming convention compliant PREFIX
Niko Kivel
Script for defining ${ECMC_P}
Script for adding axis EPICS PVs.
Adds an motion axis.
Script for adding dataStorage.
Adds dataStorage buffer.
DS_SIZE Size of data buffer.DS_ID (optional), default 0, buffer IDDS_TYPE (optional), default 0, 0: Normal Buffer, 1: Ring Buffer, 2: FIFO BufferSAMPLE_RATE_MS (optional), default 1DS_DEBUG (optional), default 0, 0: No debug printouts, 1: Debug printouts
Example calls:
${SCRIPTEXEC} ${ecmccfg_DIR}addDataStorage.cmd "DS_ID=1, DS_SIZE=1000, SAMPLE_RATE_MS=100"
Script for adding an EtherCAT domain.
Adds an EtherCAt domain.
Anders Sandström
EXE_RATE (optional) Execution rate [cycles] defaults 0 (same EC_RATE)EXE_OFFSET (optional) Execution offset cycles [cycles] defaults 0ALLOW_OFFLINE (optional) Allow domain to be offline defaults 0
All EtherCAT entries generated after this command will be assigned
Script for adding a ethercat data item.
The ethercat data item allows for accessing alreday configured ethercat domain data in a flexible
Script for adding asyn SDO object (access to SDO:s in realtime)
Add SDO for async access during realtime operation
Script for adding an extra encoder to an axis.
Adds an encoder to the last configured axis.
CONFIG configuration file, i.e. ./cfg/axis_1_enc_2.encDEV (optional) device name, i.e. MOTOR1CLEAR_VARS_CMD (optional) Set to “empty” for not clear env vars (if vars needed for later use).CFG_MACROS (optional) Substitution macros for config file
Example call:
${SCRIPTEXEC} ${ecmccfg_DIR}addEncoder.cmd, "CONFIG=./cfg/linear_1_enc_3.enc"
Script for claiming a particular master.
Claims an EtherCAT master.
MASTER_ID (optional) master ID as shown by ethercat master.
ethercat master
${SCRIPTEXEC} ${ecmccfg_DIR}addMaster.cmd
${SCRIPTEXEC} ${ecmccfg_DIR}addMaster.cmd, "MASTER_ID=3"
${SCRIPTEXEC} ${ecmccfg_DIR}addSlave.cmd, "HW_DESC=EL1018, SLAVE_ID=1, P_SCRIPT=mXsXXX"
${SCRIPTEXEC} ${ecmccfg_DIR}addSlave.cmd, "HW_DESC=EL3204, DEFAULT_SUBS=false, DEFAULT_SLAVE_PVS=true"
Script for adding a KL slave to the EtherCAT bus configuration of KL type.
Adds the respective hardware to the bus configuration, adds specific and default PV to the EPICS database. For some/most slaves also a default
Anders Sandstrom
HW_DESC Hardware descriptor, i.e. KL2032SLAVE_ID EtherCAT bus position of the BK1250 (or similar terminal)SLAVE_ID_KL KL-Bus index in two digit hex starting at zero for the first slave after BK1250 (or similar terminal)SUBST_FILE (optional) substitution file
${SCRIPTEXEC} ${ecmccfg_DIR}addSlave.cmd, "HW_DESC=EL1018, SLAVE_ID=1, SLAVE_ID_KL=0A"
Adds an virtual axis with PVs.
Script for applying axis synchronization
Adds synchronization parameters to an axis provided by CONFIG.
CONFIG configuration file, i.e. ./cfg/linear_1.saxCLEAR_VARS_CMD (optional) Set to “empty” for not clear env vars (if needed vars for later use).
${SCRIPTEXEC} ${ecmccfg_DIR}applyAxisSynchronization.cmd, "CONFIG=./cfg/linear_1.sax"
Script for applying bus configuration.
Applies the EtherCAT configuration and caluclates data offsets in the process image.
${SCRIPTEXEC} ${ecmccfg_DIR}applyConfig.cfg
Script for applying a specific slave configuration after the slave had been added manually.
Apply configurations to a slave.
Example call:call applySlaveConfig with CONFIG
${SCRIPTEXEC} ${ecmccfg_DIR}applySlaveConfig.cmd, "CONFIG=-Motor-Nanotec-ST4118L1804-B"
call applySlaveConfig with LOCAL_CONFIG
${SCRIPTEXEC} ${ecmccfg_DIR}applySlaveConfig.cmd, "LOCAL_CONFIG=./myFancyServoConfig.cfg"
Script for applying dc config to slave
Apply dc configurations to a slave.
Script for applying substitution file
Applies substitution from ${SUBST_FILE} with ${P_SCRIPT}
SUBST_FILE (optional) substitution fileECMC_P PV prefixP_SCRIPT (optional) naming convention prefix scriptNELM (optional) Used for oversampling cards. Defaults to 1
${SCRIPTEXEC} "${ECMC_CONFIG_ROOT}applySubstitutions.cmd" "SUBST_FILE=${SUBST_FILE=ecmc${ECMC_EC_HWTYPE}.substitutions},ECMC_P=${ECMC_P}"
Script for applying a template
Applies template from ${TEMPLATE_FILE} with ${P_SCRIPT}, PARAMS can be passed
TEMPLATE_FILE template fileECMC_P PV prefixPARAMS (optional) additional parameters
${SCRIPTEXEC} "${ECMC_CONFIG_ROOT}applyTemplate.cmd" "TEMPLATE_FILE=ecmcEcSlave.template,ECMC_P=${ECMC_P}"
Script for adding an axis with configuration.
Adds an axis to the configuration and applies parameters provided by CONFIG.
CONFIG configuration file, i.e. ./cfg/linear_1.paxDEV (optional) device name, i.e. MOTOR1CLEAR_VARS_CMD (optional) Set to “empty” for not clear env vars (if vars needed for later use).CFG_MACROS (optional) Substitution macros for config file
${SCRIPTEXEC} ${ecmccfg_DIR}configureAxis.cmd, "CONFIG=./cfg/linear_1.pax"
Script for adding a slave with dedicated slave configuration to the EtherCAT bus configuration.
Adds the respective hardware to the bus configuration, adds specific and default PV to the EPICS database. Applies a specific slave configuration.
HW_DESC Hardware descriptor, i.e. EL7037CONFIG configuration file, i.e. -Motor-Nanotec-ST4118L1804-B
The CONFIG together with the HW_DESC form the full filename which by definition is ecmc${HW_DESC}${CONFIG}.cmd, i.e.: ecmcEL7037-Motor-Nanotec-ST4118L1804-B.cmd
SLAVE_ID (optional) bus positionCFG_MACROS (optional) Substitution macros for config fileNELM (optional) Used for oversampling cards. Defaults to 1
${SCRIPTEXEC} ${ecmccfg_DIR}configureSlave.cmd, "HW_DESC=EL7037, CONFIG=-Motor-Nanotec-ST4118L1804-B"
${SCRIPTEXEC} ${ecmccfg_DIR}configureSlave.cmd, "HW_DESC=EL7037, CONFIG=-Motor-Nanotec-ST4118L1804-B, SLAVE_ID=8"
Script for adding a virtual axis with configuration.
Adds a virtual axis to the configuration and applies parameters provided by CONFIG.
CONFIG configuration file, i.e. ./cfg/linear_11.vaxDEV (optional) device name, i.e. GAPCLEAR_VARS_CMD (optional) Set to “empty” for not clear env vars (if needed vars for later use).
${SCRIPTEXEC} ${ecmccfg_DIR}configureVirtualAxis.cmd, "CONFIG=./cfg/linear_11.vax"
Script for finalizing. Executed just before iocInit (atInit)
Script for finalizing. Executed just before iocInit (atInit).
Script for loading Axis from yaml file via jinja2
jinja2
adds an Axis, based on a yaml config file
Niko Kivel, Anders Sandström
FILE the yaml-file containing the PLC definitionDEV the device name (optional, defaults to ${IOC}
${SCRIPTEXEC} "./loadYamlAxis.cmd" "FILE=./axis1.yaml" ${SCRIPTEXEC} "./loadYamlAxis.cmd" "FILE=./axis1.yaml, DEV=foobar"
Script for adding Encoder from yaml file via jinja2
adds an encoder to an axis, based on a yaml config file
${SCRIPTEXEC} "./loadYamlEnc.cmd" "FILE=./enc.yaml" ${SCRIPTEXEC} "./loadYamlEnc.cmd" "FILE=./enc.yaml, DEV=foobar"
Script for loading PLC from yaml file via jinja2
adds a PLC, line by line, from a yaml-file, parsed by jinja2
FILE the yaml-file containing the PLC definition
${SCRIPTEXEC} "./loadYamlPlc.cmd" "FILE=./plc1.yaml"
Script for adding a PLC from file.
Adds a PLC defined in FILE. Also adds PLC specific EPICS PVs, i.e. for enable/disable.
FILE PLC definition file, i.e. ./plc/homeSlit.plcAX_ID (optional) Ax number, default 0PLC_MACROS (optional) Substitution macros for PLC codeTMP_PATH (optional) directory to dump the temporary plc file after macro substitutionPRINT_PLC_FILE (optional) 1/0, printout msi parsed plc file (default enable(1)).SUBST_FILE (optional) custom substitution file otherwise ecmccfg default will be loaded
${SCRIPTEXEC} ${ecmccfg_DIR}loadAxisPLCFile.cmd, "AX_ID=1, FILE=./plc/homeSlit.plc"
FILE PLC definition file, i.e. ./plc/homeSlit.plcPLC_ID (optional) PLC number, default 0, or to next free PLC, the actual PLC Id is stored in ECMC_PLC_ID and can be used after this commandSAMPLE_RATE_MS (optional) excecution rate, default 1000/EC_RATEPLC_MACROS (optional) Substitution macros for PLC code. The macros “SELF_ID”,“SELF”,M_ID, and M are reserved:TMP_PATH (optional) directory to dump the temporary plc file after macro substitutionPRINT_PLC_FILE (optional) 1/0, printout msi parsed plc file (default enable(1)).SUBST_FILE (optional) custom substitution file otherwise ecmccfg default will be loadedINC (optional) List of directories for include files to pass to MSI (if several paths thendivide with ‘:').DESC (optional) Description of PLC
${SCRIPTEXEC} ${ecmccfg_DIR}loadPLCFile.cmd, "PLC_ID=0, FILE=./plc/homeSlit.plc, SAMPLE_RATE_MS=100"
Script for loading a PLC from lib from file.
FILE PLC definition file, i.e. ./plc/homeSlit.plcPLC_ID (optional) PLC number, default last loaded PLCPLC_MACROS (optional) Substitution macros for PLC code. The macros “SELF_ID”,“SELF”,M_ID, and M are reserved:INC (optional) List of directories for include files to pass to MSI (if several paths thendivide with ‘:').TMP_PATH (optional) directory to dump the temporary plc file after macro substitutionPRINT_PLC_FILE (optional) 1/0, printout msi parsed plc file (default enable(1)).
${SCRIPTEXEC} ${ecmccfg_DIR}loadPLCLib.cmd, "PLC_ID=0, FILE=./plc/homeSlit.plc, SAMPLE_RATE_MS=100"
Script for loading a ecmc plugin from file.
Loads a ecmc-plugin from file.
FILE Filename of plugin shared lib (./ecmcPlugin_Advanced.so)PLUGIN_ID Id of plugin to loadCONFIG (optional) Configuration string sent to plugin at constructREPORT (optional) Printout information of loaded plugin if set to “1”
${SCRIPTEXEC} ${ecmccfg_DIR}loadPlugin.cmd, "PLUGIN_ID=0,FILE=./ecmcPlugin_Advanced.so,CONFIG='PLUGIN CONFIGS GO HERE '
Script for adding multiple axes based on subst and template file
Configure multiple axes by using subst file
${SCRIPTEXEC} ${ecmccfg_DIR}loadSubstAxes.cmd, "FILE=./ax.subs"
Script for loading complete ecmc cfg based on subst files and templates
Loads complete ecmc cfg based on subst files and templates
${SCRIPTEXEC} ${ecmccfg_DIR}loadSubstConfig.cmd, "FILE=./cfg.subs"
Script for adding multiple hw based on subst and template file
Loads hw cfg based on subst files and templates
${SCRIPTEXEC} ${ecmccfg_DIR}loadSubstHw.cmd, "FILE=./hw.subs"
Restores record update rate to what was defined in startup.cmd
Script for switching to operational mode.
Validates configuration, starts realtime thread and checks EtherCAT slaves are in OP.
Script for enabling default diagnostics.
Set some default values to diagostics
Script for changing record update rate
Update record processing rate, all records created after this command will be updated in the specified rate.
** script for slave verification and optional reset**
will verify the slave identity and reset by writing to 0x1011, optionally read firmwre version from 0x100a
Macros
