.. _Carrier board configuration: Carrier board configuration =========================== When a new carrier board needs to be commissioned, it first requires the EEPROM to be filled with a configuration. This configuration consists of a single ZIP file containing multiple configuration files. The ZIP file contains a single mandatory file called ``carrier.ini``. This file contains the following items: - Version and type of the carrier board - Serial number - Type and number of pixelchips (now only single Timepix4) - Mapping of pixelchip outputs to chipboard channels Optionally, but common, is the inclusion of a ``carrier_prpl.ini`` file. This file contains all carrier-board specific I2C devices, such as the ADC, temperature sensor etc... This is the same format as for ``peripherals.ini`` contained in ``/etc/control`` on the control board. Editing the configuration ------------------------- Configuring a new carrier board can only be done using root shell access to the control board Linux. Once logged in there is a tool call ``promtool`` which will help you set up the new carrier board. At start-up ``promtool`` will stop the running ``control`` application as it will otherwise interfere with the operation. At start-up you will be presented with the ``promtool`` menu:: promtool - carrier board EEPROM tool Part of the Spidr4 project !! Use with care! May crash the control application if you are not sure what you are doing! Current files for EEPROM image: - carrier_prpl.ini - carrier.ini Please select what you want to do 1: Open shell to create / remove / edit files 2: (Over)write with default files (carrier.ini and carrier_prpl.ini) 3: Write to EEPROM Or leave empty to exit > The menu may deviate somewhat the first time, as the EEPROM will be empty. The first time you must select option 2. This will put a default carrier and peripheral file in your EEPROM workspace. Once complete you can choose option 1 to edit the files. The first time this will be required in order to set the serial number. Choosing 1 will open a shell (``bash``) in a temporary folder having all the files which will be put into the ZIP file and uploaded to the EEPROM once done. You can use one of the supplied editors (``nano`` and ``vi``) to edit any of the files on the carrier EEPROM. The following shows the content of the EEPROM:: Please select what you want to do 1: Open shell to create / remove / edit files 2: (Over)write with default files (carrier.ini and carrier_prpl.ini) 3: Write to EEPROM Or leave empty to exit >1 Please use the shell to create/edit/remove files from the EEPROM directory. Exit the shell to return to this tool root@ctrl2019_1:/var/volatile/tmp/tmpcLFB0h/eeprom# ls carrier.ini carrier_prpl.ini root@ctrl2019_1:/var/volatile/tmp/tmpcLFB0h/eeprom# The carrier.ini contains the main carrier configuration. You should add a serial to the carrier.ini and select the correct initialization file. An example carrier board configuration looks like this: .. code:: ini ; Board configuration file [board] type=NIKHEF_TPX4_V1 serial=3 ; Chip configuration [chip0] ; Chip-type.. TIMEPIX4, MEDIPIX4, etc... type=TIMEPIX4 ; Chip revision, e.g. timepix 4.1 this is 1, timepix 4.3 this is 3 revision=1 ; Start up script ; The following configurations exist: ; - Timepix 4.2 init: /etc/control/timepix4v2_carrier2.adat ; - Timepix 4.1 init: /etc/control/timepix4v1_carrier2.adat ; - Timepix 4.0 init: /etc/control/timepix4v0_carrier1.adat init=/etc/control/timepix4v2_carrier2.adat ; Physical TPX4 to board channel mapping top0=0 top1=1 top2=2 top3=3 top4=4 top5=5 top6=6 top7=7 bot0=8 bot1=9 bot2=10 bot3=11 bot4=12 bot5=13 bot6=14 bot7=15 dac_out=BOTTOM ; Mapping of chip specific information variables ; for display ; ; Currently: ; temp : Temperature variable ; cur_vdda : Analog current ; cur_vdd : Digital current [chip0_info] temp=carrier/temp/temperature cur_vdda=carrier/vdda/current cur_vdd=carrier/vdd/current ext_adc=carrier/adc/volt First there is the ``[board]`` directive, which configures board specific information. This contains the type of the board, for now ``NIKHEF_TPX4_V1`` and a serial number. This should match the value on the PCB. Second there should be one or more ``[chip#]`` directives, where ``#`` is an integer. Each ``#``, 0 based, corresponds to the logical position of the chip to the control board. At the moment only a single chip is supported, and thus it wil be ``[chip0]``. The chip section contains the following items: - ``type``: The type of the chip, for now TIMEPIX4 - ``init``: The initialization file, in addressable data - ``top#`` / ``bot#``: Timepix4 specific top and bottom channel to control board channel mapping. For example ``top0=0`` tells the control application that Timepix channel 0 is mapped to control board channel 0. - ``dac_out``: The pin to which the DAC_OUT is connected to the carrier board ADC channel. This can be ``TOP``, ``CENTER`` or ``BOTTOM``. Additionally there is an optional value: - ``fake_id``: This will set a fake chip ID on this chip. This will only be used if chip ID is 0. Finally there is a ``[chip#_info]`` section containing meta-information. Specifically which peripherals can be used for monitoring specific physical quantities of the chip. This can currently contain the following peripheral paths to specific sensor values: - ``temp``: The carrier board temperature sensor value - ``cur_vdda``: The analog current measurement - ``cur_vdd``: The digital current measurement - ``ext_adc``: Path to the ADC attached tot he ``DAC_OUT`` **Note:** The above peripheral sensor paths are all prefixed with ``carrier/``. When looking at the ``carrier_prpl.ini`` you will not see these prefixes in the names of the peripherals. This is because the prefix is automatically added for all peripherals on the carrier board such to distinguish them from the ones on the control board. ``carrier_prpl.ini`` contains the carrier peripheral configuration. It looks like this: .. code:: ini ; Peripherals ; For carrier v2 (comment for carrier v3) [pressure] part=mpl3115a2 addr=0x60 [humid] part=si7021 addr=0x40 ; Uncomment for carrier v3 ; [humid_pressure] ; part=bme280 ; addr=0x76 [temp] part=tmp102 addr=0x48 [vdd] part=ina219 addr=0x45 [vdda] part=ina219 addr=0x41 [adc] part=mcp3021 addr=0x4d ref_volt=3.3 Carrier v1 and v2 had a separate humidity and temperature sensor. However, for v3 this has all been combined in the BME280 which additionally also provides pressure. Once completed save all files, exit the shell and choose option 3:: Please select what you want to do 1: Open shell to create / remove / edit files 2: (Over)write with default files (carrier.ini and carrier_prpl.ini) 3: Write to EEPROM Or leave empty to exit >3 Writing 1094 byte(s) to EEPROM (max=8192) Current files for EEPROM image: - carrier_prpl.ini - carrier.ini Once done, exit the application, the control application should be automatically restarted. If not try to start it using ``control-init start``. You can also check the display whether or not the chip has been recognized and the currents and temperature are known. Using carrier board without an EEPROM ------------------------------------- By default the control application expects a carrier board to have an EEPROM at a specific i2c address. This EEPROM contains a ZIP archive which is expected to contain (at least) one ``carrier.ini`` file, and one ``carrier_prpl.ini`` file. When the board can not contain an EEPROM it is possible to configure a pixel chip configuration on the local file system. .. note:: All changes will be made in the persistent section of the SD card. This special mount point located under ``/localstore`` will not be overwritten when updating the SD card with a new firmware image. Logging in to the board ~~~~~~~~~~~~~~~~~~~~~~~ Login using as root on the board (note that this may change in the future). You can ask the spidr4 team for the root password of your board given the device serial. For this tutorial we will be using the ``nano`` editor, but it is also possible to use ``vi``, or to upload the files to the system using ``scp``. Navigate to the persistent spidr4 configuration directory: .. code:: bash cd /localstore/.spidr4 .. attention:: **For the rest of this tutorial we assume you are located in the** ``/localstore/.spidr4`` **directory.** Changing the default carrier.ini location ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Step one requires you to redirect the loading of ``carrier.ini`` from the EERPOM to the persistent section of the SD. This requires the adding of an overlay file named ``control.ini`` in this persistent section. The overlay file is loaded after the actual ``control.ini`` file and amends or modifies the existing configuration. To create/modify the control overlay ini file, open nano: .. code:: bash nano control.ini Now we are going to write a redirect to a file named ``carrier.ini``, paste in the following configuration items: .. code:: ini [carrier_config] configfile=/localstore/.spidr4/carrier.ini ; eeprom_addr=0 disabled attempting to load EEPROM eeprom_addr=0 This will overwrite the original configuration, and make the control application load the configuration from ``/localstore/.spidr4/carrier.ini``. Save the file and exit the editor. .. note:: Free to modify the filename of ``carrier.ini`` to have the name of your carrier board. This is specifically important if you are going to use multiple different boards. So, we assume the name to be ``carrier.ini``, but feel free to change it to ``carrier_our_tpx4_board_v1.ini`` or something but you should then also update the ``control.ini`` ``[carrier_config]`` section to point to that file. Adding the new carrier.ini ~~~~~~~~~~~~~~~~~~~~~~~~~~ Next we will create the ``carrier.ini``. This file describes the carrier board, excluding the peripherals. So, without further ado lets, create the carrier.ini by executing the next shell command: .. code:: bash nano carrier.ini And copy & paste the following configuration: .. code:: ini ; Board configuration file [board] ; replace YOURINSTITUTE YOURBOARD and YOURVERSION ; with the name of your institute, the name of the board ; and the version/revision number of the board. ; E.g. for Nikhef it could be NIKHEF_TPX4_V2 type=YOURINSTITUTE_YOURBOARD_YOURVERSION ; Normally this is part of the serial on the chip board. But as this file ; is located on the SD, a serial makes no sense. Just make it 0 serial=0 ; Chip configuration [chip0] ; Chip-type.. TIMEPIX4, MEDIPIX4, etc... type=TIMEPIX4 ; Chip revision, e.g. timepix 4.1 this is 1, timepix 4.2 this is 2 revision=2 ; Start up script ; The following configurations exist: ; - Timepix 4.2 init: /etc/control/timepix4v2_carrier2.adat ; - Timepix 4.1 init: /etc/control/timepix4v1_carrier2.adat ; - Timepix 4.0 init: /etc/control/timepix4v0_carrier1.adat init=/etc/control/timepix4v2_carrier2.adat ; Physical TPX4 to board channel mapping ; This describes how TPX4 pins are mapped to the logical spidr4 channels top0=0 top1=1 top2=2 top3=3 top4=4 top5=5 top6=6 top7=7 bot0=8 bot1=9 bot2=10 bot3=11 bot4=12 bot5=13 bot6=14 bot7=15 ; Which part the DAC out is attached to. This will be used for ; DAC scans using an external ADC. dac_out=BOTTOM ; Mapping of chip specific information variables ; for display and monitoring ; ; Note that this section is dependent on the boards peripherals. ; You can comment the lines if your board does not contain ; this information. ; ; Currently: ; temp : Temperature variable ; cur_vdda : Analog current ; cur_vdd : Digital current ; ext_adc : External ADC voltage [chip0_info] temp=carrier/temp/temperature cur_vdda=carrier/vdda/current cur_vdd=carrier/vdd/current ext_adc=carrier/adc/volt Read each line carefully and make modifications where required. Once done, save the file and exit the editor. Overlaying the peripheral file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Now we have done all required basic configuration to load and use the carrier board. However, this does not yet cover possible carrier board i2c peripherals. This is what we will be doing next. If you do not have any i2c peripherals you can skip this section and the next. Create a new peripheral overlay file. We will need to modify the loading of the carrier board peripheral file to the user section: .. code:: bash nano peripheral.ini and add a new carrier directive: .. code:: ini [:/localstore/.spidr4/carrier_prpl.ini] bus=i2c1 mux_ref=_board_mux mux_idx=0 namespace=carrier This special directive causes file called ``/localstore/.spidr4/carrier_prpl.ini`` to be included in the peripheral configuration. Again note you are free to change the filename if you are going to have multiple different carrier board types. .. note:: The namespace will be prefixed before each peripherals name. E.g. a fictional luminiferous aether sensor device named ``aether_sense1`` will show up as ``carrier/aether_sense``, and its flux can be access by the name ``carrier/aether_sense/flux``. Once done, save the file and exit the editor. Adding the carrier_prpl.ini ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The last required addition is the peripheral file itself. This file describes all the peripherals on the carrier board. Once configured they can be accessed through the peripheral gRPC interface and seen by the monitoring application. .. code:: bash nano carrier_prpl.ini And paste the following configuration: .. code:: ini ; Peripherals [humid_pressure] part=bme280 addr=0x76 [temp] part=tmp102 addr=0x48 [vdd] part=ina219 addr=0x45 [vdda] part=ina219 addr=0x41 [adc] part=mcp3021 addr=0x4d ref_volt=3.3 Feel free to add and remove devices which are present or not. Once everything is ready you can save and exit. Last steps ~~~~~~~~~~ Once done, the control application needs to be restarted. Currently it is not possible to use the daemon script for this, so we kill the control app manually and start it in the console. This is handy for debugging configuration problems, as any grave errors will immediately be evident in the logging: .. code:: bash killall control control If a pixelchip is populated it should be stated that it `found 1 pixelchip(s)` somewhere in the sea of logging. Note that the logging is also stored in ``/var/log`` with the name ``control_.log``. Once running, check if you can reach the pixel chip by executing a number of example scripts. If everything works as intended, close the control application using `control+C`. Finally restart the spidr4 by issuing the reboot shell command: .. code:: bash reboot