### Start Minimal Demo Setup

Source: https://github.com/bliss/bliss/blob/master/doc/docs/bliss/bliss_demo.md

Starts the bare minimal demo setup without detecting detectors. This is useful for launching only the lima2_simulator.

```bash
bliss-demo-servers --no-detectors
```

--------------------------------

### BLISS Session Setup File Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/config/config_sessions.md

A Python script for a BLISS session setup, demonstrating how to configure scan saving paths and templates.

```python
import os
from bliss.common.standard import * # import all default functions, scans, etc. 

SCAN_SAVING.base_path = os.path.join(os.environ["HOME"], "scans")
SCAN_SAVING.template = "{session}/{date}"
print "Setting scanfile to", SCAN_SAVING.get_path()

```

--------------------------------

### Controller Serial Communication Setup

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_comm.md

Example of initializing serial communication within a controller class using `get_comm`.

```python
from bliss.comm.util import get_comm, SERIAL

class FooController:
    def __init__(self, config):
        self.config = config
        self._comm = None

    def _init_com(self):
        default_options = {'baudrate': 19200}
        self._comm = get_comm(self.config, ctype=SERIAL, **default_options)
```

--------------------------------

### TCP Proxy Command Line Options

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_comm.md

Command-line examples for starting the tcp-proxy server externally, either by host/port or by beacon name.

```bash
tcp-proxy --host id14serial1.esrf.fr --port 9001
```

```bash
tcp-proxy --beacon-name k_pico1
```

--------------------------------

### BLISS Version Output (Package Installation)

Source: https://github.com/bliss/bliss/blob/master/doc/docs/installation/installation_esrf.md

Example of the BLISS version output when installed as a package.

```python
...
Welcome to BLISS version 1.11.0 running on lid00 (in bliss Conda environment)
Copyright (c) Beamline Control Unit, ESRF
...
```

--------------------------------

### Install Data Publishing Dependencies

Source: https://github.com/bliss/bliss/blob/master/scripts/scanning/withoutbliss/README.md

Installs the required dependencies for data publishing. Activate the virtual environment before proceeding.

```bash
python -m venv $HOME/virtualenvs/scan_env
source $HOME/virtualenvs/scan_env/bin/activate

pip install blissdata
```

--------------------------------

### Bash Command Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_documentation.md

Example of a bash command with options and arguments, useful for command-line interface documentation.

```bash
% bliss -h
Usage: bliss [-l | --log-level=<log_level>] [-s <name> | --session=<name>]
       bliss [-v | --version]
       bliss [-c <name> | --create=<name>]
       bliss [-d <name> | --delete=<name>]
       bliss [-h | --help]
```

--------------------------------

### Start Custom Data Monitor Client

Source: https://github.com/bliss/bliss/blob/master/scripts/scanning/withoutbliss/README.md

Starts a custom client to monitor and print data statistics. Ensure the virtual environment is activated.

```bash
source $HOME/virtualenvs/monitor_env/bin/activate

python ./bliss/scripts/scanning/withoutbliss/startmonitor.py
```

--------------------------------

### Install BLISS from Source

Source: https://github.com/bliss/bliss/blob/master/doc/docs/installation/installation.md

Install BLISS in editable mode from a local source checkout. This is useful for development.

```bash
git clone https://gitlab.esrf.fr/bliss/bliss
cd bliss/

pip install -e .
```

--------------------------------

### Hardware Controller Implementation Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_write_ctrl_hardware.md

This class demonstrates a low-level hardware controller for a device. It includes initialization, communication setup, command sending with validation, and property management for device attributes like version and integration time. Ensure the BLISS environment and necessary communication modules are available.

```python
from bliss import global_map
from bliss.comm.util import get_comm, TCP
from bliss.common.logtools import log_debug

class FooDevice:

    """
    Low level controller class for device XXX model YYY

    manufacturer:
    website: 
    description:
    """

    _WEOL = "\r"      # write eol
    _REOL = "\r\n"    # read eol

    _CMD2PARAM = {                    # a dict { cmd: (possible arg values, ...) }
        "ACQ": ("ON", "OFF"),        # a cmd taking 2 possible arg values of type str
        "BDR": (9600, 19200, 38400), # a cmd taking 3 possible arg values of type int
        "VER": None,                 # a cmd which does not take arg
        "ITM": [1e-3, 1.],           # a cmd taking an arg of type float in a given range
    }

    _CHANNEL_NAMES = (1, 2, 3, 4)
    _DEFAULT_PORT = 10001

    def __init__(self, config):
        self._config = config
        self._comm = None

        # === attribute examples
        self._version = None
        self._integration_time = None

    def __del__(self):
        self.__close__()

    def __close__(self):
        """ BLISS will try to call this method when closing a session """
        self._close_comm()

    def _init_comm(self):
        """ Initialize communication object """
        default_options = {'eol': self._REOL, 'port': self._DEFAULT_PORT}
        self._comm = get_comm(self._config , ctype=TCP, **default_options)
        global_map.register(self, children_list=[self._comm])

    def _close_comm(self):
        """ Close communication """
        if self._comm is not None:
            self._comm.close()
            self._comm = None
    
    @property
    def comm(self):
        if self._comm is None:
            self._init_comm()
        return self._comm

    def send_cmd(self, cmd, arg=None, channel=None):
        """ Send a command to the hardware and read the answer """

        self._check_cmd(cmd, arg, channel)

        msg = f"{cmd}"
        if channel is not None:
            msg += f" {channel}"
        if arg is not None:
            msg += f" {arg}"
        msg += f"{self._WEOL}"

        log_debug(self, f"send_cmd {msg}")
        ans = self.comm.write_readline(msg.encode()).decode()
        log_debug(self, f"receive {ans}")

        return ans

    def _check_cmd(self, cmd, arg=None, channel=None):
        """ Check command and argument validity """

        if cmd not in self._CMD2PARAM.keys():
            raise ValueError(
                f"Unknown command '{cmd}', should be in {list(self._CMD2PARAM.keys())}"
            )

        if channel is not None:
            if channel not in self._CHANNEL_NAMES:
                raise ValueError(
                        f"Unknown channel '{channel}', should be in {self._CHANNEL_NAMES}"
                    )

        if arg not in [None, '?']: # setter case
            rng = self._CMD2PARAM[cmd]

            # cmd does not expect an arg
            if rng is None:
                raise ValueError(
                        f"command '{cmd}' does not expect an argument but receives '{arg}'"
                    )

            # cmd expects known arg values
            if isinstance(rng, tuple):
                if arg not in rng:
                    raise ValueError(
                        f"command '{cmd}' expects argument in {rng} but receives '{arg}'"
                    )

            # cmd expects arg value in a given range
            if isinstance(rng, list):
                mini, maxi = rng
                if arg < mini or arg > maxi:
                    raise ValueError(
                        f"command '{cmd}' expects argument in range {rng} but receives '{arg}'"
                    )

    
    #=== User API / property examples ======================================

    @property
    def version(self):
        if self._version is None:
            self._version = self.send_cmd("VER", "?")
        return self._version

    @property
    def integration_time(self):
        if self._integration_time is None:
            self._integration_time = self.send_cmd("ITM", "?")
        return self._integration_time

    @integration_time.setter
    def integration_time(self, value):
        self.send_cmd("ITM", value)
        self._integration_time = value

```

--------------------------------

### EBV Configuration Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_beamviewer.md

Example configuration block for setting up an EBV instance within the BLISS system.

```APIDOC
plugin: bliss                 (mandatory)
name: myebv                   (mandatory)
class: EBV                    (mandatory)
modbustcp:
    url: wcidxxa              (mandatory)

single_model: False
has_foil: False
channel: 0
counter_name: mydiode

camera_tango_url: idxx/limaccds/bv1
```

--------------------------------

### Supervisor Startup Script for P201

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_p201.md

Example supervisor configuration for automatically starting the BLISS CT2 RPC server. This script sets up environment variables, logging, and restart policies for the P201 server.

```ini
[group:EH1]
programs=P201_zerorpc
priority=100

[program:P201_zerorpc]
command=bash -c ". /users/blissadm/bin/blissenv && exec bliss-ct2-server --name p201_eh1"
priority=800
environment=HOME="/users/blissadm"
user=blissadm
startsecs=2
autostart=true
redirect_stderr=true
stdout_logfile=/var/log/%(program_name)s.log
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_capture_maxbytes=1MB

```

--------------------------------

### Complete P201 Controller Configuration with External Sync

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_p201.md

A comprehensive configuration example for the P201 controller, including channel setup and external trigger/gate synchronization. Note that channels used for external sync cannot be used for counting.

```yaml
plugin: ct2                    # (1)
name: p201_eh1                 # (2)
class: CT2                     # (3)
address: tcp://lid312:8909     # (4)
card_address: /dev/ct2_0       # (5)
type: P201                     # (6)
clock: CLK_100_MHz             # (7)
external sync:                 # (8)
  input:                       # (9)
    channel: 9                 # (10)
    polarity inverted: False   # (11)
  output:                      # (12)
    channel: 10                # (13)
    mode: gate                 # (14)
channels:
- address: 1                   # (16)
  counter name: pC1            # (17)
  50 ohm: true                 # (18)
  level: TTL                   # (19)
- address: 10
  level: NIM                   # (20)
```

--------------------------------

### Start Beacon Server with Configuration Path

Source: https://github.com/bliss/bliss/blob/master/doc/docs/beacon/beacon_install.md

Specify the path to the YAML configuration file when starting the Beacon server. This is required for both beamline and test environments.

```shell
beacon-server --db-path=~/local/beamline_configuration
```

```shell
beacon-server --db-path=~/bliss/tests/test_configuration
```

--------------------------------

### BlissController YAML Configuration Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_write_ctrl_base.md

Example YAML configuration for a BlissController, demonstrating the declaration of counters and their associated tags.

```yaml
- class: FooController   # object class (inheriting from BlissController)
  plugin: generic        # BlissController works with generic plugin
  module: foo_module     # module where the FooController class can be found
  name: foo              # a name for the controller (optional)

  counters:              # a section to declare counters
    - name: cnt_hv       # name for a counter
      tag: hv            # a tag to identify this counter within the controller
    - name: cnt_cur      # a name for another counter
      tag: cur           # a tag to identify this counter within the controller


```

--------------------------------

### Install ODA Client-Side

Source: https://github.com/bliss/bliss/blob/master/doc/docs/installation/installation.md

Activate the bliss environment and install the ODA client-side components. This is required for using ODA with bliss.

```bash
conda activate bliss_env
pip install ./blissdemo[client]

```

--------------------------------

### Tango Configuration Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/bliss/bliss_brother.md

Example Tango configuration for BlissBrother, setting time intervals for storing motionless motors.

```yaml
delta_time_still_motor: 1200
still_time_before_saving: 15
```

--------------------------------

### Tripod Configuration Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_tripod.md

Example YAML configuration for a tripod system with two centers of rotation ('hall' and 'ring') and definitions for real and calculated axes.

```yaml
- plugin: emotion
  module: tripod
  class: tripod
  name: fjs_tripod
  centers:
    ### Si111
    - center_id: hall
      ax: -0.140
      ay: -0.1525
      bx: -0.140
      by: 0.0675
      cx: 0.140
      cy: -0.0425
    ### Si311
    - center_id: ring
      ax: -0.140
      ay: -0.0675
      bx: -0.140
      by: 0.1525
      cx: 0.140
      cy: 0.0425
  axes:
    - name: $mfjsur
      tags: real lega
    - name: $mfjsuh
      tags: real legb
    - name: $mfjsd
      tags: real legc

    - name: fjsz
      unit: mm
      tags: tz
    - name: fjsrx
      unit: mrad
      tags: rx
    - name: fjsry
      unit: mrad
      tags: ry
```

--------------------------------

### Sens4 VPM-5 Query Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_sens4.md

Example of sending a single parameter query for the MEMS Pirani sensor and the expected acknowledgment reply.

```text
Send: @254P?MP\
Reply: @ACK1.23E-5\
```

--------------------------------

### Serve Local BLISS Documentation (Alternative)

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_documentation.md

Starts the mkdocs server with a specified host and port. Useful for accessing documentation from other devices on the network.

```bash
hostname
myhost
cd <bliss.git directory>/doc/
mkdocs serve -a 0.0.0.0:8888
```

--------------------------------

### BLISS Version Output (Git Installation)

Source: https://github.com/bliss/bliss/blob/master/doc/docs/installation/installation_esrf.md

Example of the BLISS version output when installed from a Git repository, indicating a development version.

```python
...
Welcome to BLISS v1.11.dev0 running on lid00 (in bliss_dev Conda environment)
Copyright (c) Beamline Control Unit, ESRF
...
```

--------------------------------

### Configure I5 Device Server with Jive

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_tango_i5.md

Shows how to create a server instance using Jive, specifying the server name, class, device, and properties.

```yaml
Server: i5_ds/id00
Class: PreciamolenI5
Device: id00/i5/0
properties:
- beacon_name: i5
```

--------------------------------

### Google Style Docstring Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_guidelines.md

An example of a Python function docstring following the Google Style Guide, including Notes, See Also, Args, Returns, and Raises sections.

```python
    def move(axis, position, wait=False):
		"""
		Move the given axis to the given absolute position

		Note:
			using `wait=True` will block the current :class:`~gevent.Greenlet`.

	    See Also:
			:func:`rmove`

        code example: ``register(self, children_list=[self.comm])  # comm layer``

        `This will be printed in italic`

	    Args:
			axis (Axis): instance of bliss :class:`bliss.common.axis.Axis`
			position (float): position (axis units)
			wait (bool): wait or not for motion to end [default: False]

        Returns:
			float: actual position where motor is (axis units)

        Raises:
			RuntimeError
		"""
		pass

```

--------------------------------

### Launch Musst Device Server

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_tango_musst.md

Demonstrates the command-line steps to launch the Musst device server, including setting the TANGO_HOST environment variable and checking server help.

```bash
(base)  user@beamline:~/bliss$ conda activate bliss
```

```bash
(bliss) user@beamline:~/bliss$ Musst -?
```

```bash
(bliss) user@beamline:~/bliss$ export TANGO_HOST=localhost:20000
```

```bash
(bliss) user@beamline:~/bliss$ Musst -?
```

```bash
(bliss) user@beamline:~/bliss$ Musst musst_server
```

--------------------------------

### ACE Detector Configuration and Scan Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_ace.md

Displays the configuration details of an ACE detector and shows an example of initiating a scan. Use this to understand detector settings and how to start data acquisition.

```python
    Out [16]: ACE card: acedet, ACE 01.04a
              GPIB type=TANGO_DEVICE_SERVER url='tango_gpib_device_server://id10/gpib_40/0'
                   primary address='9' secondary address='0' tmo='13' timeout(s)='10' eol='
              '
              HEAD MAX CURRENT:               11 mA              (range [0, 25])
              HEAD MAX TEMPERATURE:           40 °C              (range=[0, 50])
              HEAD CURRENT TEMPERATURE:       26.1 °C
              HEAD BIAS VOLTAGE SETPOINT:     420 V (ON)         (range=[0, 600])
              COUNTING SOURCE:                SCA
              SCA MODE:                       WIN
              SCA LOW:                        0.1 V              (range=[-0.2, 5])
              SCA WIN:                        2.6 V              (range=[0, 5])
              SCA PUSLE SHAPING:              20 ns              (range=[5, 10, 20, 30])
              GATE IN MODE:                   NIM
              TRIGGER IN MODE:                NIM
              SYNC OUTPUT MODE:               GATE POS
              ALARM MODE:                     HEAD RATE CURR
              RATE METER ALARM THRESHOLD:     5e+07              (range=[0, 1e8])
              ALARM THRESHOLD:                6 mA               (range=[0, 25])
              BUFFER OPTIONS:                 DOUBLE FULL
              DATA FORMAT:                    DWORD DEC WBSWAP

              Axes
              ----
              low: apdthl
              win: apdwin
              hhv: apdhv

              Counters
              --------
              counts: apdcnt
              htemp: apdtemp
              hvcur: apdcurr
              hvmon: apdhvmon

EH1_EXP [5]: ascan(apdthl, 0, 0.1, 10, 1,ace, save=False)
    Out [5]: Scan(number=9, name=ascan, path=)
```

```python
Scan 9 Wed Mar 18 18:57:30 2020  eh1_exp user = opid10
ascan apdthl 0 0.1 10 1

           #         dt[s]     apdthl[V]        apdcnt   apdcurr[uA]   apdhvmon[V]   apdtemp[°C]
           0             0             0   3.97172e+07             0         421.3          26.1
           1       1.06521          0.01   1.70204e+07             0         421.3          26.1
           2       2.11069          0.02   5.88341e+06             0         421.3          26.1
           3       3.20752          0.03   1.72699e+06             0         421.3          26.1
           4       4.27623          0.04        446087             0         421.3          26.1
           5       5.32162          0.05        106288             0         421.3          26.1
           6       6.36807          0.06         23025             0         421.3          26.1
           7       7.43761          0.07          4793             0         421.3          26.1
           8       8.50213          0.08           901             0         421.3          26.1
           9       9.55439          0.09           174             0         421.3          26.1
          10       10.6151           0.1            39             0         421.3          26.1

Took 0:00:13.145863

================================= >>> PRESS F5 TO COME BACK TO THE SHELL PROMPT <<< =================================
```

--------------------------------

### Initialize BeaconObject with Configuration

Source: https://github.com/bliss/bliss/blob/master/doc/docs/beacon/beacon_object.md

Demonstrates initializing a BeaconObject with configuration data, specifying a path within the YAML and disabling hardware sharing.

```python
    # config that would be passed to __init__
    # of the contoller
    cfg = config.get("hello_ctrl")

    #initalize a BeaconObject
    params = MyParamObject(cfg, path=["something"], share_hardware=False)
```

--------------------------------

### Example Usage of Custom Power Supply Counters and Controllers

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_sampling_cnts.md

Demonstrates how to instantiate and use the custom power supply device, counter, and controller classes, including initiating scans.

```shell
hw_device = MyPowerSupplyDevice()
supplyCC = MyPowerSupplyCounterController(hw_device, "power-supply")
cnt1 = MyPowerSupplyCounter("voltage", "VLT", supplyCC, mode="SINGLE", unit='V')
cnt2 = MyPowerSupplyCounter("current", "CUR", supplyCC, mode="MEAN", unit='mA')
loopscan(10, 0.1, supplyCC) # counting with all counters of supplyCC
loopscan(10, 0.1, cnt1, cnt2) # or explicitely pass counter objects

```

--------------------------------

### Inline Docstring Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_documentation.md

This is an example of an inline docstring for a Python method, following the NumPy style guide. It details the method's purpose, parameters, potential exceptions, and return values.

```APIDOC
## move

### Description
Move axis to the given absolute/relative position

### Method
`move(self, user_target_pos, wait=True, relative=False, polling_time=None)`

### Parameters
#### Path Parameters
- **user_target_pos** (float) - Required - Destination (user units)
- **wait** (bool) - Optional - Wait or not for end of motion
- **relative** (bool) - Optional - False if *user_target_pos* is given in absolute position or True if it is given in relative position
- **polling_time** (float) - Optional - Motion loop polling time (seconds)

### Raises
- **RuntimeError**

### Returns
- **None**

### Notes
Keywords: Parameters, Raises, Returns, Notes, Attributes
```

--------------------------------

### Get Project Dependencies

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_guidelines.md

Run this command to obtain the list of project dependencies from the setup.py script.

```bash
python setup.py egg_info
```

--------------------------------

### Initialize and Control Handel System

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_mca_handel.md

Demonstrates basic initialization, starting and stopping the system, and retrieving detector and module information. Ensure the handel DLLs are in your system's PATH.

```python
from bliss.controllers.mca.handel.interface import *
init('xmap.ini')
start_system()
get_detectors()
get_modules()
get_module_type('module1')
get_channels()
start_run(0)
stop_run(0)
get_run_data(0)
```

--------------------------------

### Start Flint Independently

Source: https://github.com/bliss/bliss/blob/master/doc/docs/flint/flint_debugging.md

Launch Flint as a separate process to capture early logs. The session name 'EH1' is an example.

```shell
flint -s EH1
```

--------------------------------

### Activate Debugging Automatically in Session Setup

Source: https://github.com/bliss/bliss/blob/master/doc/docs/shell/shell_logging.md

To ensure a logger is always in debug mode when a session starts, add the `debugon()` command to the session's setup script (e.g., `test_configuration/sessions/test_setup.py`). This setting persists across shell restarts for that session.

```python
debugon(roby)
```

--------------------------------

### Launch Demo Session and Set Environment Variables

Source: https://github.com/bliss/bliss/blob/master/doc/docs/blissapi.md

Start the BLISS demo servers and launch the BLISS session. Environment variables for Beacon and Tango hosts may need to be set.

```bash
bliss-demo-servers
```

```bash
export BEACON_HOST="mycomputer:10001"
export TANGO_HOST="mycomputer:10000"
bliss -s demo_session
```

--------------------------------

### Configure Newport SMC100 Controller

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_smc100.md

Example YAML configuration for the NewportSMC100 controller. Ensure the serial URL and axis parameters match your setup.

```yaml
controller:
  class: NewportSMC100
  module: newport
  serial:
    url: tango://id00/serial_001/1
  axes:
    - name: smc1
      steps_per_unit: 1
      velocity: 25.0
      acceleration: 100.0
      tolerance: 0.001
      address: 1
```

--------------------------------

### Launch NanoBpm Device Server

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_tango_nanobpm.md

Demonstrates the steps to activate the conda environment, set the TANGO_HOST, and launch the NanoBpm device server with its instance name. Use the -? flag to see available options.

```bash
(base) user@beamline:~/bliss$ conda activate bliss
(bliss) user@beamline:~/bliss$ export TANGO_HOST=localhost:20000
(bliss) user@beamline:~/bliss$ NanoBpm -?
usage :  NanoBpm instance_name [-v[trace level]] [-nodb [-dlist <device name list>]]
Instance name defined in database for server Wago :
        NanoBpm_server
(bliss) user@beamline:~/bliss$ NanoBpm NanoBpm_server
Ready to accept request
```

--------------------------------

### Display object information using __info__() method

Source: https://github.com/bliss/bliss/blob/master/doc/docs/shell/shell_typing_helper.md

This example shows how typing an object name followed by Enter triggers the display of its __info__() method output. The output includes details like axis name, state, controller, configuration, and firmware information.

```python
DEMO [1]:  sampy
 Out [1]:  axis name: sampy
               state: READY (Axis is READY)
           controller: <bliss.controllers.motors.vscanner.VSCANNER object at 0x7fe0bf0c2fd0>
           ###############################
           Config:
             url=rfc2217://lid213.esrf.fr:28206
             class=VSCANNER
             channel letter:X
           ###############################
           ?ERR: b'OK\r'
           ###############################
           '?INFO' command:
           firmware version   : VSCANNER 01.02
           output voltage     : 0.200001 0.500205
           unit state         : READY
           ###############################
           $
           Max. number of lines: 3276
           Internal time step (microsec.): 50

           Current settings:
              LINE -0.100193 0 1 C
              SCAN 0 0 1 U
              VEL 0.001 0
              LTRIG MASK
              PTRIG MASK
              PIXEL 0 0
              HDELAY 0
           $
           ###############################
           
```

--------------------------------

### Configure Mythen Detector

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_mythen.md

Example configuration for two Mythen detectors in a BLISS setup. Ensure a __init__.yml file with 'plugin: bliss' is in the same directory.

```yaml
- name: mythen1
  module: mca.mythen
  class: Mythen
  plugin: bliss
  hostname: mythenid101
  apply_defaults: True    # Reset all the settings to their default value, it
                            applies a reset command, see dectris manual for
                            reset values
  energy: 10              # keV
  threshold: 5            # kev

- name: mythen2
  module: mca.mythen
  class: Mythen
  plugin: bliss
  hostname: mythenid102
  apply_defaults: True
  energy: 12
```

--------------------------------

### Session Configuration YAML Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/config/config_sessions.md

Defines a BLISS session named 'eh1' with a specified setup file and includes specific configuration objects.

```yaml
- class: Session
  name: eh1
  setup-file: ./eh1_setup.py
  config-objects: [pzth, simul_mca]

```

--------------------------------

### Launch I5 Device Server

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_tango_i5.md

Demonstrates the steps to activate the conda environment, set the TANGO_HOST, and launch the I5 device server with its instance name. Use the -? flag to see available options.

```bash
(base) user@beamline:~/bliss$ conda activate bliss_dev
(bliss) user@beamline:~/bliss$ export TANGO_HOST=localhost:20000
(bliss) user@beamline:~/bliss$ python tango/servers/i5_ds.py -?
usage :  i5_ds instance_name [-v[trace level]] [-nodb [-dlist <device name list>]]
Instance name defined in database for server i5_ds :
        id00
(bliss) user@beamline:~/bliss$ python tango/servers/i5_ds.py id00
Ready to accept request
```

--------------------------------

### a5scan Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/scan/scan_default.md

Demonstrates the usage of the a5scan function for a scan with 9 intervals, specifying motors, their start and stop positions, and a counting time.

```python
DEMO [2]: a5scan(m1,1,2, m2,3,4, m3,5,6, m4,7,8, m5,8,9, 9, 0.1)

Scan 2 Fri Oct 26 16:07:08 2018 /tmp/scans/demo/
a5scan m1 1 2 m2 3 4 m3 5 6 m4 7 8 m5 8 9 10 0.1

     #      dt[s]      m1      m2       m3       m4       m5      simct1
     0          0       1       3        5        7        8    0.038648
     1   0.432173    1.11    3.11     5.11     7.11     8.11    0.022345
     2   0.850866    1.22    3.22     5.22     7.22     8.22    0.119345
     3    1.25996    1.33    3.33     5.33     7.33     8.33     1.06995
     4    1.74734    1.44    3.44     5.44     7.44     8.44     3.45354
     5    2.16594    1.56    3.56     5.56     7.56     8.56     3.47793
     6    2.57817    1.67    3.67     5.67     7.67     8.67     1.01595
     7    2.98574    1.78    3.78     5.78     7.78     8.78    0.128783
     8     3.4303    1.89    3.89     5.89     7.89     8.89    0.073870
     9    3.84454       2       4        6        8        9    0.019919

Took 0:00:05.226827
 Out [2]: Scan(name=a5scan_2, run_number=2, path=/tmp/scans/demo/)
```

--------------------------------

### Access Beacon Objects

Source: https://github.com/bliss/bliss/blob/master/doc/docs/bliss/bliss_as_library.md

Retrieve specific objects configured in Beacon using the `config.get` method. This example shows how to get a 'transfocator_simulator' object and print its information.

```python
>>> transfocator = config.get('transfocator_simulator')
>>> print(transfocator.__info__())

```

--------------------------------

### Scan Queue Hook Execution Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_session_hooks.md

Demonstrates the output of scan queue hooks during a scan's lifecycle, showing messages for scan start, completion, or failure.

```python
DEMO [2]: ct()
---------> ct 1.0 1 started
INFO: starting Scan(name=ct, path='not saved')

ct:      state  elapsed
          DONE       1s

---------> ct 1.0 1 done
                diode1  =       49.8085      (      49.8085       /s)  simulation_diode_sampling_controller
                diode2  =       50.8401      (      50.8401       /s)  simulation_diode_sampling_controller
         Out [9]: Scan(name=ct, path='not saved')
```

--------------------------------

### Create Demo Environment using Make

Source: https://github.com/bliss/bliss/blob/master/doc/docs/installation/installation.md

Use `make` to create the demo environment, including BLISS, LIMA, and optionally an ODA environment. Requires git, make, and conda.

```bash
git clone https://gitlab.esrf.fr/bliss/bliss
cd bliss/

make demo_env [NAME=bliss_dev] [LIMA_NAME=lima_env] [LIMA2_NAME=lima2_env]

# or if online data processing is wanted

make demo_with_oda_env [NAME=bliss_dev] [LIMA_NAME=lima_env] [LIMA2_NAME=lima2_env] [ODA_NAME=oda_env]
```

--------------------------------

### Switch to a new instance and update parameters

Source: https://github.com/bliss/bliss/blob/master/doc/docs/beacon/beacon_settings.md

Illustrates how to switch to a different named instance within the ParametersWardrobe and then update its parameters. This allows managing distinct sets of configurations.

```python
dress.switch("Night dress")
dress.body = 'Jacket'
dress.feet = "Nice shoes"
dress.legs = "Black trousers"
```

--------------------------------

### Access Configured Test Devices

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_testing.md

In a test session, devices that depend on Tango servers can be accessed via the 'config' object. This example shows how to get a 'lima_simulator' device.

```python
TEST_SESSION[1]: limaDev = config.get("lima_simulator")
```

--------------------------------

### Get Acquisition Object Implementation Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_counters.md

Implement the `get_acquisition_object` method to return the appropriate acquisition object based on trigger mode. Ensure correct handling of acquisition parameters.

```python
def get_acquisition_object(self, acq_params, ctrl_params, parent_acq_params):
    """
    Return the acquisition object instance that should be used during a scanning procedure.
    The choice can be different depending on the received parameters.

    args:
        - `acq_params`: parameters for the acquisition object (dict)
        - `ctrl_params`: parameters for the controller (dict)
        - `parent_acq_params`: acquisition parameters of the master (if any)

    return: an AcquisitionObject instance
    """

    trigger_mode = acq_params.pop("trigger_mode", "SOFTWARE")
    if trigger_mode == "SOFTWARE":
        return MyAcquisitionObject_SW(self, **acq_params)
    elif trigger_mode == "HARDWARE":
        return MyAcquisitionObject_HW(self, **acq_params)
    else:
        raise ValueError(f"Unknown trigger mode {trigger_mode}")
```

--------------------------------

### Open Slits and Scan Beam

Source: https://github.com/bliss/bliss/blob/master/doc/docs/bliss/bliss_flint.md

Example of opening slits and scanning the beam using ascan command, with data displayed in the beamviewer.roi_counters. This demonstrates basic scan and data visualization setup.

```python
mv(slit_vertical_gap, 1)
ascan(slit_vertical_offset, -5.0, 5.0, 20, 0.1, beamviewer.roi_counters)
```

--------------------------------

### Hexapode Server Supervisor Startup Script Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_esrf_hexapode.md

Example of a supervisor startup script for the hexapode Tango device server. This configuration specifies the programs to run, their environment variables, and logging settings.

```ini
[group:tango]
programs=Hexapode_01, ...
priority=100

[program:Hexapode_01]
command=bash -c ". /users/blissadm/bin/blissenv && exec Hexapode Hexa1"
environment=TANGO_HOST="idXX:20000",HOME="/users/blissadm"
user=blissadm
startsecs=2
autostart=true
redirect_stderr=true
stdout_logfile=/var/log/%(program_name)s.log
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_capture_maxbytes=1MB

```

--------------------------------

### Get Global Status of Maestrio Controller

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_maestrio.md

Retrieves basic information about encoder channels, loaded programs, and sequencer state. No specific setup is required beyond having a connected Maestrio board.

```text
FSCANTEST [11]: maestrioeu6
      Out [11]: MAESTRIO board: MAESTRIO - 0.1
                TCP COMMAND:  host=maestrioeu6 port=5000

                CHANNELS:
                    C1 :   2.000000 - QUAD
                    C2 : 32160.000000 - QUAD
                    C3 :     UNUSED - UNUSED
                    C4 :     UNUSED - UNUSED
                    C5 :     UNUSED - UNUSED
                    C6 :   0.000000 - QUAD
                PROGRAMS UPLOADED:
                    FSCAN        : uploaded on 24/06/14 16:36:39
                    FTIMESCAN    : uploaded on 24/06/13 17:09:39
                SEQUENCERS:
                    SEQ1 :     STOP #ACQ       - RES: ALL
                    SEQ2 :     STOP UNKNOWNPROG - RES: NONE
                    SEQ3 :   NOPROG None       - RES: NONE
```

--------------------------------

### YAML Example Using Object References

Source: https://github.com/bliss/bliss/blob/master/doc/docs/beacon/beacon_db.md

Shows how to reference other objects within a configuration using the '$' prefix. This allows for modularity and avoids repetition.

```yaml
- name: gslits    # a CalcController using referenced axes as inputs
  class: slits
  axes:
    - name: $ssf           # a reference to existing 'ssf' axis
      tags: real front
    - name: $ssb           # a reference to existing 'ssb' axis
      tags: real back
    - name: sshg           # the calculational axis created by this CalcController
      tags: hgap
      tolerance: 0.04
```

--------------------------------

### Serve Local BLISS Documentation

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_documentation.md

Starts the mkdocs server to view the local documentation. Access it via http://localhost:8000.

```bash
cd <bliss.git directory>/doc/
mkdocs serve
```

--------------------------------

### Execute step scan

Source: https://github.com/bliss/bliss/blob/master/doc/docs/scan/scan_default.md

Example execution of the step_scan function. This demonstrates calling the function with motor, start, stop, step size, count time, and counters, and shows the resulting scan output.

```python
TEST_SESSION [42]: s = step_scan(roby, 0, 1, 0.2, 0.1, diode)
```

--------------------------------

### Instantiate and Use MyController

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_maplog_controller.md

Demonstrates the instantiation of MyController, calling its work method to send data, and disabling debug logging.

```python
DEMO [96]: mycontroller = MyController()
Setting session.ctrlers.MyController to show debug messages
Setting session.ctrlers.MyController.MyConnection.socket to show debug messages
Setting session.ctrlers.MyController.MyConnection to show debug messages
Setting session.ctrlers.MyController.socket to show debug messages
DEBUG 2019-07-05 10:00:00,000 session.controllers.MyController: HI, I am born

DEMO [97]: mycontroller.work()
DEBUG 2019-07-05 10:00:08 session.controllers.MyController.MyConnection.socket:
 Received from www.google.com bytes=547 b'HTTP/1.1 301 Moved Permanently\r\n
 Location: http://www.google.com/\r\nContent-Type: text/html; charset=UTF-8\r\n
 Date: Fri, 05 Jul 2019 07:59 GMT\r\nExpires: Sun, 04 Aug 2019 07:59 GMT\r\n
 Cache-Control: public,
 max-age=25920\r\nServer: gws\r\nContent-Length: 219\r\nX-XSS-Protection: 0\r\n
 X-Frame-Options: SAMEORIGIN\r\nConnection: close\r\n\r\n<HTML><HEAD>
 <meta http-equiv="content-type" content="text/html;charset=utf-8">
 <TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>

The document has moved\n <A HREF="http://www.google.com/">here</A>.\r\n
 </BODY></HTML>\r\n'

DEMO [98]: debugoff(mycontroller)
Setting session.ctrlers.MyController to hide debug messages
Setting session.ctrlers.MyController.MyConnection.socket to hide debug messages
Setting session.ctrlers.MyController.MyConnection to hide debug messages
Setting session.ctrlers.MyController.socket to hide debug messages

DEMO [99]: mycontroller.work()
DEMO [100]:
```

--------------------------------

### Register Global Scan Metadata Generator

Source: https://github.com/bliss/bliss/blob/master/doc/docs/data/data_scan_metadata.md

Register metadata generators in the BLISS session setup to automatically fill the `scan_info` dictionary for every scan. This example adds the position label of a Multiple Position object under the 'Instrument' category.

```python
from bliss.scanning import scan_meta

scan_meta_obj = scan_meta.get_user_scan_meta()

def generate_label(scan):
    return {"position_label": mp.position}

# mp is a BLISS Multiple Position object
scan_meta_obj.instrument.set(mp, generate_label)
```

--------------------------------

### YAML Example with Basic Items

Source: https://github.com/bliss/bliss/blob/master/doc/docs/beacon/beacon_db.md

Demonstrates basic YAML key-value pairs with different data types like integers, lists, and strings. Comments are supported in YAML.

```yaml
key_1: 1               # float value
key_2: ['a', 'b', 'c'] # list value
key_3: a string        # string value
```

--------------------------------

### Install Data Client Dependencies

Source: https://github.com/bliss/bliss/blob/master/scripts/scanning/withoutbliss/README.md

Installs the necessary dependencies for the blissdata client. Activate the virtual environment before installation.

```bash
python -m venv $HOME/virtualenvs/monitor_env
source $HOME/virtualenvs/monitor_env/bin/activate

pip install blissdata
```

--------------------------------

### Install Miniforge

Source: https://github.com/bliss/bliss/blob/master/scripts/scanning/withoutbliss/README.md

Download and install Miniforge, a minimal installer for conda, if not already present. This is a prerequisite for managing conda environments.

```bash
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh -b -p $HOME/miniforge3

source $HOME/miniforge3/etc/profile.d/conda.sh
conda config --add envs_dirs $HOME/virtualenvs/
```

--------------------------------

### Start Beacon Server with Custom Redis Configuration Files

Source: https://github.com/bliss/bliss/blob/master/doc/docs/beacon/beacon_install.md

Specify custom Redis configuration files for both the settings and data servers using --redis-conf and --redis-data-conf arguments. This allows for advanced Redis settings customization.

```shell
beacon-server --db-path=~/local/beamline_configuration \
              --redis-port=25001 \
              --redis-data-port=25002 \
              --redis-conf=~/local/redis.conf  \
              --redis-data-conf=~/local/redis_data.conf
```

--------------------------------

### Install Documentation Requirements (Alternative)

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_documentation.md

Installs documentation requirements using a conda file. This is an alternative to pip install with extras.

```bash
cd <bliss.git directory>
conda install --file requirements-doc.txt
```

--------------------------------

### FEMTO Configuration Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_femto.md

Example YAML configuration for the FEMTO controller, specifying device names, WAGO controller addresses, and signal mappings for offset, gain, range, and overload.

```yaml
plugin: bliss
class: femto
list:
  - name:     femto1
    wago:     idxx/wcidxxc/tg
    type:     dlpca
    sig_offset:   f1oset  # (1)  750-556
    sig_gain:     f1gain  # (3)  750-519
    sig_range:    f1hilo  # (1)  750-519
    sig_overload: f1ovl   # (1)  750-414
    sig_coupling: dc
    # possible other values could be:
    # sig_coupling: f1acdc
    # sig_coupling: dc
    # sig_coupling: ac
    # sig_bandwidth: f1bw10 f1bw1

  - name: femto2
    wago: $wcid99d
    type: dlpca
    sig_gain:     f2gain
    sig_range:    f2hilo
    sig_overload: f2ovl

```

--------------------------------

### Install Non-Python Dependencies for Beamline Environment

Source: https://github.com/bliss/bliss/blob/master/doc/docs/installation/installation.md

Install non-Python dependencies and specify the desired Python version using `conda install` with a requirements file.

```bash
# Install non-python dependencies (and specify the python version wanted)
conda install --file conda-requirements.txt python=3.*
```

--------------------------------

### Example `__init__.yml` File Content

Source: https://github.com/bliss/bliss/blob/master/doc/docs/beacon/beacon_db.md

Content of an `__init__.yml` file, used for defining inherited configuration values within a directory.

```yaml
familly: addams
plugin: generic
```

--------------------------------

### Controller YAML Configuration Example

Source: https://github.com/bliss/bliss/blob/master/doc/docs/dev/dev_write_ctrl_intro.md

This YAML snippet demonstrates how to configure a controller, including its name, class, plugin, and a list of named subitems like counters.

```yaml
- name: controller_name
  class: ControllerClass
  plugin: generic

  counters:
    - name: cnt_1
    - name: cnt_2
```

--------------------------------

### Install Mamba in base environment

Source: https://github.com/bliss/bliss/blob/master/doc/docs/controllers/config_xia_mca.md

Installs the Mamba package manager into the base conda environment. Mamba is a faster alternative to conda for package installation.

```bash
conda activate base
conda install -y mamba -c conda-forge
```