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:
; 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 TIMEPIX4init: The initialization file, in addressable datatop#/bot#: Timepix4 specific top and bottom channel to control board channel mapping. For exampletop0=0tells 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 beTOP,CENTERorBOTTOM.
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 valuecur_vdda: The analog current measurementcur_vdd: The digital current measurementext_adc: Path to the ADC attached tot heDAC_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:
; 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:
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:
nano control.ini
Now we are going to write a redirect to a file named carrier.ini, paste in the following configuration items:
[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:
nano carrier.ini
And copy & paste the following configuration:
; 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:
nano peripheral.ini
and add a new carrier directive:
[:/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.
nano carrier_prpl.ini
And paste the following configuration:
; 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:
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_<timestamp>.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:
reboot