* merge using and config for EBV and moco

* moved moco/ebv/diff to DEVICE section

doc/docs/config_beamviewer.md

@@ -2,15 +2,14 @@
 
 ![Screenshot](img/ebv.svg)
 
-see also: http://wikiserv.esrf.fr/bliss/index.php/Bvb
 
-These beamviewers visualise the various types of x-ray beam (white, pink and
-monochromatic) into the visible spectrum, using a scintillator, a camera and
-associated software to provide the beam shape and relative power
+**EBV** is an instrument to visualise the various types of x-ray beam (white,
+pink and monochromatic) into the visible spectrum, using a scintillator, a
+camera and associated software to measure the beam shape and relative power
 intensities. The maximum accommodated beam size (or potential beam movement) is
 10mm x 10mm for the standard beamviewers.
 
-ESRF "Standards" beamviewers (EBV) are composed by:
+**EBV** is an assembly of various modules:
 
 * a Control Box (ISG made)
 * a fixed giga-ethernet basler camera+lens
@@ -23,15 +22,17 @@ ESRF "Standards" beamviewers (EBV) are composed by:
         * Energy dependent for pink beam
 * a diode read by novelec module providing an output in frequency.
 * a LED that can be swiched ON and OFF.
-* optionnaly a foil to attenuate beam (on MX beamlines)
+* optionnaly: a foil to attenuate beam (on MX beamlines)
 
-## Usage
-Usage of an EBV is described here: [Beamviewer Usage](using_beamviewer.md).
+## References
+
+BCU wiki: http://wikiserv.esrf.fr/bliss/index.php/Bvb
 
 
 ## Control
 
-The **EBV** bliss object controls the wago box (screen, led, foil, diode), the basler camera and the associated BPM counters computed on images. 
+The **EBV** BLISS object controls the wago box (screen, led, foil, diode), the
+basler camera and the associated BPM counters computed on images.
 
 ## Wagobox modules
 
@@ -68,16 +69,17 @@ modbustcp:                    (mandatory)
 single_model: False
 has_foil: False
 channel: 0
-counter_name: mydiode      
+counter_name: mydiode
 
 camera_tango_url: idxx/limaccds/bv1
 
 ```
 
-`modbustcp / url` defines the wago control box host as in standard wago
-controller.
+* `modbustcp / url` defines the wago control box host as in standard wago
+  controller.
 
-`camera_tango_url` defines the `limaccds` Tango device server of associated Basler camera.
+* `camera_tango_url` defines the `limaccds` Tango device server of associated
+  Basler camera.
 
 #### Configuration optionnal parameters
 
@@ -102,7 +104,135 @@ controller.
 
 * `camera_tango_url`
     - default value : `None`
-    - if provided, the EBV will be extended with the BPM powers (Bpm measurements and BeamViewer Live display)
+    - if provided, the EBV will be extended with the BPM powers (Bpm measurements
+      and BeamViewer Live display)
+
+
+
+
+## Usage
+
+### Global status
+```
+BLISS [16]: myebv
+  Out [16]: EBV [myebv] Wago(wcid21bv1)
+                screen : IN
+                led    : ON
+                foil   : NONE
+                diode range   : 1mA
+                diode current : -0.351451 mA
+
+            Bpm [id21/limaccds/bv1]
+
+                exposure : 1.0 s
+                size     : [1024, 1024]
+                binning  : [1, 1]
+                roi      : [0, 0, 1024, 1024]
+                flip     : [False, False]
+                rotation : NONE
+```
+
+### SCREEN control
+```
+BLISS [12]: myebv.screen_in()
+BLISS [13]: myebv.screen_status
+  Out [13]: 'IN'
+
+BLISS [14]: myebv.screen_out()
+BLISS [15]: myebv.screen_status
+  Out [15]: 'OUT'
+```
+
+### LED control
+```
+BLISS [22]: myebv.led_on()
+BLISS [23]: myebv.led_status
+  Out [23]: 'ON'
+
+BLISS [24]: myebv.led_off()
+BLISS [25]: myebv.led_status
+  Out [25]: 'OFF'
+```
+
+### FOIL control
+
+If EBV has no foil, `foil_status` returns `None`:
+```
+BLISS [26]: myebv.foil_status
+  Out [26]: 'NONE'
+```
+
+Trying to use it will raise error:
+```
+BLISS [27]: myebv.foil_in()
+!!! === RuntimeError: No foil on EBV [myebv] === !!!
+BLISS [28]: myebv.foil_out()
+!!! === RuntimeError: No foil on EBV [myebv] === !!!
+```
+
+EBV with foil:
+```
+BLISS [12]: myebv.foil_in()
+BLISS [13]: myebv.foil_status
+  Out [13]: 'IN'
+
+BLISS [14]: myebv.foil_out()
+BLISS [15]: myebv.foil_status
+  Out [15]: 'OUT'
+```
+
+### DIODE current reading
+
+The current diode value is returned always in **mA**
+```
+BLISS [39]: myebv.current
+  Out [39]: 1.52587890625e-06
+```
+
+Raw reading of the underlying wago without gain correction is accessible by
+`myebv.raw_current`. The value returned is in the 0-10V range.
+
+### DIODE range control
+
+Changing diode range using string format:
+```
+BLISS [41]: myebv.diode_range_available
+  Out [41]: ['1mA', '100uA', '10uA', '1uA', '100nA', '10nA']
+
+BLISS [42]: myebv.diode_range
+  Out [42]: '10uA'
+
+BLISS [43]: myebv.diode_range = "100uA"
+BLISS [44]: myebv.diode_range
+  Out [44]: '100uA'
+```
+
+Floating value of gain used to convert reading to **mA** can also be accessed
+via:
+```
+BLISS [44]: myebv.diode_range
+  Out [44]: '100uA'
+
+BLISS [45]: myebv.diode_gain
+  Out [45]: 10.0
+
+BLISS [46]: myebv.diode_range = "10nA"
+BLISS [47]: myebv.diode_gain
+  Out [47]: 100000.0
+```
+
+Setting the floating gain is possible. Range will be chosen to include the
+maximum desired gain given:
+```
+BLISS [48]: myebv.diode_gain = 500
+BLISS [49]: myebv.diode_range
+  Out [49]: '1uA'
+
+BLISS [50]: myebv.diode_gain
+  Out [50]: 1000.0
+```
+
+
 
 
 ## EBV and BPM counters
@@ -110,7 +240,7 @@ controller.
 The BPM counter controller is accessible via the EBV object in Bliss.
 
 ```python
-BLISS [51]: myebv.bpm 
+BLISS [51]: myebv.bpm
   Out [51]: Bpm [id00/limaccds/simulator2]
 
                 exposure : 1.0 s
@@ -119,12 +249,11 @@ BLISS [51]: myebv.bpm
                 roi      : [0, 0, 1024, 1024]
                 flip     : [False, False]
                 rotation : NONE
-
 ```
 
 The EBV owns all BPM counters and the diode counter.
-```
-BLISS [51]: ct(1, myebv)                                                                                          
+```python
+BLISS [51]: ct(1, myebv)
 Tue Mar 31 16:43:52 2020
 
  acq_time = 1.038032054901123 ( 1.038032054901123/s)
@@ -134,30 +263,48 @@ intensity =         99.2 (        99.2/s)
         x =        512.0 (       512.0/s)
         y =        512.0 (       512.0/s)
 ebv_diode = -0.15674306466872268 (-0.15674306466872268/s)
+```
+
 
 
+### Bpm measurements reading
+
+Measure and return data (timestamp, intensity, center_x, center_y, fwhm_x, fwhm_y)
+```python
+BLISS [53]: myebv.bpm.raw_read()
+  Out [53]: [array([1.0819428]), array([99.2]), array([512.]),
+             array([512.]), array([99.04761905]), array([99.04761905])]
 ```
 
 
-At the BPM level some camera parameters can be modified:
+## Visualization
 
-* `myebv.bpm.exposure`
-* `myebv.bpm.bin`    
-* `myebv.bpm.roi`    
-* `myebv.bpm.flip`   
-* `myebv.bpm.rotation`
+The command `myebv.show_beam` will start/raise Flint and display a live preview
+from the EBV camera.
 
-more here: [Beamviewer Usage](using_beamviewer.md)
+To stop the live, just close the tab in Flint.
 
+If a scan is started, the live is automatically stopped first.
 
+A single snapshot can be performed with the command `myebv.bpm.snap()`
 
+Some parameters of the underlying camera can be read or write:
 
+```python
+myebv.bpm.exposure = 0.01           # (sec)
+myebv.bpm.bin = [2,2]               # (xbin, ybin)
+myebv.bpm.roi = [100,200,300,300]   # (xpos, ypos, width, height)
+myebv.bpm.flip = [True, False]      # (LR, TB)
+myebv.bpm.rotation = 'None'         # in ['None', '90', '180', '270']
+```
 
-# BPM Controller (camera only + BPM measurements)
+## BPM Controller (camera only + BPM measurements)
 
-Single cameras which are not part of an EBV set (i.e without the Wago part for the control of the LED/Foil/Screen) can be used to perform BPM measurements.  
+Single cameras which are not part of an EBV set (i.e without the Wago part for
+the control of the LED/Foil/Screen) can be used to perform BPM measurements.
 
-A standalone `BpmController` object can be associated to the camera and created from the configuration files like this:
+A standalone `BpmController` object can be associated to the camera and created
+from the configuration files like this:
 
 ```
 name: mybpm
@@ -165,4 +312,56 @@ plugin: bliss
 module: ebv
 class: BpmController
 camera_tango_url: idxx/limaccds/camname
-```
\ No newline at end of file
+```
+
+
+
+## EBV counters
+
+The EBV has 6 sampling counters (1 for the diode and 5 for the Bpm
+measurements):
+
+- myebv.diode
+- myebv.x
+- myebv.y
+- myebv.fwhm_x
+- myebv.fwhm_y
+- myebv.intensity
+
+
+`myebv` holds all 6 counters wheras `myebv.diode` returns only the diode
+counter.
+
+The Bpm measurements will be performed using the current CCD exposure and image
+parameters (bin, roi, flip, rotation).
+
+The camera trigger mode is forced to `INTERNAL_TRIGGER` and camera mode to
+`SINGLE`.
+
+If the scan count_time is longer than the ccd exposure the Bpm measurements are
+sampled as many times as possible.
+
+!!!note
+    the default counter name for the diode is *diode* but it can be changed in
+    the configuration file.
+
+```
+BLISS [51]: ct(1, myebv)
+Tue Mar 31 16:43:52 2020
+
+ acq_time = 1.038032054901123 ( 1.038032054901123/s)
+   fwhm_x = 99.04761904761904 ( 99.04761904761904/s)
+   fwhm_y = 99.04761904761904 ( 99.04761904761904/s)
+intensity =         99.2 (        99.2/s)
+        x =        512.0 (       512.0/s)
+        y =        512.0 (       512.0/s)
+ebv_diode = -0.15674306466872268 (-0.15674306466872268/s)
+
+
+
+BLISS [52]: ct(1, myebv.diode)
+Tue Mar 31 16:54:15 2020
+
+ebv_diode = -0.1567430646687215 (-0.1567430646687215/s)
+```
+

doc/docs/config_moco.md

@@ -2,19 +2,42 @@
 
 ## Description
 
-This module allows to control ISG MOCO device.
 
-This module provides:
+
+The Monochromator Controller (MoCo) is an electronic module designed to regulate
+the position of an optical component in a synchrotron radiation beamline. The
+controller corrects the position of the component, typically a mirror or a
+monochromator, by monitoring the outgoing beam and actively compensating low
+frequency drifts due to thermal load changes or mechanical instability.
+
+Features:
+
+* Active regulation of an optical element on one of its degrees of freedom.
+* Keeps constant either the transmission or the position of the beam.
+* Primarily designed for double crystal monochromators but it could be
+  potentially used with other optics (mirrors, single crystal monochromators).
+* Main features:- Time constant from 1 ms to 1 minute- Automatic tuning-
+  Autorange- Beam lost detection- Current and voltage inputs- Serial line
+  communication
+* Can be configured from slave mode to fully automatic mode.
+* Built-in current amplifiers (24 gain ranges over 7 decades).
+
+
+
+BLISS Moco controller provides:
 
 * Raw access to MOCO commands
-* Direct access as method or attributes to the main functionnalities of the device
+* Direct access as method or attributes to the main functionnalities of the
+  device
 * Access to MOCO values as BLISS counters
 * definition of a BLISS motor to control the Voltage output of the module
   (usually a piezo is connected to this output)
 
-## Usage
 
-Usage of a MOCO object is described here: [MOCO Usage](using_moco.md).
+## References
+
+* BCU wiki page: http://wikiserv.esrf.fr/bliss/index.php/Moco
+
 
 ## Configuration
 
@@ -26,8 +49,8 @@ Usage of a MOCO object is described here: [MOCO Usage](using_moco.md).
   class: Moco                       (mandatory)
   name: mocoeh1                     (mandatory)
   serial:                           (mandatory)
-    url: rfc2217://ld231-new:28213  (mandatory)
-      
+    url: rfc2217://ld421-new:28213  (mandatory)
+
   counters:
     - counter_name: outm
       role: outbeam
@@ -75,11 +98,241 @@ Usage of a MOCO object is described here: [MOCO Usage](using_moco.md).
 
 ### Configuration options
 
-* If you do not need a motor just remove it from the yml file
-* In the `counters` section add only the counters you need
+* Motor can be removed from the yml file if not needed.
+* In the `counters` section add only the needed counters.
 
-## References
 
-* User Manual: http://www.esrf.fr/Instrumentation/DetectorsAndElectronics/moco
-* ISG/ESL page: http://www.esrf.fr/Instrumentation/DetectorsAndElectronics/moco
-* BCU wiki page: http://wikiserv.esrf.fr/bliss/index.php/Moco
+
+## Usage
+
+In the following session, The Moco object `moco` is running in the
+`moco` BLISS session
+
+### User API
+
+#### status
+
+* Status got from the MOCO device
+
+```python
+DEMO [1]: moco
+ Out [1]: MOCO
+          Name    : moco
+          Comm.   : Serial[rfc2217://lid265:28254]
+
+          MOCO 02.00  -  Current settings:
+            NAME "no name"
+            ADDR
+
+            OPRANGE -2 5 0
+            INBEAM SOFT 1
+            OUTBEAM VOLT NORM UNIP 1.25 NOAUTO
+
+            MODE OSCILLATION
+            AMPLITUDE 0.0513738
+            FREQUENCY 166.667
+            PHASE 150
+            SLOPE 1
+            SETPOINT 0
+            TAU 0.1
+            SET
+            CLEAR  AUTORUN BEAMCHECK NORMALISE AUTORANGE INTERLOCK
+            AUTOTUNE OFF
+            AUTOPEAK OFF
+            BEAMCHECK 0.1 0.1 1.024 0
+            SRANGE 0 3
+            SPEED 2 50
+            INHIBIT OFF LOW
+```
+
+* Status of the regulation
+
+```python
+DEMO [2]: moco.state()
+IDLE
+```
+
+#### Parameters
+
+A number of MOCO parameters can set and read:
+
+* `amplitude`
+```python
+DEMO [3]: moco.amplitude = 0.00513
+DEMO [4]: moco.amplitude
+ Out [4]: 0.00513
+```
+
+* `phase`
+```python
+DEMO [5]: moco.phase = 150.0
+DEMO [6]: moco.phase
+ Out [6]: 150.0
+```
+
+* `slope`
+```python
+DEMO [7]: moco.slope = 1.0
+DEMO [8]: moco.slope
+ Out [8]: 1.0
+```
+
+* `tau`
+```python
+DEMO [9]: moco.tau = 0.1
+DEMO [10]: moco.tau
+ Out [10]: 0.1
+```
+
+* `frequency`
+```python
+DEMO [11]: moco.frequency = 166.667
+DEMO [12]: moco.frequency
+ Out [12]: 166.667
+```
+
+#### Commands
+
+All commands of a MOCO obejct have silent mode:
+
+```python
+moco.command(par1=val1, par2=val2, ..., silent=False/True)
+```
+
+The most important functionnalities of MOCO may be access using the following
+commands:
+
+* `mode`
+```python
+DEMO [14]: moco.mode("OSCILLATION")
+MODE: OSCILLATION       [POSITION | INTENSITY | OSCILLATION]
+ Out [14]: 'OSCILLATION'
+
+DEMO [15]: moco.mode()
+MODE: OSCILLATION       [POSITION | INTENSITY | OSCILLATION]
+ Out [15]: 'OSCILLATION'
+```
+
+* `srange`
+```python
+DEMO [16]: moco.srange(0, 3)
+SRANGE: [0 - 3]
+ Out [116]: [0.0, 3.0]
+
+DEMO [17]: moco.srange()
+SRANGE: [0 - 3]
+ Out [17]: [0.0, 3.0]
+```
+
+* `outbeam`
+```python
+DEMO [18]: moco.outbeam("VOLT", "NORM", "UNIP", 1.25, "autoscale")
+OUTBEAM: source    : VOLT       [CURR | VOLT | EXT]
+         polarity  : NORM       [NORM | INV]
+         channel   : UNIP       [BIP | UNI]
+         fullscale : 1.25
+         autoscale : NOAUTO     [AUTO | NOAUTO]
+DEMO [19]: moco.outbeam()
+OUTBEAM: source    : VOLT       [CURR | VOLT | EXT]
+         polarity  : NORM       [NORM | INV]
+         channel   : UNIP       [BIP | UNI]
+         fullscale : 1.25
+         autoscale : NOAUTO     [AUTO | NOAUTO]
+```
+
+* `go`
+```python
+DEMO [20]: moco.go()
+```
+
+* `peak`
+```python
+DEMO [21]: moco.peak(1, 0.1, 0.0)
+DEMO [22]: moco.peak()
+PEAK: height=1  width=0.1  pos=0
+ Out [22]: [1.0, 0.1, 0.0]
+```
+
+* `tune`
+```python
+DEMO [20]: moco.tune()
+```
+
+* `stop`
+```python
+DEMO [20]: moco.stop()
+```
+
+* `beam`
+```python
+DEMO [19]: moco.beam()
+
+Beam IN  [0]
+Beam OUT [0.0223569]
+```
+
+### Raw commands
+
+* MOCO commands may be call using raw communication system
+
+```python
+DEMO [3]: moco.comm("?BEAM")
+ Out [3]: '0 0.0217459'
+```
+
+* List of commands available using the .comm method
+
+```python
+DEMO [2]: moco.help()
+
+      RESET
+        GO
+      STOP
+      TUNE
+  AUTOTUNE  ?AUTOTUNE
+  AUTOPEAK  ?AUTOPEAK
+     PIEZO  ?PIEZO
+            ?STATE
+            ?BEAM
+            ?FBEAM
+  AUTOBEAM
+  SOFTBEAM  ?SOFTBEAM
+   OPRANGE  ?OPRANGE
+    SRANGE  ?SRANGE
+       SET
+            ?CLEAR
+     CLEAR
+            ?SET
+     PAUSE  ?PAUSE
+   INHIBIT  ?INHIBIT
+       TAU  ?TAU
+  SETPOINT  ?SETPOINT
+      MODE  ?MODE
+    INBEAM  ?INBEAM
+   OUTBEAM  ?OUTBEAM
+      GAIN  ?GAIN
+      ZERO  ?ZERO
+    OFFSET  ?OFFSET
+  ADCCALIB  ?ADCCALIB
+ BEAMCHECK  ?BEAMCHECK
+     SPEED  ?SPEED
+      PEAK  ?PEAK
+     SLOPE  ?SLOPE
+            ?OSCBEAM
+            ?OSCSAT
+     OSCIL  ?OSCIL
+ AMPLITUDE  ?AMPLITUDE
+ FREQUENCY  ?FREQUENCY
+     PHASE  ?PHASE
+            ?INFO
+   ISGTEST  ?ISGTEST
+      ECHO
+    NOECHO
+            ?ERR
+      ADDR  ?ADDR
+            ?CHAIN
+      NAME  ?NAME