==================================
How to simulate IDCP on a Linux PC
==================================

.. note::
   Currently (Feb. 2026) idcp cannot be built from public repositories, so the
   following recipe only works at the Helmholtz-Zentrum Berlin. In the future
   it will be possible to build everything from public repositories.
   See also :doc:`Sites <sites>`.

Overview
--------

We build an undulator emulation, a digital twin, and and the undulator control program, idcp.

Since both communicate by 
`CAN bus <http://en.wikipedia.org/wiki/CAN_bus>`_, we can use the Linux
`Virtual CAN Driver <https://docs.kernel.org/networking/can.html#the-virtual-can-driver-vcan>`_
to run both applications on a single Linux PC without a physical CAN Bus interface.

All functions, even speed control, can be tested on a single Linux PC.

We create these directories:

VENV
  The Python virtual environment where extra Python applications and scripts
  and some Perl scripts and libraries are installed.

SUMO
  The `sumo <https://epics-sumo.sourceforge.io/>`_ directory that contains the
  sumo database and all
  `EPICS <http://www.aps.anl.gov/epics/about.php>`_ device supports.

unisim
  The :doc:`unisim` application that implements the simulation of the
  undulator, a digital twin.

idcp
  The idcp application, the undulator control application.

Prerequisites (incomplete)
--------------------------

- Development packages: gcc, g++, make, Perl, Python
- Version control: darcs, mercurial, git
- Access to http://repo.acc.bessy.de
- sudo rights on your local machine

unisim
------

.. note::
   For details on unisim see :doc:`unisim`.

Check out with::

  hg clone http://repo.acc.bessy.de/hg/unisim

Initialize::

  cd unisim
  ./configure.sh --venv ../VENV --sumodir ../SUMO -c custom-HZB.sh --system-site-packages

Build::
  
  ./build.sh

Note: The "configure.sh" call initializes a Python Virtual Environment as
well as a SUMO directory.

Change to parent directory::

  cd ..

Important: Activate Python Virtual Environment::

  source VENV/bin/activate

idcp
----

Check out with::

  hg clone http://repo.acc.bessy.de/hg/idcp/idcp

Change directory::

  cd idcp

Configure::

  ./idcp-configure --arch linux --no-repo --venv ../VENV --system-site-packages

Configure shell::

  source ./setenv.sh

Build supports::

  nice sumo build utilize --makeflags "-sj" --progress

Build application::

  nice make -sj

Configure virtual CAN Bus
-------------------------

This uses two utility scripts from the 'socan' device support.

Note: You need to have sudo rights for this.

In the idcp directory enter::

  source ./setenv-socan.sh
  init-can.sh -d vcan -p 0 5
  link-vcan-devices.sh link 2 4

Start unisim
------------

In a new terminal in the unisim directory run::

  ./start-ioc.sh --sudo

.. note::
   Possibly start the script above with option "--ip IPADDRESS" if you host has
   more than one network interface.

Start idcp
----------

In a new terminal in the idcp directory run::

  scripts/start-ioc.sh --sudo --local idcp98

.. note::
   Possibly start the script above with option "--ip IPADDRESS" if you host has
   more than one network interface.

Initialize undulator
--------------------

In another terminal window in the "idcp" directory run::

  source setenv.sh 
  source setenv-epics-base.sh 
  source setenv-iddb.sh 
  BOOT.sh U2IV -V 150 -H 0 --no-cioc reset

.. note::
   The message "'healthy' flag for at least one axle is not set" is not an
   error here, this is a small difference between the simulation and the real
   undulator.

Start DM2K
----------

Note: You must have "DM2K" installed on you local host.

DM2K source can be downloaded here:

https://github.com/goetzpf/DM2K-HZB

In a new terminal in the idcp directory enter::

  scripts/dm2k-local.sh U2IV

Use
---

You can now do everything on the simulated undulator you could do in the real
undulator. 

For example:

- Enter '100' at 'Dest:'
- Below change the button from 'STOP' to 'START'.
- On the right side of this button click on 'exec'.

You should now see that the undulator moves.

Your find further documentation on the user interface at
:doc:`idcp_user_interface`.