bytran communication protocol

Starting with version 1.3 bytran can be operated remotely.   This functionality may be tested over Bluetooth, Serial port or using WebSockets over WiFi / Ethernet (i.e. from within the web browser).  The data exchange is initiated using the communication commands listed below.

By default the "char mode" is used in which all commands and numerical parameter values are transmitted as string representations of the corresponding variables.  In this mode the desired string format and precision of the floating point numbers returned by bytran may be specified using the FORMAT and PREC commands listed below.   A "mixed binary mode" is also to be implemented to enable numerical data transfer in a binary format as opposed to strings.

The parameters which do not currently have an associated menu item in the bytran interface/menu or responsible for calculated spectra manipulation are not stored in the configuration file when modified using the protocol described on this page (currently these commands are TOTAL, PREC, FORMAT, and DELIMITER).


Commands with one parameter or without parameters

for commands with one parameter:
Set value:   "#" + "Command" + ";" + "Parameter value"
Get value:   "#" + "Command" + ";" + "?"

Get value example: #SWAVE;? to obtain the value of the Start wavenumber.
Set value example: #PATH;2500 to set the pathlength to be 2500 meters.

for commands without parameters:
Commands which do not have a data type are trasmitted without the subsequent question mark or the parameter value.
Request format:   "#" + "Command".
Example: #CALC to start a new calculation.  Once the calculation initiated with the #CALC command is complete a READY signal will be transmitted to the requesting device.

The table below presents a complete listing of available commands with one parameter or with no parameters:

Parameter name / Possible values Get / Set command Data type Units
Start wavenumber SWAVE double 1 / cm
End wavenumber EWAVE double 1 / cm
Number of wavenumber points NUMWNPTS int -
Y-axis paramter to plot YPARAM int -
       0 - Attenuation
       1 - Radiance
-
W / (sr * cm2 * cm-1)
Y-axis units for the selected Y-axis paramter YUNITS int -
       0 - Cross-section
       1 - Optical depth
       2 - Absorption
       3 - Transmission
(cm2 / molecule)
-
%
%
Show total spectrum or Separate molecules TOTAL boolean -
       0 - Show separate molecules spectra
       1 - Show total spectrum
Pathlength PATH double meters
Total pressure TPRES double atm
Use barometer sensor USEBAROM boolean -
Temperature TEMP double Kelvin
Use temperature sensor USETHERM boolean -
Use humidity sensor USEHUMID boolean -
Use SensorTag module USESENSTAG boolean -
Sensors sampling period SMPLPERIOD int milliseconds
Number of sensor samples to average SMPLSTOAVG int -
HITRAN database option HITOPT unsigned byte -
       0 - Segmented download
       1 - Complete download
       2 - Download every time
Lineshape profile LSHAPE unsigned byte -
       0 - Doppler lineshape profile
       1 - Lorentz lineshape profile
       2 - Voigt lineshape / Standard precision
       3 - Voigt lineshape / Higher precision
Line intensity threshold LTHRESH double cm * molec * 1E-25
Line wing contribution
(in saturated half widths)
LWINGSAT double -
Line wing contribution, absolute LWINGABS double 1 / cm
Lineshape broadening LBROAD unsigned byte -
       0 - Air
       1 - Self
       2 - Air and Self
Line shift use LSHIFTUSE boolean -
Instrument function type INSTRFUNCT unsigned byte -
       0 - None
       1 - Rectangular (Boxcar)
       2 - Triangular
       3 - Gaussian
       4 - Dispersion (Lorentz)
       5 - Diffraction
       6 - Michelson
       7 - Cosine
Instrument resolution INSTRRES double 1 / cm
Instrument function wing INSTRWING double 1 / cm
Apply atmospheric model ATMMODEL unsigned byte -
       0 - Tropical
       1 - Midlatitue summer
       2 - Midlatitude winter
       3 - Subarctic summer
       4 - Subarctic winter
       5 - US Standard
Calculate for all molecules ALLCALC boolean -
Perform calculation CALC - -
Set precision of returned floating point values (default value is 8) PREC unsigned byte -
Set format for returned floating point values (default is g) FORMAT char -
       Possible values   -   e, E, f, g, G   (see this link)
Set returned data delimiter (default is the semicolon ';') DELIMITER String -
Request calculation results RESULT see below see below
Boolean variables are transmitted as one character string (one byte, char) with a char value of 1 for true and 0 for false.


For molecular concentrations and molecule selected states
Set value:   "#" + "Command" + ";" + "Molecule number (as in HITRAN)" + ";" + "Second parameter value"
Get value:   "#" + "Command" + ";" + "Molecule number (as in HITRAN)" + ";" + "?"

Get value example: #MCONC;1;? to obtain the molecular concentration of the H2O molecule in ppmv.
Set value example: #MCONC;3;0.03 to set the molecular concentration of the O3 molecule in ppmv to 0.03 ppmv.
Get value example: #MSEL;1;? to obtain the selected state of the H2O molecule.
Set value example: #MSEL;3;1 to select the O3 molecule for calculation (1 - for true, 0 - for false).

OR

Set value:   "#" + "Command" + ";" + "Molecule chemical formula (as in HITRAN)" + ";" + "Second parameter value"
Get value:   "#" + "Command" + ";" + "Molecule chemical formula (as in HITRAN)" + ";" + "?"

Get value example: #MCONC;H2O;? to obtain the molecular concentration of the H2O molecule in ppmv.
Set value example: #MCONC;O3;0.03 to set the molecular concentration of the O3 molecule in ppmv to 0.03 ppmv.
Get value example: #MSEL;H2O;? to obtain the selected state of the H2O molecule.
Set value example: #MSEL;O3;1 to select the O3 molecule for calculation (1 - for true, 0 - for false).

Parameter name / Possible values Get / Set command Data type Units
Molecular concentration MCONC - -
        - First parameter (molecule number or chem. formula ) int -
        - Second parameter (molecule concentration) double ppmv
Molecule selected state MSEL - -
        - First parameter (molecule number or chem. formula ) int -
        - Second parameter (selected state) boolean -

Boolean variables are transmitted as one character string (one byte, char) with a char value of 1 for true and 0 for false.
as numbered in HITRAN.
chemical formula as listed in HITRAN (not case sensitive)


To retrieve the results of the last calculation

All commands related to the retrieval of calculation results are read only and begin with #RESULT; followed by one of the supported commands listed below without the preceding # character.   To retrieve the calculated spectra the #RESULT; command is used in combination with the SPEC; command to form #RESULT;SPEC; followed by the integer or string parameter representing the type of calculated spectrum to return as listed in the following table.   The individual values in the returned calculation results are delimited with a ; character.

Parameter name / Possible values Get command Data type Returned data units
One of the calculated spectra SPEC int in currently set vertical axis units
      -1 - Smoothed total
       0 - High resolution (not smoothed) total
       N - spectrum for molecule N
One of the calculated spectra SPEC String in currently set vertical axis units
      TOTAL - Smoothed total
       INSTR - High resolution (not smoothed) total
       Molecule chemical formula (i.e. H2O, CO2 etc.) - spectrum for a molecule
Get wavenumber grid WNGRID - 1 / cm

as numbered in HITRAN
chemical formula as listed in HITRAN (not case sensitive)

For example:
#RESULT;SPEC;1 or #RESULT;SPEC;1;?  would return the calculation results for the H2O molecule in a String representation delimited with a ; character in the currently set vertical scale units (i.e. transmission, absorption etc.)
#RESULT;SPEC;CO2 or #RESULT;SPEC;CO2;?  would return the spectrum of CO2 in current units.
#RESULT;SPEC;TOTAL and #RESULT;SPEC;INSTR will return the high resolution total spectrum and its instrument function processed version respectively.
#RESULT;WNGRID or #RESULT;WNGRID;?  would return the wavenumber grid array values in 1/cm.

Some calculation paramters are frequently modified, as such a copy of these paramters is made at each calculation run to associate them with that calculation.   These coppied values are not affected if the user changes the settings through the menu and may be retrieved using the #RESULT; followed by the corresponding command.   For example, if the total pressure is modified in the menu after a calculation, the value of total pressure retrieved using the #RESULT;TPRES command will remain unchanged and will correspond to the total pressure used in the calcuation.   A listing of such read only paramters for which a copy is made at each calculation run and which may be retrieved using the #RESULT; with the corresponding command are presented below:

Parameter name Get command
Start wavenumber SWAVE
End wavenumber EWAVE
Number of wavenumber points NUMWNPTS
Pathlength PATH
Total pressure TPRES
Temperature TEMP
Molecular concentration MCONC

For example:
#RESULT;SWAVE;? or #RESULT;SWAVE  would return the starting wavenumber used in the last calculation,
#RESULT;WNGRID;? or #RESULT;WNGRID  will return the wavenumber grid used in the last calculation, and
#RESULT;MCONC;2;? or #RESULT;MCONC;2  would return the concentration of CO2 in ppmv used in the last calculation.

www.bytran.org -|- 2018     To report a bug or suggest a feature please email us:  bytran@bytran.org