Quick Tour

Home

First Try Using Kinoko

There are several sample Kinoko scripts in the directory "kinoko/local/samples". In this quick tour, we will use a software-simulated CAMAC ADC as our example.

tinyKinoko (Tcl/Tk version)

"tinyKinoko" is a light-weight DAQ program consisting of only one process.

screenshot (large) (PNG 76kB)
How To Use tinyKinoko
  1. Change directory to "samples", and launch tinyKinoko.
    % cd kinoko/local/samples
    % tinykinoko-tcltk
    

  2. Set the fields in the Configuration section of the window to the following.
    Readout Script (.kts): SimCamacAdc.kts
    Data File (.kdf): test01.kdf
    # of events: 1000

  3. Click the [Start] button in the Acquisition section. tinyKinoko will begin data acquisition. It will finish in about ten to twenty seconds.

  4. If you click the [Dump] button in the Dump section, tinyKinoko will launch an editor and show the data taken. If you click the [Summary] button, tinyKinoko will display a statistical summary such as the number of events and their mean value.

  5. If ROOT is available, tinyKinoko can display a histogram or graph plot. To draw histograms, fill in fields Min, Max, and Bins in the Histogram section with 0, 4096, and 128 respectively. Then click the [Generate Script] button. A ROOT script for the data taken will be automatically generated. Click [Draw] to start ROOT.

smallKinoko

"smallKinoko" is a DAQ system that consists of several processes on a single computer. Real-time data display is available on this system. Network-distributed parallel processing is not available since the system works on a single computer.

screenshot (large) (PNG 69kB)
How To Use smallKinoko
  1. Change directory to "samples" and launch smallKinoko.
    % cd kinoko/local/samples
    % smallkinoko
    

  2. After a while, several windows will pop up. Look for one titled SmallKinoko Control Panel in the title bar and set the fields as follows.
    Readout Script (.kts): SimCamacAdc.kts
    View Script (.kvs): CamacAdc.kvs or
    CamacAdc-Fancy.kvs
    Data File (.kdf): (leave this field empty)

  3. Click the [construct] button on the bottom of the control panel.

  4. Make sure that there is no error or panic message in the "logger" window (marked with E or P at the beginning of each line). The "logger" displays log messages from each component. If you find E or P messages, click the [quit] button in the control-panel window and the system will be shut down. Otherwise, click [start] to start data acquisition.

  5. When you get bored, click [stop] to stop data acquisition, then click [quit] to shout down the system.

Preparing to Use Kinoko

Before taking data, you need to make a directory where you will store your work. You can make it anywhere. If you prefer to make it under the kinoko tree, use the directory kinoko/local, which is intended for experiment-specific files. In this example, we make a directory trial01 under kinoko/local and will do all the work there.

  % cd kinoko/local
  % mkdir trial01
  % cd trial01

Using tinyKinoko

"tinyKinoko" is a light-weight DAQ program consisting of only one process. Scripting (readout script) is available on this system, but real-time data display is not. Since the script used by this program is common to all Kinoko software, and tinyKinoko is a tiny system that is easy to use, it will be particularly useful for early-stage DAQ system testing.

In this example, we use an RPC-022 CAMAC ADC (Rinei) with a CC/7x00 CAMAC controller (Toyo), and read the ADC data in ch-0, 1, 2, and 3. It is assumed that the ADC is installed in station 3, and that the ADC issues a LAM signal after the ADC receives a gate input.

Write a file with the following contents and save it as trial01.kts. The line numbers are for later explanation so do not include them.

 1: /* trial01.kts */
 2: 
 3: datasource Trial01
 4: {
 5:     int station_number = 3;
 6:     long readout_channels = #0..#3;
 7:     
 8:     CamacCrate crate;
 9:     CamacController controller("Toyo-CC7x00");
10:     CamacModule adc("Rinei-RPC022");
11:     
12:     crate.installController(controller);
13:     crate.installModule(adc, station_number);
14:     
15:     on trigger(adc) {
16:         adc.read(readout_channels);
17:         adc.clear();
18:     }
19: }
Although the syntax has been slightly extended, it is basically similar to the syntax of C++, so C++ programmers should find it easy to understand. Details are described later in the Usage section.

With the ktscheck utility, you can check for script errors.

% ktscheck Trial01.kts
Following the UNIX tradition, there will be no error messages if there aren't any. If there is an error, a message will appear with the line number (the following is an example of typing "Rinei-RPC220" instead of "Rinei-RPC022").
%ktscheck Trial01.kts
script exception: line 10: unknown camac module: Rinei-RPC220
%
Now that you have checked for errors, let's take data with this script. Start tinyKinoko as follows:
% tinykinoko trial01.kts trial01.kdf 100
The second argument is the output data file name, and the third is the number of events to be read out. Before starting the program, make sure that signals are fed into the ADC gate (if an adequate signal source is not available, use a 10Hz to 100Hz clock instead).

Is everything okay? If it works correctly, the data file trial01.kdf will be created. If an error message script exception appears, the script has errors: compare the script with the former example carefully. If the system froze without any messages, check the following things:

Reading Data Files

The data file (trial01.kdf) is a binary-file which contains various information about the setups and so on. The easiest way to convert the file into ASCII text is to use the kdfdump utility as follows:
% kdfdump trial01.kdf -
This command will generate an output like the following:
# Creator: tinykinoko
# DateTime: 2002-05-17 04:14:41 JST
# UserName: sanshiro
# Host: shimeji.awa.tohoku.ac.jp
# Directory: /home/sanshiro/work/kinoko/local/trial01
# ScriptFile: Trial01.kts

adc 0 1475
adc 1 215
adc 2 1144
adc 3 251

adc 0 295
adc 1 1508
adc 2 1353
adc 3 2251

adc 0 201
adc 1 837
adc 2 1071
adc 3 1414
(lines omitted below)
Lines that starts with the # character are comments. Data lines consists of the section name, address, and data, from left to right. In this example, the section name is a module name assigned in the readout script (line 10), and the address is the ADC channel. A blank line is inserted at the end of every event.

By using the "kdftable" utility, the output can be put in a format that might be convenient for offline analysis. (However, some data types cannot be handled with the kdftable utility, such as Flash ADC and Multihit TDC. The only types that can be handled are ones where data structures for each events are fixed to a format that can be described as a table.)

% kdftable trial01.kdf -
# Creator: tinykinoko
# DateTime: 2002-05-17 04:14:41 JST
# UserName: sanshiro
# Host: shimeji.awa.tohoku.ac.jp
# Directory: /home/sanshiro/work/kinoko/local/trial01
# ScriptFile: Trial01.kts

# Fields: index adc.0 adc.1 adc.2 adc.3    
0 1475 215 1144 251 
1 295 1508 1353 2251 
2 201 837 1071 1414 
3 1251 1245 3298 716 
4 1829 919 1752 2697 
5 137 899 1728 1546 
6 1581 1088 357 172 
7 1840 1038 1466 1826 
8 121 484 181 337 
9 950 239 2167 2150 
(lines omitted below)
If comment lines and blank lines are obstructive for your analysis, use the UNIX standard command "grep" to take them off.
% kdftable trial01.kdf | grep "^[0-9]"
0 1475 215 1144 251 
1 295 1508 1353 2251 
2 201 837 1071 1414 
3 1251 1245 3298 716 
(lines omitted below)

tinyKinoko Tcl/Tk Front-End

With the Tcl/Tk front-end of tinykinoko (tinykinoko-tcltk), you can use a GUI (Graphical User Interface) for data acquisition. tinykinoko-tcltk also has an interface to GNUPLOT and ROOT, so that it can draw histograms and graphs of the acquired data. tinykinoko-tcltk automatically generates the ROOT script (trial01_hist.C) or the GNUPLOT script (trial01_hist.gp) during drawing. These scripts may be useful as the basis of a user analysis program.
screenshot (PNG 44kB)
screenshot (large) (PNG 76kB)
To acquire data, set fields such as the file name in the Configuration section, and click the [start] button in the Acquisition section. The acquisition can be stopped by clicking the [Stop] button.

The acquired data can be displayed by clicking the [Dump] button. By clicking the [Summary] button, some statistical information will be displayed such as event numbers for each channel and their average.

If ROOT or GNUPLOT is available, tinyKinoko-tcltk will generate scripts by clicking the Generate Script button in the Plot/Histogram section. Parameters in the Plot/Histogram section must be set prior to script generation. Click Draw to launch ROOT/GNUPLOT and execute the script. Selecting ROOT or GNUPLOT can be done in the Option menu.

The "kdftable" utility is used internally in the interface with ROOT/GNUPLOT. Therefore, these functions can only be used if the acquired data can be handled by "kdftable."

Using smallKinoko

"smallKinoko" is a multi-process DAQ system that works on a single PC. The system consists of several components: a Collector (hardware front-end), Buffer (shared memory manager), Viewer (real-time data display), Recorder (storage interface), Logger, and Controller. The components Controller, Logger and Viewer have a communication channel for user-interfaces (KinokoShell). These channels are connected to kinoko-control, kinoko-board and kinoko-canvas respectively.

Prior to using the system, you need to write a view script that the Viewer component uses. Make a file with the following contents and save it as trial01.kvs. Make sure the extension is .kvs, not .kts.

 1: /* Trial01.kvs */
 2: 
 3: display Trial01
 4: {
 5:     Histogram histogram_adc_01("ADC ch 01", 128, 0, 4096);
 6:     History history_adc_01("ADC ch 01", 0, 4096, 32);
 7:     Histogram histogram_adc_all("ADC all channels", 128, 0, 4096);
 8:     Tabular tabular_adc_all("ADC values");     
 9:
10:     analysis ("Trial01") {
11:         DataElement adc_01("adc", 1);
12:         DataElement adc_all("adc");
13:     
14:         histogram_adc_01.fill(adc_01);
15:         history_adc_01.fill(adc_01);
16:         histogram_adc_all.fillOne(adc_all);
17:         tabular_adc_all.fillOne(adc_all);
18:     }
19:
20:     on every (1sec) {
21:         histogram_adc_01.draw();
22:         history_adc_01.draw();
23:         histogram_adc_all.draw();
24:         tabular_adc_all.draw();
25:     }
26: }
Details of this script will be described later in the section Usage.

The utility that checks the view script is kvscheck. Like ktscheck, it will not display anything if there aren't any errors.

After preparing the script, start the launcher smallkinoko as follows:

  % smallkinoko
Several windows will appear with [SmallKinoko Control Panel], [logger], and [viewer] written on the title bars. Each of these is the window corresponding to the KinokoShells connected to components Controller, Logger, and Viewer.
screenshot (PNG 79kB)
screenshot (large) (PNG 211kB)
Enter the following to each field in the control panel window.
Readout Script (.kts): Trial01.kts
View Script (.kvs): Trial01.kvs
Data File (.kdf): Trial01.kdf

Then, click on the [construct] button in the control panel. Each component will read the script and build datastreams. Log messages outputted by the components will appear on the logger window. Here's an example of what it will look like.

N 05 Mar 2001 06:35:13 JST, collector: change state: ComponentReady
N 05 Mar 2001 06:35:14 JST, recorder: change state: ComponentReady
N 05 Mar 2001 06:35:14 JST, viewer: change state: ComponentReady
N 05 Mar 2001 06:35:14 JST, buffer: change state: Constructing
N 05 Mar 2001 06:35:15 JST, buffer: change state: DataTaking
D 05 Mar 2001 06:39:16 JST, collector: setReadoutScript(): trial01.kts
D 05 Mar 2001 06:39:16 JST, viewer: setViewScript(): trial01.kvs
D 05 Mar 2001 06:39:16 JST, recorder: setDataFile(): smallkinoko.kdf
D 05 Mar 2001 06:39:17 JST, collector: setSink: buffer (buffer) @127.0.0.1, shm: 100, msg: 101
D 05 Mar 2001 06:39:18 JST, recorder: setSource(): buffer (buffer) @127.0.0.1, shm: 100, msg: 101
D 05 Mar 2001 06:39:19 JST, viewer: setSource(): buffer (buffer) @127.0.0.1, shm: 100, msg: 101
N 05 Mar 2001 06:39:19 JST, collector: change state: Connecting
D 05 Mar 2001 06:39:19 JST, collector: connecting sink...
D 05 Mar 2001 06:39:20 JST, collector: connected
(lines omitted below)
The first column is "log level", which has the following classifications:
D: Debugignore it
N: Noticemight be interesting
R: Remarkablesupernova explosions and such
W: Warningdata might have problems (but not execution)
E: Errorunable to continue executing
P: Panicunable to continue executing, unable to terminate; garbage is left on the system which will need to be removed before the next execution
If error or panic occurs, shut down the system by clicking the [quit] button. Most errors are caused by script errors.

If everything goes well, start data acquisition by clicking the [start] button. The histograms will be updated every second, and you can watch your kinoko grow!

screenshot (PNG 28kB)
screenshot (large) (PNG 50kB)
When you get bored, click [stop] and then [quit] to shut down the system. The shutdown process takes a few seconds after clicking [quit]. Do not Ctrl-c before the prompt returns to a terminal and the shutdown process is complete.

SmallKinoko Enterprise

SmallKinoko Enterprise is structured basically the same as SmallKinoko (well, entirely the same), but with added functions like compressing data files, adding comments, and automatically stopping runs. To use SmallKinoko Enterprise, choose the --enterprise option when launching SmallKinoko. SmallKinoko Enterprise includes all functions that SmallKinoko has, so if you want to use this regularly, setting an alias would be useful.
% smallkinoko --enterprise
The only difference from SmallKinoko in terms of how it looks is just the control panel.

screenshot (large) (PNG 15kB)
The RunName and Comment are recorded in the header of the datafile. The header can be displayed with kdfdump, etc.

If you specify the "#-of-events" and/or "time" on the [auto-stop conditions], the run will stop automatically at that certain number of events or after that certain amount of time passes. If you don't want to use this function, simply leave the fields blank.

The "Prohibit Datafile Overwriting" option under the [Data File Settings] disables the overwriting of datafiles. A pop-up window will appear if you specify data file names that already exist, but if this option is chosen, even if you choose to overwrite on the pop-up, it will produce an error and not let you overwrite.

If you choose "Set Datafile Readonly," the data file composed in this run will be set to a read-only attribute (444: -r--r--r--). Kinoko does not change a file's attribute in any case so the file will be protected at the system level.

By choosing "Enable Data Compression," a file will be compressed using zlib. The file becomes significantly smaller, but you cannot use some functions such as random accessing.

By choosing "Make Data Index," an index file will be made separately and random access using this will be available. Choosing this option regularly isn't thought to be necessary however (an index file can be created later).

All these options mentioned above have to be configured prior to clicking the [construct] button.

Customizing the Control Panel

Here we will customize the control panel so that we can specify the ADC station number and readout channel from the control panel. The following is an image of how our control panel we make will look. It has fields for the station number and channels.

The control panel configuration is scripted by a control panel script (KCML script). This, unlike the ones we have discussed, uses an XML script. Here we will customize our control panel using the control panel script used in SmallKinoko as our basic script. Copy the SmallKinoko script (and the images used) to your working directory like the following.

% cp $KINOKO_ROOT/scripts/SmallKinoko.kcml ./Trial02.kcml
% cp $KINOKO_ROOT/scripts/SmallKinoko.xpm .
Edit "Trial02.kcml" like the following. The bold lines are the ones you need to add.
<?xml version="1.0"?>

<KinokoControlPanel label="SmallKinoko Control Panel">
  <HSpace/><Image file="SmallKinoko.xpm"/>
  <VSpace/>

  <HSpace/><Label name="message" label="Welcome to the Kinoko World." font="times-italic" size="14"/><HSpace/>
  <VSpace/>

  <EntryList>
    <Entry name="readout_script" label="ReadoutScript (.kts)" option="file_select"/>
    <Entry name="view_script" label="ViewScript (.kvs)" option="file_select"/>
    <Entry name="data_file" label="DataFile (.kdf)" option="file_select"/>
    </EntryList>
  <VSpace/>

  <Frame label="ADC Configuration">
    <Entry name="station" label="Station" width="40" selection="1 2 3 4"/>
    <Label label="Ch: "/>
    <RadioButton name="enable_ch0" label="0"/>
    <RadioButton name="enable_ch1" label="1"/>
    <RadioButton name="enable_ch2" label="2"/>
    <RadioButton name="enable_ch3" label="3"/>
    <RadioButton name="enable_ch4" label="4"/>
    <RadioButton name="enable_ch5" label="5"/>
    <RadioButton name="enable_ch6" label="6"/>
    <RadioButton name="enable_ch7" label="7"/>
  </Frame>
  <NewLine/>

  <Frame name="run_control" label="Run Control">
    <ButtonList>
      <Button name="construct" label="Construct" enabled_on="stream_ready system_ready"/>
      <Button name="start" label="Start" enabled_on="system_ready"/>
      <Button name="stop" label="Stop" enabled_on="data_taking"/> 
      <Button name="clear" label="Clear" enabled_on="system_ready data_taking"/>
      <Button name="quit" label="Quit" enabled_on="stream_ready system_ready error"/>
    </ButtonList>
  </Frame>
</KinokoControlPanel>
You can confirm how the control panel this script makes will look like using "kcmlcheck".
% kcmlcheck Trial02.kcml
Next, we configure the readout script so that it acquires the values set in the control panel to use them. In Trial01.kts, delete the lines that hard-code the station number and channels (lines 5 and 6) and add the following bold parts. The "getRegistry()" function grabs the parameters set in the control panel.
 1: /* Trial02.kts */
 2: 
 3: datasource Trial02
 4: {
 5:     int station = getRegistry("control/station");
 6:     int readout_channels;
 7:     for (int ch = 0; ch < 16; ch++) {
 8:         if (getRegistry("control/enable_ch" + ch) == "1") {
 9:             readout_channels += 0x0001 << ch;
10:         }
11:     }
12:
13:     CamacCrate crate;
14:     CamacController controller("Toyo-CC7x00");
15:     CamacModule adc("Rinei-RPC022");
16:     
17:     crate.installController(controller);
18:     crate.installModule(adc, station_number);
19:     
20:     on trigger(adc) {
21:         adc.read(readout_channels);
22:         adc.clear();
23:     }
24: }
Use the KCML file we made previously as the argument and launch SmallKinoko. This should launch a SmallKinoko with the customized control panel that we just made.
% smallkinoko Trial02.kcml
Don't forget to change the "ReadoutScript" to "Trial02.kts" before clicking [construct].

Cleaning Up After Abnormal Termination

If Kinoko is terminated abnormally, it leaves garbage on the operating system, specifically system resources such as shared memory and/or left-over processes. This garbage will disturb the next execution of Kinoko (a common error message is "File already exists"). In this case, a little clean-up is needed. The clean-up steps vary slightly depending on the operating system. The following applies to Linux 2.x operating systems.
Deleting Message Queues
smallKinoko uses two message queues. Message queues currently used can be shown with the ipcs command.
% ipcs
------ Message Queues --------
key        msqid     owner    perms      used-bytes  messages
0x01039817 128         sanshiro  600       0           0
0x6503802e 129         sanshiro  600       0           0
Usually message queues are used only by Kinoko. If other system are using message queues, Kinoko's queues can be identified by their owner (you) and permissions (600). To delete the message queue, use the ipcrm command with "msg [id]".
% ipcrm msg 128
% ipcrm msg 129
When the message queues are deleted, most kinoko processes will exit with error messages.

Deleting a Shared Memory Segment
smallKinoko uses one shared memory segment. Shared memory segments currently in use can be listed with the ipcs command.
% ipcs
------ Shared Memory Segments --------
key        shmid     owner     perms     bytes     nattch  status
0x5b037c7f 3         root      644       1048576   0       dest
0x00000000 260       root      644       98304     16      dest
0x00000000 1157      sanshiro  777       65536     2       dest
0x00000000 1158      sanshiro  777       65536     2       dest
0x00000000 1159      sanshiro  777       65536     2       dest
(lines omitted)
0x00000000 71365     sanshiro  777       65536     2       dest
0x00000000 71366     sanshiro  777       65536     2       dest
0x6403802e 73159     sanshiro  600       33554432  4           
(lines omitted below)
If you use a desktop-environment such as GNOME, a lot of shared memory segments are used. The shared memory segment used by Kinoko can be identified by its owner (you), permissions (600), and size (33554432). To delete the shared memory segment, use the ipcrm command with "shm [id]".
% ipcrm shm 73159

Deleting Left-Over Processes
First, close all Kinoko windows. Then find the remaining Kinoko processes.
% ps -ef | grep inoko
sanshiro  1259     1  0 06:34 ttyp2    00:00:00 wish /home/sanshiro/work/kinoko/bin/kinoko-control-panel leno.awa.tohoku.ac.jp 10001
sanshiro  1273     1  0 06:34 ttyp2    00:00:00 KinokoController-kcom controller port: 10002
sanshiro  1277     1  0 06:35 ttyp2    00:00:00 KinokoCollector-kcom collector file: smallkinoko.log
sanshiro  1303  1285  0 07:23 ttyp5    00:00:00 grep inoko
Note that inoko is used as the grep match keyword instead of kinoko or Kinoko: this is because the process names might be either Kinoko-something or kinoko-something. Use the kill command to delete these processes.
% kill 1259
% kill 1273
% kill 1277
In the Kinoko utilities, there is a simple script killoff that performs searches with grep and kills the processes found all at once. By using this the processes shown above can be taken care of like the following.
% killoff inoko
sanshiro  1259     1  0 06:34 ttyp2    00:00:00 wish /home/sanshiro/work/kinoko/bin/kinoko-control-panel shimeji.awa.tohoku.ac.jp 10001
sanshiro  1273     1  0 06:34 ttyp2    00:00:00 KinokoController-kcom controller port: 10002
sanshiro  1277     1  0 06:35 ttyp2    00:00:00 KinokoCollector-kcom collector file: smallkinoko.log
commit? (y/n) > y
kill 1259
kill 1273
kill 1277
% 
Also check kcom and korb as the grep keyword. It is possible that the following processes are still running.
kcom-manager
kcom-registry-server
korb-broker
korb-nameserver

The Last Resort: in case cleaning up cannot be completed
Reboot the operating system. All left-over garbage will be deleted automatically. Don't forget to install the device drivers after rebooting.


Edited by: Enomoto Sanshiro