Add more info to manual

hugo/content/manual/PLC_cfg/function_libs.md

@@ -6,7 +6,7 @@ chapter = false
 
 ## function libs
 Function libraries can be loaded into ecmc PLCs by loadPLCLib.cmd. The command takes these parameters:
-* FILE PLC: definition file, i.e. ./plc/homeSlit.plc
+* FILE: definition file, i.e. ./plc/homeSlit.plc
 * PLC_ID: (optional) PLC number, default last loaded PLC
 * PLC_MACROS: (optional) Substitution macros for PLC code. The macros "SELF_ID","SELF",M_ID, and M are reserved:
   - "SELF_ID" = PLC Id of this plc

hugo/content/manual/best_practice.md

@@ -0,0 +1,10 @@
++++  
+title = "best practice"   
+weight = 6
+chapter = false
++++  
+
+### links to best practice:
+* [General](../general_cfg/best_practice/)
+* [Motion](../motion_cfg/best_practice/)
+* [PLC](../plc_cfg/best_practice/)

hugo/content/manual/general_cfg/best_practice.md

@@ -18,7 +18,7 @@ As a comparison, TwinCAT default EtherCAT rates are:
 * 100Hz for PLC
 * 500Hz for motion
 
-See [ecmc_server](../../knowledgebase/hardware/host/) for more information.
+See [host/ecmc_server](../../knowledgebase/host/) for more information.
 
 ## ecmc server setup
 * If possible, make sure you use the native igb ethercat driver.

hugo/content/manual/introduction.md

@@ -41,6 +41,8 @@ For this purpose scripts can be called for:
 * **adding and configure** while adding
 * **applying** a configuration to the previously added slaves
 
+In addition to these ecmccfg scripts also the ecmccomp repo that contains a component library can be used. Settings are then applied with the ecmccomp/applyComponent.cmd, see below examples.
+
 ##### examples
 The `addSlave` is used for simple slaves, a default configuration is automatically applied.
 In addition default PVs will created for the basic slave features, i.e. status.
@@ -109,17 +111,26 @@ It is theoretically possible to use a mix of `yaml` and classic configuration, b
   epicsEnvSet("DEV",      "STEST-MYDEVICE")
   ${SCRIPTEXEC} ${ecmccfg_DIR}configureAxis.cmd,  "CONFIG=./cfg/axis_1"
   ```
+{{% notice tip %}}
+See [best practice](../motion_cfg/best_practice/) and [yaml cfg](../motion_cfg/axisyaml/) and for more information.
+{{% /notice %}}
 
 ##### adding a virtual motor axis
   ```bash
   ${SCRIPTEXEC} ${ecmccfg_DIR}configureVirtualAxis.cmd,     "CONFIG=./cfg/axis_11_virt"
   ```
+{{% notice tip %}}
+See [best practice](../motion_cfg/best_practice/) and [yaml cfg](../motion_cfg/axisyaml/) and for more information.
+{{% /notice %}}
 
 ##### adding synchronization
   ```bash
   ${SCRIPTEXEC} ${ecmccfg_DIR}applyAxisSynchronization.cmd, "CONFIG=./cfg/axis_1_sync"
   ${SCRIPTEXEC} ${ecmccfg_DIR}applyAxisSynchronization.cmd, "CONFIG=./cfg/axis_11_sync"
   ```   
+{{% notice tip %}}
+See [best practice](../motion_cfg/best_practice/) and [yaml cfg](../motion_cfg/axisyaml/) and for more information.
+{{% /notice %}}
 
 ##### loading a PLC from file
 The PLC functionality is explained in detail here.
@@ -136,6 +147,9 @@ ECMC PLCs can be loaded from classical PLC files, from pure yaml files or from a
   ```bash
   ${SCRIPTEXEC} ${ecmccfg_DIR}loadYamlPlc.cmd "FILE=./plc1File.yaml"
   ```
+{{% notice tip %}}
+See [plc cfg](../plc_cfg/best_practice/) for more information.
+{{% /notice %}}
 
 #### go active
   ```bash

hugo/content/manual/knowledgebase/hardware/EL1xxx.md

@@ -0,0 +1,30 @@
++++  
+title = "EL1xxx"   
+weight = 17
+chapter = false  
++++
+
+### EL1252, EL1252-0050
+EL1252-xxxx is a 2 ch digital input terminal with timestamps (low to high, high to low):
+* EL1252: **24V signals**
+* EL1252-0050: **5V signals**
+
+Both terminals have the product id and process data and can therefore be configured as EL1252:
+```
+# One channel:
+${SCRIPTEXEC} ${ecmccfg_DIR}addSlave.cmd, "SLAVE_ID=16, HW_DESC=EL1252"
+```
+
+These terminals are very powerful since they can latch the time of the positive edge and/or negative edge of the input signal (independent of the ethercat bus rate). These timestamps can then be used to correlated other data, like encoders or analog inputs with timestamps.
+
+**IMPORTANT**
+Sine the EL1252-0050 is a 5V terminal, it needs to be powered with **5V** if the terminal is powered with 24V, the terminal will burn. The simplest way to achieve a correct power supply is by adding an EL9505 (or similar) before the EL1252-0050.
+See above for more information [5v-and-24v-terminals](../elxxxx#5v-and-24v-terminals)
+
+{{% notice warning %}}
+**Make sure the EL1252-0050 has a 5V power supply by an EL9505 (or similar), before powering the system. If the terminal is powered with the normal 24V it will most likely break**
+{{% /notice %}}
+
+{{% notice note %}}
+A 5v signal will not be detected with the 24V version (EL1252), the terminal will however not be damaged. Further more, it's not a good idea to to power the 24V version with 5V (EL9505, or similar)
+{{% /notice %}}

hugo/content/manual/knowledgebase/hardware/EL51xx.md

@@ -0,0 +1,82 @@
++++  
+title = "EL51xx"   
+weight = 20
+chapter = false  
++++
+
+## Overview
+The EL51xx series covers incremental encoder interfaces:
+1. EL5101: 1 ch, diff rs422, ttl, 1MHz
+2. EL5101-0010: 1 ch, diff rs422, 5MHz
+3. EL5101-0011: 1 ch, diff rs422, 5MHz, oversampling 100kHz
+4. EL5112: 2 ch ABC or 1ch AB, rs422, 5MHz, **PSI standard**
+5. EL5131: 1 ch, diff rs422, 5MHz, 2 digital outputs for cam/trigger
+
+### General
+Normally, the incremental encoder interfaces do not require any SDO configuration. Therefore, the ecmccomp/applyComponent.cmd, which many times are needed after the ecmccfg/addSlave.cmd, is in most cases not needed. 
+
+### Adding the slave
+Make sure you use the correct slave type when adding the slave. Some of the slaves have the same product id but totally different process data which can result in that the slave will not go into OP mode and ecmc will fail to start and a timeout will occur.
+
+For example, the EL5101-**0010** and EL5101-**0011** has the same product id but very different process data.
+So, if an EL5101-**0011** is added to the configuration but the actual slave connected is an EL5101-**0010**, the initial product id verification will not catch the miss match. However, later the slave will not go online since the process data is wrong. 
+
+The issue can be diagnosed by checking the dmesg logs:
+```bash
+# first login to host (ecmc server)
+sudo dmesg
+```
+Configuring the wrong process data will lead to an error message  "* EtherCAT * Invalid input configuration" 
+
+The solution is to use the correct configuration script.
+
+### EL5101-0010
+This is commonly used at PSI (even though the EL5112 should be teh standard choice). For configuration, use the EL5101-0010 configuration script:
+```
+${SCRIPTEXEC} ${ecmccfg_DIR}addSlave.cmd, "SLAVE_ID=16, HW_DESC=EL5101-0010"
+```
+### EL5101-0011
+This is an oversampling slave, use the EL5101-0011 configuration script with an optional NELM which defines the levels of oversampling:
+Example: Add an EL5101-0011, with 100 levels of oversampling:
+```
+${SCRIPTEXEC} ${ecmccfg_DIR}addSlave.cmd, "SLAVE_ID=16, HW_DESC=EL5101-0011, NELM=100"
+```
+In the above example, for each ethercat frame, an array of 100 elements will be transferred. If the ethercat rate is 1kHz, then the incremental data will be sampled at 100kHz (which also is the maximum rate for this terminal).
+
+{{% notice note %}}
+NELM cannot be freely defined, depending on the ethercat rate different NELM values will be accepted. Consult the EL5101-0011 manual for more information.
+Normally, NELM needs to be an integer value, like 10,20,50, 100. 
+{{% /notice %}}
+
+### EL5112
+This is the PSI standard incremental encoder interface. The terminal can be used as one channel if index pulse needs to be connected or two channel if only A and B pulse trains are needed.
+
+For 1 channel operation with index pulse, use the EL5112_ABC configuration script and for two channel, the EL5112_AB script:
+```
+# One channel:
+${SCRIPTEXEC} ${ecmccfg_DIR}addSlave.cmd, "SLAVE_ID=16, HW_DESC=EL5112_ABC"
+
+# Two channel:
+${SCRIPTEXEC} ${ecmccfg_DIR}addSlave.cmd, "SLAVE_ID=16, HW_DESC=EL5112_AB"
+```
+
+### EL5131
+This terminal support setting cam/trigger outputs at certain counter values (for predefined time, and direction).  
+
+8 predefined threshold counter values can be entered and configured switch outputs on or off. These thresholds can also be accessed/updated during runtime.
+
+Depending how the terminal should be used, the following startup scripts exists:
+* EL5131: Normal increment encoder operation
+* EL5131_DC: Normal incremental encoder and DC clock (access to timestamps)
+* EL5131_DC_TRG: Incremental encoder, access to timestamps, access to configuration of thresholds for outputs for triggering.
+
+```
+# EL5131: Normal increment encoder operation:
+${SCRIPTEXEC} ${ecmccfg_DIR}addSlave.cmd, "SLAVE_ID=16, HW_DESC=EL5131"
+
+# EL5131_DC: Normal incremental encoder and DC clock (access to timestamps)
+${SCRIPTEXEC} ${ecmccfg_DIR}addSlave.cmd, "SLAVE_ID=16, HW_DESC=EL5131_DC"
+
+# EL5131_DC_TRG: Incremental encoder, access to timestamps and configuration of thresholds for outputs/triggering.
+${SCRIPTEXEC} ${ecmccfg_DIR}addSlave.cmd, "SLAVE_ID=16, HW_DESC=EL5131_DC"
+```

hugo/content/manual/knowledgebase/hardware/EL70x1.md

@@ -1,17 +1,15 @@
 +++  
 title = "EL70x1"   
-weight = 19
+weight = 22
 chapter = false  
 +++
 
 ## Topics
 1. [error/warning](#error/warning)
 2. [Tuning](#tuning)
 
----
-
 ### error/warning
-If the drive is in error or warning state, further information about the reason for the warning/error can be read from the drive terminal by using the ethercat command. See [command line interface](ethercatcli) for more info.
+If the El70x1 is in error or warning state, further information about the reason for the error/warning can be read from the drives diagnostic register by using the ethercat command. See [command line interface](ethercatcli).
 
 {{% notice info %}}
 In order to use the ethercat command, you must first login to the server where the ecmc IOC is running.

hugo/content/manual/knowledgebase/hardware/ELxxxx.md

@@ -0,0 +1,23 @@
++++  
+title = "ELxxxx"   
+weight = 16
+chapter = false  
++++
+
+# 5V and 24V terminals
+24V is the most common signal level for the terminals, however, a few terminals also support other voltage levels, for instance 5V.
+In that case, normally the terminal needs to be powered with the same voltage.
+For 5V terminals, normally this is handled by adding a EL9505 before the 5v terminal in the ethercat chain. The EL9505 will supply the power bus with 5V instead of the normal 24V .
+
+Example of slaves needing 5V power supply:
+* EL1124 
+* El1252-0050
+* ...
+
+{{% notice warning %}}
+**If a 5V terminal is supplied with 24V it will most likely break. Make sure the terminals has the correct power supply __before__ powering the system.** 
+{{% /notice %}}
+
+{{% notice note %}}
+**The voltage level of the power bus after (downstream) of a 5V terminal is normally also 5V, if another voltage is needed then another system terminal is needed to set a new voltage level of the power bus**
+{{% /notice %}}

hugo/content/manual/knowledgebase/hardware/_index.md

@@ -1,6 +1,6 @@
 +++  
 title = "hardware"   
-weight = 15
+weight = 22
 chapter = false  
 +++  
 

hugo/content/manual/knowledgebase/hardware/host.md → hugo/content/manual/knowledgebase/host.md

@@ -1,5 +1,5 @@
 +++  
-title = "ecmc server"   
+title = "host / ecmc server"   
 weight = 17
 chapter = false  
 +++
@@ -8,8 +8,6 @@ chapter = false
 1. [latency issues](#latency-issues)
 2. [EtherCAT rate (EC_RATE)](#EtherCAT-rate-(EC_RATE))
 
----
-
 ### latency issues
 
 High latency, more than 10% of the ethercat cycle time, can in worse case result, in lost ethercat frames, which of course is not an ideal situation. High latency of the ecmc_rt thread can be related to:

hugo/content/manual/knowledgebase/panel.md

@@ -22,7 +22,7 @@ The ecmcMain.ui covers most parts of an ecmc system:
     - plugin objects
     - data storage objects
 
-The ecmcMain.ui is started with the following syntax:
+The panel is started with the following syntax:
 ```
 caqtdm -macro "IOC=<ioc_name>" ecmcMain.ui
 ```