Slight resturcture in manual

hugo/content/manual/general_cfg/best_practice.md

@@ -0,0 +1,28 @@
++++  
+title = "best practice"   
+weight = 14
+chapter = false  
++++  
+
+## EtherCAT rate (EC_RATE)
+The default EtherCAT frame rate in ecmc is set to 1kHz. For most applications this is however not needed and can therefore be reduced. A reduced EtherCAT rate reduces the load on the controller. In general, a good value for the frame rate is in the range 100Hz to 1kHz. For motion systems, a frame rate of 100Hz..500Hz is normally enough. Rates ouside the 100Hz..1kHz range is normally not a good idea, and some slaves might not support it. However, in special cases both lower and higher rates might be possible and required.
+
+Example: Set rate to 500Hz
+```
+require ecmccfg "EC_RATE=500"
+...
+```
+For more information see the chapter [startup.cmd](../startup/_index.md).
+
+As a comparison, TwinCAT default EtherCAT rates are:
+* 100Hz for PLC
+* 500Hz for motion
+
+See [ecmc_server](../knowledgebase/hardware/host.md) for more information.
+
+## ecmc server setup
+* If possible, make sure you use the native igb ethercat driver.
+
+For more information see:
+* https://git.psi.ch/motion/ecmc_server_cfg
+* [ecmc_server](../knowledgebase/hardware/host.md) for more information.

hugo/content/manual/general_cfg/startup/_index.md

@@ -48,7 +48,4 @@ Normally these arguments are set when the module is required:
 require ecmccfg "ENG_MODE=1,MASTER_ID=2"
 ```
 
-### [set mode](modes)
-A very powerful tool is provided through the command line.
-See a summary, incl. some examples of what possible [here](ethercatcli).
 

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

@@ -1,6 +1,6 @@
 +++  
 title = "EL5042"   
-weight = 15
+weight = 18
 chapter = false  
 +++
 
@@ -43,7 +43,7 @@ Lack of clock or data pulses could be caused by (in order of probability):
 Make sure the encoder is powered with the correct voltage. Most encoders require 5V, but there are also some that require 9V, 12V or 24V.
 
 {{% notice warning %}}
-Never apply a higher voltage than the specified operating voltage for the encoder.
+**Never apply a higher voltage than the specified operating voltage for the encoder.**
 {{% /notice %}}
 
 The EL5042 can supply 5V or 9V. The default setting is 5V and in order to change the setting to 9V a special sequence need to be executed (see EL5042 manual).
@@ -120,7 +120,7 @@ Note: The tool ecmccfg/utils/PDO_read can also be used for reading the diagnosti
 ### Offset LSB Bit [Bit] (0x80p8:17)
 
 {{% notice warning %}}
-When using the LSB offset, the same amount of ones ("1") will be shifted in as MSB. Therefore the LSB offset should normally not be used.
+**When using the LSB offset, the same amount of ones ("1") will be shifted in as MSB. Therefore the LSB offset should normally not be used.**
 {{% /notice %}}
 
 When using the LSB offset setting, the same amout of bits needs to be subtracted from the ST_BITS or MT_BITS
@@ -141,7 +141,7 @@ ${SCRIPTEXEC} ${ecmccomp_DIR}applyComponent.cmd "COMP=Encoder-Generic-BISS-C,CH_
 * Enabling status bits by SDO (0x80p8:02) will not work, seems only valid for BISS-C (kind of hints this in manual).
 
 {{% notice warning %}}
-If the total bit count does not match, the READY bit of the EL5042 will be low (and soemtimes also error or warning).
+**If the total bit count does not match, the READY bit of the EL5042 will be low (and soemtimes also error or warning).**
 {{% /notice %}}
 
 Example: 26bit RLS encoder with 2 status bits (set ST_BITS=28)

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

@@ -1,6 +1,6 @@
 +++  
 title = "EL70x1"   
-weight = 18
+weight = 19
 chapter = false  
 +++
 

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

@@ -17,7 +17,7 @@ In the standard setup at PSI over current protection modules are used to feed 24
 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. 
 
 {{% notice warning %}}
-Before pressing the buttons, check the electrical drawings. Make sure it's safe to power on the system.
+**Before pressing any button, check the electrical drawings and make sure it's safe to power on the system.**
 {{% /notice %}}
 
 #### el9221-5000
@@ -32,5 +32,5 @@ Some terminals are passive. Passive terminals are not EtherCAT slaves and do not
 The passive terminals will not show up as an EtherCAT slave when issueing the "ethercat slaves" command. However, they are normally visible in the electrical drawings. This could result in that the slave id in the electrical drawing is **NOT** corresponding to the EtherCAT slave index used when configuring ecmc. In worst case this could lead to that the wrong hardware/drive is configured.
 
 {{% notice warning %}}
-**When configuring ecmc, make sure the EtherCAT slave index is correct, do not blindly trust the electrical drawings since and passive terminal could introduce an shift in the slave indices.**
+**When configuring ecmc, make sure the EtherCAT slave index is correct, do not blindly trust the electrical drawings since a passive terminal could introduce an shift in the slave indices.**
 {{% /notice %}}

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

@@ -1,7 +1,7 @@
 
 +++  
 title = "general"   
-weight = 12
+weight = 16
 chapter = false  
 +++
 

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

@@ -1,13 +1,14 @@
 +++  
 title = "ecmc server"   
-weight = 14
+weight = 17
 chapter = false  
 +++
 
 ***
 ***
 ## Topics
 1. [latency issues](#latency-issues)
+2. [EtherCAT rate (EC_RATE)](#EtherCAT-rate-(EC_RATE))
 
 ---
 
@@ -45,7 +46,7 @@ The sample rate is defined when require ecmccfg (example set to 500Hz, instead o
 require ecmccfg "EC_RATE=500"
 ```
 {{% notice info %}}
-There are some restrictions on the sample rate. Normally, a rate in the range 100Hz-1Khz is a good choice. For other rates, please check the documentation of slaves in use.  
+There are some restrictions on the sample rate. Normally, a rate in the range 100Hz-1Khz is a good choice. For other rates, please check the documentation of slaves in use. See heading "EtherCAT rate" below for more information.
 {{% /notice %}}
 
 ** Affinity**
@@ -71,3 +72,41 @@ afterInit "epicsThreadSetAffinity cbLow 6"
 {{% notice info %}}
 cbLow is created at iocInit, therefore the "epicsThreadSetAffinity" must be executed with the "afterInit" command.
 {{% /notice %}}
+
+### EtherCAT rate (EC_RATE)
+The default EtherCAT frame rate in ecmc is set to 1kHz. For most applications this is however not needed and can therefore be reduced. A reduced EtherCAT rate reduces the load on the controller. In general, a good value for the frame rate is in the range 100Hz to 1kHz. For motion systems, a frame rate of 100Hz..500Hz is normally enough. Rates ouside the 100Hz..1kHz range is normally not a good idea, and some slaves might not support it. However, in special cases both lower and higher rates might be possible and required.
+
+Example: Set rate to 500Hz
+```
+require ecmccfg "EC_RATE=500"
+...
+```
+For more information see the chapter descriping startup.cmd.
+
+As a comparison, TwinCAT default EtherCAT rates are:
+* 100Hz for PLC
+* 500Hz for motion
+
+#### Lower rates
+Issues that could occour in rates below 100Hz:
+* triggering of slave watchdogs
+* issues with dc clock syncs (DC capabale slaves normally performes best with at a rate of atleast 500Hz)
+* some slaves might not support it
+
+#### Higher rates
+Issues that could occour in rates over 1000Kz:
+* missed frames
+* issues with dc clock syncs
+* some slaves might not support it.
+
+NOTE: Some slave might support a high rate but could have built in signal filters of several ms which then makes sampling at higher freqs unneccesarry/not needed.
+
+In order to successfully run an ecmc ethercat system at higher rates some tuning might be needed:
+* minimize slave count (and ensure that the slaves support it)
+* minimize amount of processing (PLC, motion)
+* use a performant host/controller
+* use native ethercat driver (igb, not generic)
+* only transfer the needed PVs to epics.
+* affinity: Use a dedicated core for the ecmc_rt thread and move other high prio threads to other cores. see "high load on system
+" above.
+* consider use of more than one domain