bytran communication protocol

Starting with bytran 1.3 the capability to control bytran remotely will be introduced.   Once version 1.3 is released this functionality may be tested over Bluetooth or from within the web browser over WiFi / Ethernet using the form on this page.   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.

 

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.

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

Parameter name / Possible values Get / Set command Parameter data type Parameter units
Start wavenumber SWAVE double 1 / cm
End wavenumber EWAVE double 1 / cm
Number of wavenumber points NUMWNPTS int32 -
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 int32 milliseconds
Number of sensor samples to average SMPLSTOAVG int32 -
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 cm-1
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
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 6) 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)
Request calculation results RESULT see below see below
Boolean variables are transmitted as one character string (one byte, char) with a 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).

Parameter name / Possible values Get / Set command Parameter data type Parameter units
Molecular concentration MCONC - -
        - First parameter (molecule number ) int32 -
        - Second parameter (molecule concentration) double ppmv
Molecule selected state MSEL - -
        - First parameter (molecule number ) int32 -
        - Second parameter (selected state) boolean -

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

 

 

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 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 Parameter data type Returned data units
One of the calculated spectra SPEC int32 in currently set vertical axis units
      -1 - Smoothed total
       0 - High resolution (not smoothed) total
       N - spectrum for molecule N
Get wavenumber grid WNGRID - 1/cm

as numbered in HITRAN

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;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