Specifications of the format of cyloop files

This document describes the file structure used by free software Cyloop developed by Chardonneau Bernard (France) to store the information that this software can handle.

Files whose format is described in this document are called "cyloop files".

The exact reproduction of this text, its translation into other languages and its dissemination are free.

In case of differences of meaning between two versions of the text written in different languages, the French version is the one what constitutes the reference.

File suffix and data formats used

Cyloop files are files whose name ends with the suffix .cyl or .CYL .
These are binary files. The information they contains are stored in the following formats :
It is possible to store the numerical values from the upper byte to the lower byte (big endian) or from the lower byte to the upper byte (little endian).
However, the order of bytes in the numerical values indicated in the cyloop file.

If the digital values are stored from the lower byte to the upper byte, as it is the case on the personal computers (microprocessor Intel or compatible), the name of the cyloop files end by the suffix .cyl and the first 3 bytes of the cyloop file are cyl (lowercase).

If the digital values are stored from the upper byte to the lower byte, the name of the cyloop files end by the suffix .CYL and the first 3 bytes of the cyloop file are CYL (in capital letters).

Finally, if the operating system does not allow to choose between lowercase or uppercase letters for file names, it is the cyloop file signature (represented by his first 3 bytes) that defines the byte order in numerical values.

Structure of a cyloop file

Cyloop files have the following general structure :


There is a special case for the cyloop files that memorize only one variable without name.
In this case, the cyloop files have the following structure :


The header of a cyloop file

The header of a cyloop file consists of 16 bytes and contains in this order the following fields :

TypeNameDescription
3-bytesignature Allow to control that the file is a cyloop file with the right format.
Contains in this order :
  • characters cyl if numeric values are stored from the lower byte to the upper byte (it is the case on the PCs),
  • characters CYL if numeric values are stored from the upper byte to the lower byte.
    		•
    bytenb_var Number of variables stored in the cyloop file.
  • If nb_var = 0, the cyloop file memorize a single variable that has no name.
  • If nb_var > 0 (value between 1 and 255), the cyloop file memorize nb_var variables. Each can be identified by name or by a number corresponding to its position in the list of variables described in the following paragraph.
    		•
    bytecaract_gen Bit field which defines the general characteristics of the cyloop file.
    Every indication is stored on one bit.
  • bit 0
    		• cycle_decl Triggered cycle.
  • If cycle_decl = 0, each new cycle begins immediately at the end of the previous one (default setting for Cyloop).
  • If cycle_decl = 1, it is necessary to run the command cyldecl to start a new cycle.
    		•
  • bit 1
    		• temps_utc Beginning of cycles counted in universal time (UTC or GMT).
  • If temps_utc = 0, the beginning of the cycle are calculated relative to local time (which can be offset if daylight saving is applied a portion of the year).
  • If temps_utc = 1, the beginning of the cycle are calculated relative to Universal Time (UTC or GMT).
    		•
  • bit 2
    		• cycle_ireg Using irregular cycle length based on the calendar.
  • If cycle_ireg = 0, all cycles have the same duration that is set by the value of duree_cycle.
  • If cycle_ireg = 1, using cycles with irregular duration, monthly or yearly.
    		•
  • bit 3
    		• cycle_annuel Choice between monthly or yearly cycle.
    This bit is meaningful only if bitt cycle_ireg is 1
  • If cycle_annuel = 0, the cyloop file operates on a monthly cycle starting to the first day of the month.
  • If cycle_annuel = 1, the cyloop file operates on an annual cycle starting to the first day of the year.
    		•
  • bits 4-7 unused
    		•  They must be left to 0.
    byteetat_cyloop Status bits of the cyloop file.
  • bit 0
    		• heure_ete This bit stores if it was summer time (bit to 1) or winter time when data was updated for the last time.
    It is meaningful only if bit temps_utc = 0 (local time).
  • bits 1-7 unused
    		•  They must be left to 0.
    uint16nb_don_cycle Number of data per measurement cycle.
    It is the number of intervals of the same duration (potentially to second near) in which each cycle is divided.
    uint32deb_cycle Moment when start of the current cycle.
    It is the value returned by function time() at the beginning of this cycle (number of seconds since 1 January 1970-0 H UTC).
    uint32duree_cycle Duration in seconds of the current cycle.

    The list of variables

    This list exists only if the value of nb_var of the cyloop file header is not 0. In this case, the list includes nb_var elements with the following structure :

    The header of a variable

    The header of a variable consists of 6 or 8 bytes and contains in this order the following fields :

    TypeNameDescription
    uint16der_enreg Number of the last data updated in the current cycle.
  • If der_enreg = 0, the data has not been yet updated for the current cycle.
  • Otherwise, der_enreg is between 1 and nb_don_cycle.
    		•
    bytetypedon Bit field that defines the characteristics of the variable.
    Each indication is stored on one bit.
  • bit 0
    		• cmoy_sep Separate coefficient coef_moy for each moment of the cycle.
  • By default (cmoy_sep = 0) the calculation of the average value for each data cycle is done regarding the value of the field coef_moy defined at the end of of this header. coef_moy field contains a value related to the number of cycles done.
  • If cmoy_sep = 1, to each data corresponding to a given moment of the cycle is associated a distinct value coef_moy.
    		•
  • bit 1
    		• cpt_cycle_vide Empty cycles taken into account in the weighting calculations.
    This bit is meaningful only if the value of ponderation field is different from 0.
  • By default (cpt_cycle_vide = 0), if one or more cycles elapse without any registration data, they are ignored in the next weighting calculation of already recorded datas.
  • If this bit is 1, the weighting calculation is made taking into account the empty cycles.
    		•
  • bit 2
    		• cumul_donnees Allow multiple updates at every moment of the cycle.
  • By default, during a cycle, each data corresponding to a moment of the cycle can be updated only once.
  • If this bit is 1, the same data can be updated several times.
    		•
  • bit 3
    		• compteur Choice between a variable containing values or a counter.
  • By default (compteur = 0) it is necessary to introduce a value for updating the data corresponding to a moment of the cycle.
  • If compteur = 1, the variable is a counter that is incremented automatically.
    		•
  • bit 4
    		• donnees_32bits Data format for the counter variable.
    This bit is only meaningful if bit compteur is 1.
  • By default (donnees_32bits = 0), counter data are stored on 2 bytes (uint16).
  • If donnees_32bits = 1, counter data are stored on 4 bytes (uint32).
    		•
  • bit 5
    		• val_float Data format for the standard variable.
    This bit is only meaningful if bit compteur is 0.
  • By default (val_float = 0), variable data are then integer 4 bytes values (int32).
  • If val_float = 1, the data of the variable are stored in float values.
    		•
  • bit 6
    		• mem_min_max Storing minimum and maximum values of data input at every moment of the cycle.
    This bit is only meaningful if bit compteur is 0.
  • By default (mem_min_max = 0), only an amount possibly weighted of datas is stored for each moment of the cycle, and an indication to calculate their average value.
  • If mem_min_max = 1, the minimum and maximum values of data submitted for each moment of the cycle are also stored.
    		•
  • bit 7
    		• cpt_toute_don This bit is only meaningful if cmoy_sep = 1 and cumul_donnees = 1.
  • If in addition, cpt_toute_don = 1, the value coef_moy associated to each moment of the cycle is incremented with each update the corresponding data.
  • If cpt_toute_don = 0, the increment occurs only during the first update of the data for this moment of the cycle.
    		•
    byteponderation Weighting factor for the values of previous cycles.
  • If ponderation = 0, no operation is performed on the data already stored when a cycle changes. With each new cycle, new data are added to those of previous cycles.
  • Otherwise (ponderation between 1 and 255), data from previous cycles are multiplied by (ponderation / 256). It is the same for memorised coefficient(s) coef_moy.
    Thus, data of the last cycles become more important for calculating the average value than those of the older cycles.

  • If bit cpt_cycle_vide of typedon field is 1 and that several cycles occured without updating the data, the weighting calculation is performed for each of these cycles.
    		•
    uint16extention Available field for possible future use. Presently set to 0.
    uint16coef_moy (optional) Coefficient used to calculate the average value of data stored for each moment of the cycle.
  • If bit cmoy_sep of typedon field is 0, this coefficient has a value updated at the beginning of each cycle which allows the calculation of average values of data for every moment of the cycle.
  • If bit cmoy_sep of typedon field is 1, this coefficient does not exist in the header of the cyloop variable, but a similar coefficient is stored separately in the cyloop file for every moment of the cycle.
    		•

    Data structure of a variable

    After the header of a variable, the data associated with this variable are found in succession.

    All the datas for the first moment of the cycle are found first, then those on the next moment, and so on.

    Depending on the value of bits cmoy_sep, compteur, donnees_32bits, val_float and mem_min_max of typedon field inside the header of the variable, there can be one or more values stored for each moment of the cycle and several storage formats for each of these values.

    A group of values corresponding to a moment of the cycle contains in this order :
    In total, that group of value appears nb_don_cycle times (value set in the header of the file) to store the complete cycle.

    Data structure for counter variables

    Data structure for "value" variables