BM-800 Communication Protocol Specification
BM-800 Communication Protocol Specification
Specification
Bl-1013-02
elektronisk kopia
Contents
CONTENTS ......................................................................................................................................................2
1. SUMMARY ..............................................................................................................................................5
1.1. FUTURE CHANGES .............................................................................................................................5
2. INTRODUCTION, AND USE OF XML IN BM800 ............................................................................6
Bl-1013-02
elektronisk kopia
3.5.5.3. CEXP - Expiry Date of a Control Blood with Reference Ranges ...................................................................... 18
3.5.5.4. CEXT - Extra Control Blood Information for a Control Blood with Reference Ranges................................... 18
3.5.6. Patient Information ................................................................................................................19
3.5.7. Container Status.....................................................................................................................19
3.5.7.1. RGED - Diluent Container Empty ...................................................................................................................... 19
3.5.7.2. RGEL - Hemolyzer Container Empty ................................................................................................................. 19
3.5.7.3. RGEC - Cleaner Container Empty ...................................................................................................................... 19
3.5.8. Settings ...................................................................................................................................19
3.5.8.1. APNU – Analysis Profile Number ...................................................................................................................... 19
3.5.8.2. APNA – Analysis Profile Name / control blood level name .............................................................................. 20
3.5.8.3. XLT - Extra Hemolyzing Time ........................................................................................................................... 20
3.5.9. Reagent statistics....................................................................................................................21
3.5.9.1. RDLI Reagent Statistics Diluent Lot identifier................................................................................................... 21
3.5.9.2. RDPN Reagent Statistics Diluent Package number............................................................................................ 21
3.5.9.3. RDED Reagent Statistics Diluent Expiry date.................................................................................................... 21
3.5.9.4. RLLI Reagent Statistics Hemolyzer Lot identifier ............................................................................................. 21
3.5.9.5. RLPN Reagent Statistics Hemolyzer Package number....................................................................................... 21
3.5.9.6. RLED Reagent Statistics Hemolyzer Expiry date .............................................................................................. 22
3.5.9.7. RCLI Reagent Statistics Cleaner Lot identifier .................................................................................................. 22
3.5.9.8. RCPN Reagent Statistics Cleaner Package number............................................................................................ 22
3.5.9.9. RCED Reagent Statistics Cleaner Expiry date.................................................................................................... 22
3.6. <SMPRESULTS> SAMPLE RESULT PARAMETER VALUES ................................................................22
3.6.1. Result Parameter Format.......................................................................................................23
3.6.1.1. <v> - Parameter Value......................................................................................................................................... 23
3.6.1.2. <r> - Parameter Out-of-Range ............................................................................................................................ 23
3.6.1.3. <f> - Parameter Error Flag .................................................................................................................................. 23
3.6.1.4. <l> - Parameter Normal/Reference Range Low ................................................................................................. 23
3.6.1.5. <h> - Parameter Normal/Reference Range High................................................................................................ 24
3.6.1.6. Examples.............................................................................................................................................................. 24
3.6.2. Description of the Sample Result Parameters........................................................................24
3.7. <HGRAMS> HISTOGRAMS ...............................................................................................................25
3.7.1. <hgrams> - Histograms Section............................................................................................27
3.7.2. <hgram> - Histogram Format...............................................................................................27
3.7.2.1. <n> – Histogram Name ....................................................................................................................................... 27
3.7.2.2. <min> - Histogram Min Range ........................................................................................................................... 27
3.7.2.3. <m> - Histogram Max Range.............................................................................................................................. 27
3.7.2.4. <k> - Histogram Number of Bins........................................................................................................................ 27
3.7.2.5. <w> - Histogram Filter Factor............................................................................................................................. 28
3.7.2.6. <d> - Histogram Discriminator Index................................................................................................................. 28
3.7.3. <hgdata> - Histogram Data Vector ......................................................................................28
3.7.3.1. <n> - Histogram Data Vector Name ................................................................................................................... 28
3.7.3.2. <v> - Histogram Data Vector Values.................................................................................................................. 28
4. TRANSPORT PACKAGE....................................................................................................................29
4.1. PACKAGE DELIMITERS ....................................................................................................................29
4.2. CHECKSUM ARMOUR .......................................................................................................................29
4.2.1. New Line handling .................................................................................................................30
4.2.2. Checksum algorithm...............................................................................................................30
4.2.2.1. “Easy calculation” checksum algorithm ............................................................................................................. 30
4.3. MESSAGE HANDLING ......................................................................................................................32
4.3.1. Message ID assignment..........................................................................................................32
4.3.2. Acknowledge messages ..........................................................................................................33
4.3.3. Retransmission of lost messages ............................................................................................34
4.3.4. Handling of duplicate message ID:s ......................................................................................34
4.3.5. Handling of missing message ID:s.........................................................................................34
4.3.6. Handling of incomplete packages ..........................................................................................34
4.3.7. Handling of packages that fails the checksum test, or has transport package or message
format errors 34
4.3.8. Handling of messages with undefined message content.........................................................34
4.3.9. Some comments about the message handling in BM800........................................................35
4.3.10. Final tips and tricks................................................................................................................35
Bl-1013-02
elektronisk kopia
5. REFERENCES ......................................................................................................................................35
Bl-1013-02
elektronisk kopia
1. Summary
This specification describes both the BM800 XML formatted sample result format (see 3) and a rather
generic full duplex transport package protocol which is formatted inside XML comments (see 4).
BM800 uses an eXtensible Markup Language (XML) based format for all in- and outgoing computer
communications.
The normal BM800 communication consists of a BM800 transmitting sample results, and a receiving end
storing and/or processing the sample results. The receiving end can also optionally acknowledge each sample
results package.
The results of one sample are transmitted in one transport package.
The BM800 can either be set up to automatically transmit sample results every time one sample has been
processed, or the operator can initiate a transmission of one or more sample results from the sample memory
in the BM800. It the latter case each sample results is still transmitted in one transport package.
It is not possible to determine if one set of sample results comes from an automatic transmission, or from a
send from the sample memory. They looks exactly the same.
The receiving end should be prepared to handle duplicate transmissions of the same sample. (Do no confuse
this with the transport package retransmissions described in 4.3.3. Such retransmitted sample results are
dropped on the transport package level.)
BM800 instruments equipped with special firmware can also receive sample results formatted according to
this specification.
Future versions of the BM800 firmware may well include more kinds of in- and outgoing communications.
Bl-1013-02
elektronisk kopia
2. Introduction, and use of XML in BM800
This is unfortunately a mix (mess?) of formal specification, implementation details about BM800 and XML,
and rationale for some decisions.
Some knowledge of XML, character encoding and BM800 is assumed. And some C language programming
too.
BM800 only uses the syntax and structure from XML. This gives it a lot of existing XML parsers to use
instead of having to write custom tailored ones. The format needs to be as simple as possible, since the
BM800 has to parse it as well. Producing XML, on the other hand, is easy for fixed data structures. For
further description of XML, see [1].
Document Type Declarations (DTD:s) are not used, but could be added. The BM800 communication format
is a very application-specific use of XML. But a DTD should preferably actually be possible to write and
use.
The XML output from the BM800 is strictly speaking not correct XML. An XML document should have one
top-level document node. BM800 outputs multiple sample result nodes after each other on the top level. But
each sample result node in itself is a correct XML document.
BM800 does not use attributes. They might not be visible by a simple XML text viewer, and complicates
parsing in the BM800.
BM800 will use the ISO 10646 ~ "Unicode" character set for non-7-bit-ASCII characters. These characters
will be encoded in "UTF-8" or as numeric character entities. (Note: “UTF-8” is the default encoding in XML
unless one is specified.)
BM800 does not use XML declarations '<?xml version="..." ... ?> ' or text declarations "<?xml ... ?>". They
are not required since only "UTF-8" is used (or its 7-bit ASCII subset), which is the XML default character
encoding.
BM800 only uses the predefined entities "&" (&), "<" (<), ">" (>), "'" (") and ""e;" (').
("'" and ""e;" are only needed in attribute values, which are not used in this specification.)
The tag name syntax is limited to be like C identifiers:
[A-Za-z_][A-Za-z_0-9]*
(=An upper- or lowercase letter or an underscore followed by zero or more upper- or lowercase letters,
underscores or digits)
Note: all tag names beginning with "xml" in any combination of upper- or lowercase letters are reserved for
use by XML standards.
Case is significant in tag names and in parameter names.
BM800 uses single-character names for common element tag names to speed up serial transfers. Examples:
"<n>" for name, "<v>" for value etc. But note that all element tag names in an XML document should be
unique if it should be possible to add a "tight" DTD that separates PCDATA content and element content. (It
can be argued that PCDATA elements could be reused in different contexts. F.ex. "<n>" could mean name in
one context, and number of data points in another. This is mostly an issue for human readers, since the XML
standard does not interpret PCDATA.)
The acronym PCDATA means Parsed Character Data and is for the purpose of this specification element
free, free formatted text.
The BM800 XML formatted data is free-format. It is allowed to insert white space at any position allowed by
XML standards. At least one white space character is required in some character data to separate data
elements. White space characters is of course not allowed inside individual character data elements.
Example. "<X>3.14</X>", not "<X>3 . 14</X>". But "<X> 3.14 </X>" is ok. (And increases
the transfer time.)
Bl-1013-02
elektronisk kopia
3. Sample Data Format
A sample result is the actual output produced by the BM800. A sample result may differ in the number of
parameters, the presence of histograms etc.
BM800 defines a lot of parameter names below. They should be unique within the sample definition. BM800
limits parameter names to at most 4 characters. This saves space in the BM800, and time during serial
transfer. The syntax restriction of a parameter name is the same as for a C identifier.
BM800 has a simple XML structure, and use parameters for flexibility instead. This might minimize changes
to the XML structure. External applications should be prepare to handle the addition and removal of
parameters. And also be prepared for values outside of the ranges defined below.
The basic idea is that different BM800 instruments are allowed to dump different parameter lists, but that
one particular instrument should dump the same parameter list for every sample. In the latter case, unused
parameters should be output with a name but without a value. (This can make it easier to go through dump
texts. At least for humans, or very simple text handling programs.)
BM800 splits information in many small, easily parsed pieces instead of combining more than one value as
one parameter. This makes the XML text bigger, but simplifies external applications.
The exception is: "<v>" (list of values) for histograms and raw HGB data.
Note about storing samples in databases: there exist no 100% correct primary key among these parameter
values. But a combination of "SEQ" and "DATE" (in the case of one instrument), or "SNO" (or "IID"
maybe), "SEQ" and "DATE" (in the case of multiple instruments) is probably good enough. (Note: 3.4.1
gives PRDI and SNO as an instrument primary key, but this is probably overkill for a sample primary key.)
Bl-1013-02
elektronisk kopia
Note: The ":Begin:...: " and ":End:...: " XML comments are present during serial transfer for error detection,
flow control and retransmissions. See section 4 for further info.
The parameter name should follow C identifier syntax (see above). By convention, sample result parameter
names use only upper case.
The "<n>" (name) tag must be the first one.
The "<v>" tag is the parameter value. It is present if a valid value of the parameter exists.
Parameters that could be present should be present with their names even if they have no value. Parameters
are not present if:
1) The parameter is not included in the BM800 model, or
2) The parameter is blocked by the user.
Examples:
A parameter without any value etc.
<p><n>APNU</n></p>
The common parameter format is extended for result parameters. See section 3.6.1.
Bl-1013-02
elektronisk kopia
3.4.1. Static Instrument Parameters
The static instrument parameters are parameters that are always the same during the instrument life cycle.
The combination of the PRDI and SNO parameters can be used as a unique identifier (primary key) of an
individual instrument.
3.4.1.1. PRDI - Product Identifier
PRDI identifies the instrument as for example a BM800. This parameter is always present with a value. Its
format is not further defined here. (Other instruments could in theory use this specification.)
<p><n>PRDI</n><v>BM800</v></p>
Bl-1013-02
elektronisk kopia
The parameter order below is not fixed. The parameters might be in another order. Be prepared for added and
removed parameters.
<smpinfo>
<p><n>ID</n>...</p>
<p><n>SEQ</n>...</p>
<p><n>DATE</n>...</p>
<p><n>APNU</n>...</p>
<p><n>APNA</n>...</p>
<p><n>ASPM</n>...</p>
<p><n>ASPS</n>...</p>
<p><n>SORC</n>...</p>
<p><n>BLMD</n>...</p>
<p><n>BLNK</n>...</p>
<p><n>STYP</n>...</p>
<p><n>RGED</n>...</p>
<p><n>RGEL</n>...</p>
<p><n>RGEC</n>...</p><!-- Optional, may be present in vet instruments -->
<p><n>RDLI</n>...</p>
<p><n>RDPN</n>...</p>
<p><n>RDED</n>...</p>
<p><n>RLLI</n>...</p>
<p><n>RLPN</n>...</p>
<p><n>RLED</n>...</p>
<p><n>RCLI</n>...</p><!-- Optional, may be present in vet instruments -->
<p><n>RCPN</n>...</p><!-- Optional, may be present in vet instruments -->
<p><n>RCED</n>...</p><!-- Optional, may be present in vet instruments -->
<p><n>RPD</n>...</p>
<p><n>RPDS</n>...</p>
<p><n>RPDL</n>...</p>
<p><n>RPDH</n>...</p>
<p><n>RPDF</n>...</p>
<p><n>WDDM</n>...</p>
<p><n>WDDP</n>...</p>
<p><n>WDMS</n>...</p>
<p><n>WDMA</n>...</p>
<p><n>WDFB</n>...</p>
<p><n>WDLL</n>...</p>
<p><n>WDLH</n>...</p>
<p><n>WDCL</n>...</p>
<p><n>WDCH</n>...</p>
<p><n>WLGL</n>...</p><!-- Optional, may be present in vet instruments -->
<p><n>WDIL</n>...</p>
<p><n>WDIH</n>...</p>
<p><n>XLT</n>...</p><!-- Optional, may be present in vet instruments -->
<p><n>CAPL</n>...</p>
<p><n>CLVL</n>...</p>
<p><n>CEXP</n>...</p>
<p><n>CEXT</n>...</p>
<p><n>ASWN</n>...</p>
<p><n>ASWP</n>...</p>
</smpinfo>
Bl-1013-02
elektronisk kopia
Note 1: non-numeric characters are allowed in the ID. But leading or trailing white space will be filtered
away.
Note 2: be prepared for non-ASCII characters.
Note 3: All control blood sample ID:s are a number followed by a trailing "+". (The number is normally the
digits of the lot number of the control blood.)
Note 4: leading zero digits in ID numbers are significant.
Note 5: the maximum number of characters in ID numbers may change.
"Blank" ID
<p><n>ID</n></p>
Numeric ID
<p><n>ID</n><v>12356</v></p>
Non-numeric ID
<p><n>ID</n><v>Mrs. Smith</v></p>
Control blood ID
<p><n>ID</n><v>0606123+</v></p>
Bl-1013-02
elektronisk kopia
3.5.1.5. STYP – Sample Type
STYP indicates the sample type, i.e. if the run was a blood or a PLT concentrate sample. This parameter is
always present with a value.
Note: more sample types may be added. They will all be small positive numbers.
Value range:
0: blood
1: PLT concentrate
<p><n>STYP</n><v>0</v></p>
<p><n>ASPM</n><v>OT</v></p>
Bl-1013-02
elektronisk kopia
Value range:
0: not a blank sample
1: a blank sample
<p><n>BLNK</n><v>0</v></p>
RBC
PLT
RPDL RPDH
RPD
(calculated)
Figure 1 Illustration of the RPD floating discriminator and the range limits RPDL and RPDH.
Bl-1013-02
elektronisk kopia
Value range: 0 - 99
Note: the position of this discriminator is included in the PLT and RBC histograms too (see 3.7.2.6), but in
that case as histogram bin indices.
<p><n>RPD</n><v>24</v></p>
Bl-1013-02
elektronisk kopia
the selected method, but it is possible with the fallback method. Fallback is only used when the instrument
configuration allows it, and only in veterinary instruments.
Note 2: more diff methods may be added. They will all be small positive numbers.
Note 3: the value range is 1, 2, 4.
Value range:
1: DM1 human floating
2: DM2 fixed
4: DM4 vet floating
<p><n>WDMS</n><v>1</v></p>
Bl-1013-02
elektronisk kopia
3.5.4.6. WDCL - WBC Calculated Floating Discriminator Low (LYM/MID)
WDCL indicates where a fixed LYM/MID discriminator should be positioned to report the same LYM result
as was calculated using floating discriminators during this sample run. See Figure 2 in section 3.5.4.10 and
substitute WDCL for WDIL. This position is visible in the WBC histogram when the show as lines mode is
enabled. The value is given in the unit fl. This parameter is always present. The value is present only if a
floating differentiation method (DM1 or DM4) is used.
Note: WDCL is also included in the WBC histogram as a discriminator line expressed as a bin number if the
show as lines mode is enabled (see 3.7.2.6).
Value range:
0 - 800
<p><n>WDCL</n><v>111</v></p>
Bl-1013-02
elektronisk kopia
3.5.4.10. WDIH - WBC Fixed Discriminator High (MID-H)
WDIH indicates the high range limit for the fixed WBC discriminator (MID-L). See Figure 2 in section
3.5.4.10. The value is given in the unit fl. The parameter is always present. The value is present only if a
differentiation method with fixed discriminators (DM2) is used, or if a fallback to such a method could have
been used.
Note: WDIL is also included in the WBC histogram as a discriminator line expressed as a bin index (see
3.7.2.6).
A qualified operator can set the value of this parameter.
Value range:
0 - 800
<p><n>WDIH</n><v>130</v></p>
GRAN
LYM
MID
WDIL WDIH
Bl-1013-02
elektronisk kopia
Value range:
0 – 99
<p><n>WDDP</n><v>45</v></p>
3.5.5.4. CEXT - Extra Control Blood Information for a Control Blood with Reference Ranges
CEXT can identify extra control blood info for a control blood with reference ranges. This parameter is
always present. The value is only present if the blood was a control blood with reference ranges, and there is
some extra information.
Value range:
completely TBD
Note: this information might be included in the control blood reference range assay information.
No extra info:
Bl-1013-02
elektronisk kopia
<p><n>CEXT</n></p>
3.5.8. Settings
3.5.8.1. APNU – Analysis Profile Number
APNU is the number of the Analysis Profile (species in vet instruments) selected for the run. This parameter
is always present. The value is present if the blood was not a control blood with reference ranges.
Bl-1013-02
elektronisk kopia
A qualified operator can set the value of this parameter.
Note 1: the upper limit may change.
Note 2: the initial instrument setup uses 1 for the “blood” analysis profile, and 2 for “background”.
Note 3: an analysis profile can have different numbers in different instruments, since a qualified operator can
set up analysis profiles.
Value range: 1 - 15.
<p><n>APNU</n><v>1</v></p>
Bl-1013-02
elektronisk kopia
3.5.9. Reagent statistics
The BM800 instrument has an optional reagent statistics system that keeps track of the reagents used in the
instrument.
Note: The diluent and hemolyzing regent information is exactly the same if a reagent “combo” pack is used.
3.5.9.1. RDLI Reagent Statistics Diluent Lot identifier
RDLI is the lot identifier of the diluent reagent. This parameter is always present. The value is only present if
the reagent statistics system is enabled.
The value is always formatted as “YYMM-NNN”, where YY, MM and NNN are digits. (Normally YY =
production year, MM =production month and NNN = lot sequence number.) See example below.
Note 1: This information comes from the reagent package information.
Note 2: leading zero digits in reagent lot identifiers are significant.
<p><n>RDLI</n><v>0606-123</v></p>
Bl-1013-02
elektronisk kopia
3.5.9.6. RLED Reagent Statistics Hemolyzer Expiry date
RLED is the expiry date of the hemolyzing reagent. This parameter is always present. The value is only
present if the reagent statistics system is enabled.
The value is a date, always formatted according to ISO 8601. See example below.
Note: This information comes from the reagent package information.
<p><n>RLEL</n><v>2006-06-29</v></p>
Bl-1013-02
elektronisk kopia
<p><n>HGB</n>...</p>
<p><n>WBC</n>...</p>
<p><n>LA</n>...</p> <!-- LYM# -->
<p><n>MA</n>...</p> <!-- MID# -->
<p><n>GA</n>...</p> <!-- GRAN# -->
<p><n>LR</n>...</p> <!-- LYM% -->
<p><n>MR</n>...</p> <!-- MID% -->
<p><n>GR</n>...</p> <!-- GRAN% -->
</smpresults >
Bl-1013-02
elektronisk kopia
3.6.1.5. <h> - Parameter Normal/Reference Range High
The "<h>" tag is always present. Its value is the high end of the normal / reference range. If the parameter
value is exactly equal to "<h>", then it is within the normal / reference range.
See the <v> tag above for information about values ranges etc.
3.6.1.6. Examples
Examples:
A result parameter could be without any value, for example if the value could not be calculated:
<p><n>MCV</n><l>70.0</l><h>100.0</h></p>
Or it could have an out-of-range flag instead of a value (possibly with an error flag too).
<p><n>HGB><r>H</r><l>12.5</l><h>16.5</h></p>
Bl-1013-02
elektronisk kopia
WBC White blood cell concentration 109/l White side counting succeeded.
LA Lymphocyte concentration 109/l White side counting succeeded,
enough cells counted, and WBC
diff calculation succeeded.
MA Mid concentration 109/l White side counting succeeded,
enough cells counted, and WBC
diff calculation succeeded.
GA Granulocyte concentration. 109/l White side counting succeeded,
enough cells counted, and WBC
diff calculation succeeded.
LR Lymphocyte concentration, relative total % White side counting succeeded,
WBC. enough cells counted, and WBC
Given in percent (%). diff calculation succeeded.
MR Mid concentration, relative total WBC. % White side counting succeeded,
Given in percent (%). enough cells counted, and WBC
diff calculation succeeded.
GR Granulocyte concentration, relative total WBC. % White side counting succeeded,
Given in percent (%). enough cells counted, and WBC
diff calculation succeeded.
Bl-1013-02
elektronisk kopia
</hgdata>
</hgram>
<hgram>
<n>RBC</n><m>250</m><k>80</k><w>2</w><d>8</d>
<hgdata>
<v>
0 1 3 1 ... <!-- 80 numbers in total, separated by white space -->
</v>
</hgdata>
</hgram>
<hgram>
<n>WBC</n><m>450</m><k>80</k><w>4</w><d>8</d>
<hgdata>
<n>LYM</n>
<v>
0 0 1 3 5 ... <!-- 80 numbers in total, separated by white space -->
</v>
</hgdata>
<hgdata>
<n>MID</n>
<v>
0 0 0 0 0 ... <!-- 80 numbers in total, separated by white space -->
</v>
</hgdata>
<hgdata>
<n>GRA</n>
<v>
0 0 0 0 0 ... <!-- 80 numbers in total, separated by white space -->
</v>
</hgram>
</hgrams>
Bl-1013-02
elektronisk kopia
3.7.1. <hgrams> - Histograms Section
The <hgrams> section collects all the histograms (<hgram>) in this sample.
The <hgrams> section is optional. The operator can enable and disable the inclusion om the <hgrams>
section> in the sample data. The control memory has no histogram data.
Bl-1013-02
elektronisk kopia
Note 2: Do not assume that all histograms in one sample have the same number of data points. This may
change. Exception: the "LYM", "MID", "GRA" histograms must of course have the same number of data
points, since they are overlaid to create a single three-population histogram.
3.7.2.5. <w> - Histogram Filter Factor
The "<w>" tag is specifies the filter factor and indicates how hard the instrument has filtered the histogram.
The values 0 and 1 mean no filtering while 2, 3, 4, … mean increasingly harder filtering. (If a max filter
factor is needed, set it to “<k>/2”.)
Qualified operators can set the value of this tag.
3.7.2.6. <d> - Histogram Discriminator Index
The "<d>" tag(s) optionally specifies the indices of the bins where the discriminators are positioned in the
histogram. This tag is optional. A histogram may have more than one discriminator, so the tag may be
present more than once.
The histogram discriminator index is zero-based.
Unit: data point index. In the example above 64 for "PLT" gives a scale value of <d>*(<m>/<k>) =
64*(30/80) = 24.
Note 1: The exact definition of the scale values for the bins of the histogram is a bit fuzzy. And so is the
exact definition of the discriminator position: is it supposed to be at the left edge, in the middle or at the right
edge of the position range for a certain bin(?).(Assume for now that it is in the middle.)
Note 2: Do not assume that the maximum number of discriminator lines is 3. (At least not during
development.) If a fixed maxis needed, use 8 (is possible) until further notice.
Note 3: do not assume that the discriminators are output with ascending positions.
Note 4: The discriminator for the PLT and RBC histograms is also included as RPD (see 3.5.3.1).
Note 5: The discriminators for the WBC histograms is also include as WDIL (see 3.5.4.9) / WDIL (see
3.5.4.10) or WDCL (see 3.5.4.6) / WDCH (see 3.5.4.7), plus WDDP (see 3.5.4.12).
Bl-1013-02
elektronisk kopia
Index range:
0 - "<k>-1"
Note: Try to apply some formatting to the data point numbers. For instance output 80 data points as 5 rows
with 16 data points each. (This is mainly for those human readers who are able to “see” the histogram by
looking at the data values.)
4. Transport Package
The data that belongs to a certain sample run and is represented by the XML structure described in section 3
is subject to be transferred via the communication port (today RS232) of the instrument. To ensure that the
sample data is correctly transferred BM800 needs to add some mechanisms related to the transport level of a
protocol stack. This specification therefore defines the term package. A package has the following logical
structure:
{Checksum begin}
{Message begin}
{Message content/“Payload”. Here Sample Data.}
{Message end}
{Checksum end}
So what BM800 actually sends over the communication link are packages, one package per sample.
The Checksum part is described in section 4.2 while the Message part is described in section 4.3.
{Algorithm ID} Corresponds to an integer that identifies what checksum algorithm that has been
used. The different check sum algorithms are described in section 4.2.2.
{Checksum...} Is the optional checksum for the checksum with a certain algorithm ID. Disregard
when not implementing an algorithm ID.
Checksum end token, algorithm 1:
Bl-1013-02
elektronisk kopia
<!--:End:Chksum:1:{Checksum byte 1}:{Checksum byte 2}:-->
The checksum tokens have the syntax of an XML comment (surrounded by the “<!—“ and “-->“ tokens) to
not break the XML structure of the sample data described in section 3 and hence the data may be displayed
in any XML viewer application.
The checksum is calculated for every character (byte) that exist after the “>” character in the checksum begin
token and up to but not including the “<” character in the checksum end token. This means that white spaces
and new lines also are included in the checksum calculation, including newlines at the beginning and at the
end. Notice though that new lines are handled according to the XML standard, i.e. they are always replaced
with the line feed character (ASCII 10) as described in section 4.2.1.
The data between checksum begin and end tokens should be considered as a “byte stream” and hence the
format of the data is irrelevant. Note that no XML parsing of the data should be performed before the
checksum calculation.
Bl-1013-02
elektronisk kopia
void
cs_calc( const unsigned char buf[], // Pointer to buffer
unsigned start, // Index of first check summed byte
unsigned lim, // Index of last+1 check summed byte
unsigned char cs[2] ) // Output checksum
{
unsigned char cs1 = 0, cs2 = 0;
for( ; start < lim; ++start ){
cs1 += buf[start];
cs2 += cs1;
}
cs[0] = cs1;
cs[1] = cs2;
}
The correct result when checking check summed data is "cs[0]==0 && cs[1]==0".
This is how to set the checksum in the two last bytes in a buffer, so it has a correct checksum:
void
cs_set( unsigned char buf[], // Pointer to buffer (2 bytes changed)
unsigned start, // Index of first check summed byte
unsigned lim ) // Index of last+1 check summed byte
{
// precond: start+2 <= lim
unsigned char cs[2];
buf[lim-2] = buf[lim-1] = 0; // Init checksum bytes for calc
cs_calc( buf, start, lim, cs );
buf[lim-2] = cs[0] - cs[1];
buf[lim-1] = cs[1] - 2*cs[0];
}
buf[lim-2] and buf[lim-1] shall be inserted as Checksum byte 1 and Checksum byte 2 in Checksum
end token, algorithm 1 during transfer. They shall not be included in the package content!
C# Code sample:
The data to be check summed is stored in the msg string variable. The two checksums are returned in the out
parameters checksum1 and checksum2.
private void CalcCheckSum(string msg, out byte checksum1, out byte
checksum2)
{
byte cs1 = 0;
byte cs2 = 0;
checksum1 = cs1;
checksum2 = cs2;
}
Bl-1013-02
elektronisk kopia
Then add the checksums read from the transferred package to the calculated checksums in the following
way:
checksum1 += transferredChecksum1;
checksum2 += checksum1;
checksum1 += transferredChecksum2;
checksum2 += checksum1;
Message end:
<!--:End:Msg:{Message ID}:{Acknowledge flag}:-->
{Message ID} The message ID is an integer that identifies the message in a sufficiently unique
way. The message ID is a sequential number that may be used to detect if any
complete package has been lost. The algorithm for ID assignment to a message is
described in section 4.3.1.
{Acknowledge flag} The acknowledge flag is set to 1 by the transmitting side to indicate that an
acknowledge message is expected by the transmitting side and 0 if no acknowledge
is expected. The acknowledge management is described in section 4.3.2.
Example:
<!--:Begin:Msg:3:0:-->
{Message content}
<!--:End:Msg:3:0:-->
4.3.1. Message ID assignment
The message ID is a single digit number. The transmitting side sets the message ID in transmitted messages.
The transmitting side must have a variable containing the next message ID of the next numbered message.
The transmitting side sets the message ID of the next numbered message to 1 during initialisation. Then the
transmitting side updates the message ID of the next numbered message after every completed transmission
according to the table below. (In the presence of acknowledges: completed = after receiving an acknowledge
message, or giving up re-transmitting.)
The receiving side must have a variable containing the message ID of the last received numbered message.
The receiving side sets the message ID of the last received numbered message during initialisation so it does
not match any valid message ID (Suggestion: initialize it to 10). Every time the receiving side receives a
numbered message, it sets the message ID of the last received numbered message to the message ID of the
last numbered message received.
The BM800 sets the message ID of the next numbered message to 1 during “power up” and “exit standby”.
BM800 may also sets the message ID of the next numbered message to 1 at other times.
The possible values for message ID:s are:
0 This message is unnumbered, and is not included in the sequence of numbered
messages. (This should only be used during development, since it is impossible to
detect duplicate messages by looking at the message ID alone.)
1 This message is the initial message of a sequence of numbered messages.
Bl-1013-02
elektronisk kopia
2–9 This message is one of the non-initial messages of a sequence of numbered
messages.
If the message ID of a transmitted message is: The message ID of the next numbered message
should be:
0 Unchanged.
1 Set to 2.
2–8 Set to current message number + 1.
9 Set to 2.
Example:
The transmitted message ID:s of a normal sequence of numbered messages:
1 2 3 4 5 6 7 8 9 2 3 4 5 6 7 8 9 2...
Example:
The transmitted message ID:s of a sequence of numbered messages with two unnumbered messages inserted:
1 0 2 3 4 5 6 7 8 9 2 3 4 5 0 6 7 8 9 2...
Example:
The transmitted message ID:s of a sequence of numbered messages where the transmitting side re-initialise
the sequence of numbered message:
1 2 3 4 5 6 7 8 9 2 3 1 2 3 4 5 6 7 8 9 2 3 4 5 6 7 8 9 2...
{Message ID} The message ID of the acknowledge message shall be set to the message ID of the
message it acknowledges.
{Acknowledge type} The receiving side sets to acknowledge type to indicate if the message content
was accepted. The acknowledge type shall be set according to the following table.
Acknowledge type Description
0 The message was received correctly, and has been accepted.
1 The message was received correctly, but was not accepted due to some temporary
condition that will probably disappear in the near future. The BM800 instrument can
not handle some messages during cycle runs, for example. The transmitting side can
either report this as an error, or retransmit the same message at a later time (and with
an updated message ID).
Note: The BM800 instrument does not retransmit messages in this case. It reports an
error instead.
2 The message was received correctly, but was not accepted due to some permanent
condition. Example: the message had indeed a correct checksum, but contained
malformed XML data.
Note: The BM800 instrument reports an error in this case.
Example of an acknowledge message for an accepted message, with a correct checksum of type 1:
<!--:Begin:Chksum:1:--><!--:Ack:Msg:3:0:--><!--:End:Chksum:1:184:62:-->
Bl-1013-02
elektronisk kopia
4.3.3. Retransmission of lost messages
If the transmitting side transmits a message with the acknowledge flag set 1, the receiving side shall return an
acknowledge message as soon as possible. If the transmitting side does not receive an acknowledge message
with the right message ID within a suitable time, it shall retransmit exactly the same message, including the
same message ID.
The transmitting side shall repeat this process a suitable number of times.
The BM800 instrument has an acknowledge timeout of 5 seconds from the transmission of the last character
in the message
The BM800 instrument sends each message at most 3 times (=1 initial transmission and up to 2
retransmissions).
4.3.7. Handling of packages that fails the checksum test, or has transport package or message
format errors
The receiving side shall drop all received packages that fails the checksum test (see 4.2).
The receiving side shall also drop all received packages which does not conform to the transport package
format or message format described here.
The receiving side may take some suitable action (like logging the event) when any of this happens.
Bl-1013-02
elektronisk kopia
(Note: there may be receiving side applications which acknowledges all correctly received messages, but
does not do any interpretation of the message content. Not even checking if it seems to be in XML format.)
Note: the BM800 instrument acknowledges badly formatted messages content with an acknowledge message
with the acknowledge type set to 2.
5. References
[1] DuCharme, Bob. “XML- The Annotated Specification”, 1999, ISBN 0-13-082676-6.
Bl-1013-02
elektronisk kopia