Campbell BMP5 User Guide

BMP5 Transparent Commands

Revision: 9/08

Copyright © 2005-2008

Campbell Scientific, Inc.

BMP5 Transparent Commands
Table of Contents

PDF viewers note: These page numbers refer to the printed version of this document. Use
the Adobe Acrobat® bookmarks tab for links to specific sections.

1. Introduction...............................................................1-1

1.1 Communication Layers......................................................................... 1-1

1.2 Packet Structure.................................................................................... 1-2

1.2.1 PakBus Packet Framing and Quote Bytes................................... 1-2

1.3 PakBus Packet Headers ........................................................................1-3

1.4 Encoding and Decoding Packets .......................................................... 1-4

1.4.1 Quoting the Message Body and Signature Nullifier................... 1-4

1.4.2 Unquoting the Message Body and Signature Nullifier............... 1-4

1.4.3 Signature Nullifier ...................................................................... 1-4

1.4.4 Packet Processing Checklist........................................................ 1-4

2. Protocols and Packet Types....................................2-1

2.1 SerPkt Link-State Sub-Protocol............................................................ 2-1

2.2 PakBus Control Packets (PakCtrl)........................................................2-2

2.2.1 Delivery Failure Message (MsgType 0x81) ...............................2-2

2.2.2 Hello Transaction (MsgType 0x09 & 0x89)............................... 2-3

2.2.3 Hello Request Message (MsgType 0x0e)................................... 2-4

2.2.4 Bye Message (MsgType 0x0d)................................................... 2-5

2.2.5 Get/Set String Settings Transactions (MsgType 0x07, 0x87,

0x08, 0x88) .................................................................................... 2-5

2.2.6 DevConfig Transactions .............................................................2-6

2.2.6.1 DevConfig Get Settings Message (MsgType 0x0f &

0x8f)........................................................................................ 2-7

2.2.6.2 DevConfig Set Settings Message (MsgType 0x10 &

0x90) .......................................................................................2-8

2.2.6.3 DevConfig Get Setting Fragment Transaction Message

(MsgType 0x11 & 0x91)......................................................... 2-9

2.2.6.4 DevConfig Set Setting Fragment Transaction Message

(MsgType 0x12 & 0x92)......................................................... 2-9

2.2.6.5 DevConfig Control Transaction Message (MsgType

0x13 & 0x93)........................................................................ 2-10

2.3 BMP5 Application Packets.................................................................2-11

2.3.1 Please Wait Message (MsgType 0xa1)..................................... 2-12

2.3.2 Clock Transaction (0x17 & 0x97) ............................................2-12

2.3.3 File Transfer and Control Transactions .................................... 2-13

2.3.3.1 File Download Transaction (MsgType 0x1c & 0x9c)..... 2-13

2.3.3.2 File Upload Transaction (MsgType 0x1d & 0x9d)......... 2-14

2.3.3.3 File Directory Format......................................................2-15

2.3.3.4 File Control Transaction (MsgType 0x1e & 0x9e)......... 2-15

2.3.3.5 Get Programming Statistics Transaction (MsgType

0x18 & 0x98)........................................................................ 2-17

i

BMP5 Transparent Commands Table of Contents

2.3.4 Data Collection and Table Control Transactions ......................2-17

2.3.4.1 Table Definitions.............................................................2-17

2.3.4.2 Getting Table Definitions and Table Signatures..............2-18

2.3.4.3 Collect Data Transaction (MsgType 0x09 & 0x89)........2-19

2.3.4.4 One-Way Data Transaction (MsgType 0x20 & 0x14).... 2-20

2.3.4.5 Table Control Transaction (MsgType 0x19 & 0x99)......2-22

2.3.5 Get/Set Values Transaction (MsgType 0x1a, 0x9a, 0x1b,

& 0x9b).........................................................................................2-23

3. The CR200 Datalogger............................................. 3-1

3.1 Dealing with Unexpected, Asynchronous Commands from the CR2003-1

3.2 Getting the Attention of the Datalogger................................................3-1

3.3 Getting the PakBus Address of the CR200...........................................3-2

3.4 Getting and Setting CR200 Settings .....................................................3-2

3.5 Getting and Setting the CR200 Clock................................................... 3-3

3.6 Datalogger Program Structure ..............................................................3-3

3.7 Creating CR200 Programs and the CR200 Compiler...........................3-4

3.7.1 Discovering the CR200 OS Version ...........................................3-4

3.7.2 Sending a Program to the CR200................................................3-5

3.7.3 Interpreting the Response............................................................ 3-7

3.7.4 Handling Rejection......................................................................3-7

3.8 Understanding Table Definitions and Table Signatures .......................3-8

3.9 Getting Table Definitions from the CR200...........................................3-8

3.9.1 How to Get and Use Table Signatures ........................................3-8

3.10 Retrieving Data from the CR200........................................................3-9

3.10.1 Interpreting Data Types.............................................................3-9

3.10.2 Data Collection Sequence .........................................................3-9

3.10.3 Collecting Tables and Specific Records..................................3-10

3.10.4 Getting Values from Specific Records....................................3-11

3.11 Controlling Packet Size.....................................................................3-11

4. The CR1000 Type Datalogger ................................. 4-1

4.1 Dealing with Unexpected Commands...................................................4-1

4.2 Getting the Attention of the Datalogger and Establishing a Baud Rate 4-1

4.3 Getting the PakBus Address .................................................................4-2

4.4 Getting and Setting Datalogger Settings...............................................4-2

4.5 Getting and Setting the Clock...............................................................4-3

4.6 The Program Structure..........................................................................4-3

4.7 Sending a Program to the Datalogger................................................... 4-4

4.7.1 Interpreting the Response............................................................ 4-6

4.7.2 Handling Rejection......................................................................4-6

4.7.3 Erasing Files on the CFM100......................................................4-6

4.7.4 Deleting Program Files................................................................4-7

4.8 Understanding Table Definitions and Table Signatures .......................4-7

4.9 Getting Table Definitions......................................................................4-8

4.9.1 How to Get and Use Table Signatures......................................... 4-8

4.10 Retrieving Data...................................................................................4-8

4.10.1 Interpreting Data Types.............................................................4-9

4.10.2 Data Collection Sequence .........................................................4-9

4.10.3 Collecting Tables and Specific Records....................................4-9

4.10.4 Getting Values from Specific Records....................................4-10

ii

BMP5 Transparent Commands Table of Contents

4.11 Collecting Files from the Datalogger................................................ 4-11

4.12 Controlling Packet Size ....................................................................4-11

Appendices

A. Data Types Summary .............................................A-1

B. Calculating Packet Signatures and the

Signature Nullifier................................................. B-1

C. Device Description Files.........................................C-1

D. JAVA Example Code...............................................D-1

Glossary

iii

BMP5 Transparent Commands Table of Contents

iv

Section 1. Introduction

This document outlines the structure for a fundamental subset of protocols and packet
types used to communicate directly with a single P
packet types discussed in this document are collectively referred to as BMP5 and are used
to communicate with Campbell Scientific’s native PakBus dataloggers (CR200 Series,
CR1000, CR3000, etc.). This documentation assumes the communication link to the
datalogger has already been established. Therefore, packets are created, sent, and
received over a transparent link directly to and from a single datalogger.

While this document only discusses essential packet types that facilitate communication
with a single datalogger, the creation of these packets requires an understanding of packet­switched protocols. With this understanding and through the use of this reference, a
developer should be able to send basic packets to and receive packets from a Campbell
Scientific CR200 or CR1000 type datalogger.

1.1 Communication Layers

Like other types of packet switched communication protocols such as TCP/IP,
transparent BMP5 communication relies on a low-level network protocol and
higher application level protocols. These different protocol layers exist to
facilitate communication between applications and nodes across a given
medium. The benefit of using protocol layers is that each layer becomes
responsible for a specific function that assists communication. Since these
functions are presented in manageable blocks, end-to-end communication is
easier because each layer focuses on a single responsibility.

AKBUS® datalogger. The protocols and

The way a single layer handles a specific task internally can change as long as
communication to the protocol layer above and the protocol layer below
continues to function in the same manner. For example, the command to check
a datalogger clock may exist in the application layer while a separate layer
handles the connection. As long as these separate layers communicate with
each other, the information can be organized and sent across the network as a
complete packet.

The protocol types discussed in this document are the SerPkt Protocol used to
monitor the state of the communication link, the PakBus Control Protocol
(PakCtrl) used to facilitate PakBus network-level services, and the BMP5
Protocol used to send application messages. An understanding of these
message types and the packet structure for these protocols will be necessary to
send basic packets to and receive basic packets from a native PakBus
datalogger.

1-1

Section 1. Introduction

t

t

1.2 Packet Structure

1 byte

Header (8 bytes)

Message (0...998 bytes)

Source node ID 12 bits MSB first

Hop coun t 4 bits

Destination node ID 12 bi ts MSB first

Hi proto code 4 bits

Source physical address 12 bits MSB firs

Priority 2 bits

1 byte2 bytes

Signature Nullifier

Message Body

Transaction ID 1 byte

Message type 1 byte

The first an d last bytes are 0xbd t o mark the beginning and end of a packet

1.2.1 PakBus Packet Framing and Quote Bytes

Expect more code 2 bits

Destination physical a d dress 12 bits MSB firs

Link State 4 bits

PakBus data packets always end with a reserved or special byte code called a
SerSyncByte (0xbd

1

) used to identify and isolate each complete packet. Also,
one or more SerSyncBytes are transmitted before a data packet. Sending extra
SerSyncBytes through an RS-232 interface will clear residual characters from
the receiving node’s input buffer or wake the node up in preparation for
communication.

1

The character string (0xbd) designates that the characters “bd” are actually
hexadecimal representations of the values within the transmission. The
character sequence “0x” is a common hexadecimal prefix notation and is used
throughout this document when referring to hexadecimal values. Please note
that when viewing included log files, the characters “bd” will appear without
the “0x” prefix. For reference, the hexadecimal value “b” correlates to the
decimal value “11” or the binary value of “1011” while the hexadecimal value
“d” correlates to the decimal value “13” or the binary value of “1101”.

1-2

To ensure that a SerSyncByte doesn’t appear inadvertently within the message
data, it must be recognized and quoted within the body of the packet before the
packet is transmitted. The quoting process is accomplished by replacing
reserved bytes with a special code called the QuoteByte. Both SerSyncBytes
and QuoteBytes must be found in the packet body and replaced with the
following sequence:

SerSyncByte (0xbd) becomes (0xbc 0xdd)
Quote Byte (0xbc) becomes (0xbc 0xdc)

Remember that when receiving a packet, the quoted two-byte codes must be
recognized and replaced within the message body by its corresponding value in
order to interpret the data correctly.

1.3 PakBus Packet Headers

Along with a SerSyncByte, each packet must contain a PakBus header with the
appropriate information to complete the transaction. The header will contain
the following:

PakBus Header Information:

Name Type Description

LinkState bits 7..4 The state of the link described binaurally:

1000: off-line
1001: ring
1010: ready
1011: finished

1100: pause
DstPhyAddr 12 bits Address where this packet is going (MSB first)
ExpMoreCode bits 7..6 Describes whether the client should expect

another packet from this transaction.

0x00: This is the last message to this

destination from this source

0x01: Expect more messages to this destination

from the same source

0x02: Neutral message that has no impact on

whether to expect more

0x03: Expect more messages in the reverse

direction
Priority bits 5..4 The message priority on the network. Ranges

from the lowest priority, 00, to the highest

priority, 03. Priority 01 will be sufficient for

normal communication.
SrcPhyAddr 12 bits Address of the node that sent the packet (MSB

first)
HiProtoCode bits 7..4 Designates the type of higher level protocol

that will be contained in this packet:

0x00: PakCtrl Message

0x01: BMP5 Message
DstNodeId 12 bits Node ID of the message destination (MSB

first)
HopCnt bits 7..4 Always zero when connected directly
SrcNodeId 12 bits Node Id of the message source (MSB first)

Section 1. Introduction

1-3

Section 1. Introduction

1.4 Encoding and Decoding Packets

Reserved characters must be acknowledged and quoted by the application
before sending a packet and also recognized and decoded before the application
processes a packet. These reserved characters are the SerSyncByte, 0xbd, and
the QuoteByte, 0xbc. When these special characters are found within the
message body or signature nullifier, they must be handled appropriately.

1.4.1 Quoting the Message Body and Signature Nullifier

Use a QuoteByte, 0xbc, to mark places in the message body or signature
nullifier where the SerSyncByte, 0xbd, or the QuoteByte, 0xbc, appear before
transmitting the packet. The value of the byte following the QuoteByte is the
sum of the quoted character and 0x20. All packets sent by the application must
encode the message body and signature nullifier in this manner. An example
of packet encoding can be found in the JAVA code in Appendix D.

1.4.2 Unquoting the Message Body and Signature Nullifier

When a packet is received, the application must parse through the message and
signature nullifier to find and replace any reserved characters that have been
quoted before processing the message. An example of decoding a packet can
be found in the JAVA code in Appendix D.

1.4.3 Signature Nullifier

In addition to the PakBus header and packet framing implementation, packets
are checked for errors through the use of a two-byte signature nullifier at the
end of the data frame. The signature nullifier is a two-byte code that when
calculated with the rest of the data frame results in a signature value o f zero.
Of course, the packet must be unquoted prior to the signature calculation
process.

Checking the packet integrity with a signature nullifier enables the application
to calculate a running signature as bytes are received and then simply check to
see if the signature is zero when the trailing SerSyncByte is received. If the
signature is zero, the framed data must be correct and can be confidently
processed. Otherwise, the data has become corrupt and must be discarded.

Please note that the signature nullifier field must always be checked to ensure
that reserved characters are quoted before transmitting the message and
decoded before processing a received message. Additional descriptions of the
signature and signature nullifier algorithms and example C code can be found
in Appendix B. An additional example of the signature and signature nu llifier
algorithm can be found in the JAVA code in Appendix D.

1.4.4 Packet Processing Checklist

Data packets received by an application must be examined and processed. The
necessary steps to accomplish this process first require that all reserved
characters be unquoted in the message body and signature nullifier. After all
special characters are unquoted in the packet and signature nullifier but before

1-4

Section 1. Introduction

processing the packet information, the application should make the following
checks:

1. Check the length of the packet. If the entire packet length is less than 4

bytes or greater than 1010 bytes, it should be considered invalid and
discarded.

2. The DstPhyAddr and DstNodeId fields within the packet header should

both equal the address of the application or the broadcast address.

3. The SrcPhyAddr and SrcNodeId in the header should be equal to the

address of the datalogger with which the application is commun icating.

4. The signature of the entire packet, excluding the SerSyncBytes, should be

zero. A non-zero signature indicates a corrupt data packet.

1-5

Section 1. Introduction

This is a blank page.

1-6

Section 2. Protocols and Packet Types

Packet types from three distinct protocols are described in this document. The SerPkt
Protcol used to monitor the state of the communication link, the PakBus Control Protocol
(PakCtrl) used to facilitate PakBus network-level services, and the BMP5 Protocol used to
send application messages.

2.1 SerPkt Link-State Sub Protocol

SerPkt protocol allows the application and the datalogger to track and control
the state of their communication link on the network. The application can
request the datalogger’s state before attempting to send messages with a “ring”
packet. If the datalogger responds with a “ready” packet, the application
should be able to proceed with communication.

Some possible link-states sent by the application and a possible response from
the datalogger, depending on the state of the device, include but are not limited
to the following few examples:

Ring –> Ready
Ready with a message –> Ready with data
Finished with a message –> Ready with data
Finished –> Off-line
Pause –> Finished with or without data

The SerPkt protocol discussed in this section is the Link-state Sub Protocol. If
the developer can communicate between the application and the datalogger
with this protocol layer, all other protocols discussed in this document should
be implemented easily as additional layers working with this SerPkt protocol.

With Link-state Sub Protocol communication, a node initiates a link check and
the receiving node responds with a corresponding Link-st ate Sub Protocol
packet declaring the current state. Packets with four bytes of data will only
contain the state of the communications link while packets with more than four
bytes of data will contain additional link information and possibly even
message data. The format for this packet is outlined in the following table.

2-1

Section 2. Protocols and Packet Types

Link-State Sub-protocol Packet Format:

Name Type Description

LinkState bits7..4 The packet type and the link state:

DstPhyAddr 12 bits Address where this packet is going
ExpMoreCode bits 7..6 Expect more communication with this same

Priority bits 5..4 Priority – Ranges from 0 as the lowest priority

SrcPhyAddr 12 bits Address of the node sending this packet
{ HiProtoCode bits 7..4 Designates the higher level protocol
DstPBAddr 12 bits Address where this packet is going
HopCnt bits 7..4 Hop count – measured from the source node
SrcPBAddr 12 bits Address of the node sending this packet
{ MsgData }} Byte [ ] Message data

1000: Off-line
1001: Ring
1010: Ready
1011: Finished
1100: Pause

destination-source pair soon described
binaurally:
00: Last
01: Expect more
10: Neutral
11: Reverse

to 3 as the highest priority

2.2 PakBus Control Packets (PakCtrl)

The PakBus Control Protocol (PakCtrl) facilitates communication and network
management on the PakBus network by exchanging information between
network nodes. Along with the standard PakBus header and SerSyncByte
framing characters, all PakCtrl protocol message bodies also include a two­byte header consisting of a message type code used to uniquely identify the
format of the rest of the message and a transaction number used to detect
orphaned transactions. While the message type code must be specific to the
message that follows, the application assigns and monitors the transaction
number for each packet.

The PakCtrl message types that an application must be aware of and
understand include the following:

2.2.1 Delivery Failure Message (MsgType 0x81)

The delivery failure or fault message is generated at any node on th e network
when a message cannot be delivered. To avoid an endless loop, fault messages
are not generated when an existing fault m essage cannot be delivered.

2-2

Section 2. Protocols and Packet Types

Delivery Failure Message Format (MsgType 0x81):

Name Type Description

MsgType Byte Message type code (0x81)
TranNbr Byte Transaction number (always zero)
ErrCode Byte Failure code:

0x01: Unreachable
0x02: Unreachable higher level protocol
0x03: Queue overflow (timed out or out of
resources)
0x04: Unimplemented command or MsgType
0x05: Malformed message
0x06: Link failed

HiProtoCode bits 7..4 High level protocol code from the original

message

DstPBAddr 12 bits Destination node address from the original

message
HopCnt bits 7..4 Hop count from the original message
SrcPBAddr 12 bits Source node address from the original message
MsgData Byte [0..16] Up to 16 bytes of MsgData from the original

message

2.2.2 Hello Transaction (MsgType 0x09 & 0x89)

The Hello transaction is used to verify that two-way communication can occur
with a specific node. An application does not have to send a Hello command to
the datalogger but the datalogger may send a Hello command to which the
application should respond.

It is important that the application copy the exact transaction number from the
received Hello command meassage into the Hello response sent to the
datalogger. Since the application is connected directly to the datalogger, the
hop metric received in the command message packet from the datalogger can
be copied by the application and inserted in the response message packet. In
addition, the application should not identify itself as a router in the IsRouter
parameter of the response message packet.

Hello Command Message Format (MsgType 0x09):

Name Type Description

MsgType Byte Message type code (0x09)
TranNbr Byte Transaction number
IsRouter Byte Indicates whether the source node is a router:

0x00: False

0x01: True

2-3

Section 2. Protocols and Packet Types

Name Type Description

HopMetric Byte A code used to indicate the worst case interval

VerifyIntv Uint2 Link verification interval in seconds

Hello Response Message Format (MsgType 0x89):

Name Type Description

MsgType Byte Message type code (0x89)
TranNbr Byte Transaction number
IsRouter Byte Indicates whether the source node is a router.

HopMetric Byte A code used to indicate the worst case interval

VerifyIntv Uint2 This value is the link verification interval from

for the speed of the link required to complete a
transaction (default value of 0x02):
0x00: 200 msec or less
0x01: 1 sec or less
0x02: 5 sec or less (default for RS232 or
TCP/IP)
0x03: 10 sec or less
0x04: 20 sec or less
0x05: 1 min or less
0x06: 5 min or less
0x07: 30 min or less

The application should specify 0x00 (False)
indicating it is not a router in the response
message.
0x00: False
0x01: True

for the speed of the link required to complete a
transaction (default value of 0x02). The
application should copy the value from the
command message :
0x00: 200 msec or less
0x01: 1 sec or less
0x02: 5 sec or less (default for RS232 or
TCP/IP)
0x03: 10 sec or less
0x04: 20 sec or less
0x05: 1 min or less
0x06: 5 min or less
0x07: 30 min or less

the Hello Command message divided by 2.5.

2-4

2.2.3 Hello Request Message (MsgType 0x0e)

A one-way message used to trigger a Hello transaction from the recipient. Use
this message to initiate communication with a node when the address of the
node is not known. If the application receives a Hello Request message from a
datalogger, the best course of action is to return a Hello Message to the
datalogger.

Hello Request Message Format (MsgType 0x0e):

Name Type Description

MsgType Byte Message type code (0x0e)
TranNbr Byte Transaction number (always zero)

2.2.4 Bye Message (MsgType 0x0d)

The Bye Message is a one-way message that lets a node on the network know
that the link is shutting down and that the nodes will no longer be able to talk
to each other. Before shutting down a link, like a phone modem connection, it
is good practice to always send a Bye Message.

Bye Message Format (MsgType 0x0d):

Name Type Description

MsgType Byte Message type code (0x0d)
TranNbr Byte Transaction number (always zero)

Section 2. Protocols and Packet Types

2.2.5 Get/Set String Settings Transactions (MsgType 0x07,
0x87, 0x08, 0x88)

Both the Get Settings and Set Settings transactions are used exclusively when
reading or writing settings in a CR200 series datalogger but only has limited
usage for settings within a CR1000 type datalogger. These datalogger settings
exist as a list of ASCII text variables within the datalogger and are used by the
datalogger like environment variables are used by a personal computer.

Get Settings Command Message (MsgType 0x07):

Name Type Description

MsgType Byte Message type code (0x07)
TranNbr Byte Transaction number
NameList ASCIIZ List of names for which you want values. The

names will be separated with an ASCII semi­colon character. If this is an empty string, the
datalogger will respond with all settings.

Get Settings Response Message (MsgType 0x87):

Name Type Description

MsgType Byte Message type code (0x87)
TranNbr Byte Transaction number
Settings ASCIIZ A string containing a list of name-value pairs

with each name separated by the value with the
“=” sign. Each value-pair is separated with a
semi-colon. For example:
Model=CR200;PakBusAddress=1;

2-5

Section 2. Protocols and Packet Types

Set Settings Command Message (MsgType 0x08):

Name Type Description

MsgType Byte Message type code (0x08)
TranNbr Byte Transaction number
Settings ASCIIZ A string containing a list of name-value pairs

Set Settings Response Message (MsgType 0x88):

Name Type Description

MsgType Byte Message type code (0x88)
TranNbr Byte Transaction number
RespCode Byte Response code:

{ FailOffset } UInt2 Offset from the start of the settings string to the

with each name separated by the value with the
“=” sign. Each value-pair is separated with a
semi-colon. For example:
Model=CR200;PakBusAddress=1;

0x00: Complete
0x01: Read-only
0x02: Out of space
0x03: Syntax error
0x04: Access denied

name of the variable that caused the command
to be rejected.

If a list of variables is specified while using the Set Settings transaction, the
datalogger will process the settings one at a time until it finishes or until a
setting fails to process. When a failure occurs, the response message will
report the offset into the settings string where the offending setting starts. All
settings up to the offending one are acceptable but the settings after the
offending setting have not been evaluated by the datalogger.

Some examples of possible settings include:

• Model: The datalogger model name or number

• Version: The version of the datalogger

• SerialNbr: The serial number of the datalogger

• PakBusAddress: The PakBus address of the datalogger

2.2.6 DevConfig Transactions

Applications should use the DevConfig transactions to get settings from and set
settings in a CR1000 type datalogger. The DevConfig transactions are a subset
of the PakCtrl protocol.

Settings are variables within the operating system of a datalogger that control
operation and can be changed by the user. An applicati on usi ng DevC o n fi g
transactions can obtain the values for these settings and change these settings if
necessary.

2-6

Section 2. Protocols and Packet Types

As datalogger operating systems are revised, these settings may change or be
removed. However, the datalogger will always report the major version
number within the setting response message so that an application can be aware
of the current operating system in the datalogger. By knowing the data type
and version number, an application can verify the most current settings for a
datalogger with the CR1000 Device Description File located in the Appendix
of this document. Specific setting IDs can be gleaned from the Device
Description file and used during the creation of an application that
communicates with a CR1000 type datalogger.

2.2.6.1 DevConfig Get Settings Message (MsgType 0x0f & 0x8f)

The Get Settings transaction allows an application to receive all or part of the
datalogger settings. The application sends a command and waits for the
response from the datalogger. If the datalogger has more settings to send than
can fit in a single response message, the MoreSettings parameter is set in the
response. The application must issue another Get Settings message and specify
the BeginSettingId to get the remaining datalogger settings.

DevConfig Get Settings Command (MsgType 0x0f):

Name Type Description

MsgType Byte Message type code (0x0f)
TranNbr Byte Transaction number
SecurityCode UInt2 The security code of the datalogger
{ BeginSettingId UInt2 Allows the application to specify the first

setting for the datalogger to include in the
response message.

{ EndSettingId }} UInt2 Allows the application to specify the last

setting the datalogger should include in the
response message.

DevConfig Get Settings Response (MsgType 0x8f):

Name Type Description

MsgType Byte Message type code (0x8f)
TranNbr Byte Transaction number
Outcome Byte Specifies the outcome of the transaction:

0x01: The transaction succeeded and values
will follow
0x02: The security code is invalid

{ DeviceType UInt2 Specifies a code that identifies the type of

device that is sending the response:
0x0c: CR1000 type datalogger

MajorVersion Byte Identifies the version number for the device.

The application can use a combination of the
DeviceType and MajorVerion to identify the
settings that should be supported by the device
through the Device Description XML file.

MinorVersion Byte Identifies the version number to determine how

settings for a device are to be interpreted. For
example, a device might support a different
baud rate in one version than in another
version.

2-7

Section 2. Protocols and Packet Types

Name Type Description

MoreSettings Boolean Set to true by the datalogger when it has more

{ SettingId UInt2 Identifies the specific setting being described
LargeValue bit 15 Set to 1 if the setting value is larger than will

ReadOnly bit 14 Set to 1 if this setting is read only
SettingLen bit 13..0 Specifies the length in bytes of the setting that

SettingValue }} Byte [1..988] The value of the setting. The Binary format of

settings to send than are in this response
message

fit into the 988 byte packet size limit for a
DevConfig protocol packet

will follow. If LargeValue is set to true, the
value that follows will be the first fragment of
the message and subsequent fragments must be
retrieved using the DevConfig Get Setting
Fragment transaction.

this field depends on the setting type declared
in the Setting Id parameter.

2.2.6.2 DevConfig Set Settings Message (MsgType 0x10 & 0x90)

The Set Settings transaction allows an application to change the value of one or
more settings in the datalogger. The application sends the command message
and waits for the datalogger’s response message. The datalogger will not
activate the new setting until the client sends a Control message to commit the
setting. The datalogger will timeout after forty seconds and resume normal
operations based on previous settings if it has not received an additional Set
Settings command or a commit message.

DevConfig Set Settings Command (MsgType 0x10):

Name Type Description

MsgType Byte Message type code (0x10)
TranNbr Byte Transaction number
SecurityCode UInt2 The security code of the datalogger
{ SettingId UInt2 The identity of the setting that follows
SettingLen UInt2 The length in bytes of the SettingValue
SettingValue } Byte [ ] The value for the setting

DevConfig Set Settings Response (MsgType 0x90):

Name Type Description

MsgType Byte Message type code (0x90)
TranNbr Byte Transaction number
Outcome Byte The outco me of the transaction:

0x01: The transaction succeeded
0x02: The security code is invalid or does not
provide sufficient access to set settings
0x03: Another client has already made changes
that have not been committed

{ SettingId UInt2 The setting identifier from the Set Settings

command

2-8

Section 2. Protocols and Packet Types

Name Type Description

SettingsOutcome } Byte Specifies the outcome of the set attempt:

0x01: Setting value tagged to be changed
0x02: Setting identifier was not recognized
0x03: Setting value malformed or out of range
0x04: Setting is read-only
0x05: Not enough memory to store the setting

2.2.6.3 DevConfig Get Setting Fragment Transaction Message (MsgType
0x11 & 0x91)

The Get Setting Fragment transaction allows an application to ask for part of a
setting value. This transaction is used if the setting value is too large for a
single packet. Typically, an application will use the Get Settings transaction to
retrieve a setting. However, if the LargeValue flag is set, the application can
get the rest of the setting value using this transaction.

DevConfig Get Setting Fragment Command (MsgType 0x11):

Name Type Description

MsgType Byte Message type code (0x11)
TranNbr Byte Transaction number
SecurityCode UInt2 The security code of the datalogger
SettingId UInt2 The identifier of the setting value that should

be returned

Offset Uint4 The offset from the start of the setting value

where the requested fragment should start

DevConfig Get Setting Fragment Response (MsgType 0x91):

Name Type Description

MsgType Byte Message type code (0x91)
TranNbr Byte Transaction number
Outcome Byte The outco me of the transaction:

0x01: The transaction succeeded and the values
will follow
0x02: The security code is invalid or does not
provide sufficient access to read the setting
0x03: The transaction is not supported by this
device

{ MoreFragments bit 15 If set to true, there are more fragments that can

be sent for this setting
FragmentSize bits 14..0 The size of this fragment in bytes
FragmentData } Byte [ ] The fragment of the setting

2.2.6.4 DevConfig Set Setting Fragment Transaction Message (MsgType
0x12 & 0x92)

The Set Setting Fragment Transaction is used to send settings to the datalogger
that are too large to fit in a single packet.

2-9

Section 2. Protocols and Packet Types

DevConfig Set Setting Fragment Command (MsgType 0x12):

Name Type Description

MsgType Byte Message type code (0x12)
TranNbr Byte Transaction number
SecurityCode UInt2 The security code of the datalogger
SettingId UInt2 The identifier of the setting value that should

FragmentOffset UInt4 Th e starting offset for this fragment
MoreFragments bit 15 If set to true, the application has more

FragmentLen bits 14..0 The length in bytes of the setting value to

FragmentData Byte [ ] The setting fragment data

DevConfig Set Setting Fragment Response (MsgType 0x92):

Name Type Description

MsgType Byte Message type code (0x92)
TranNbr Byte Transaction number
Outcome Byte The outco me of the transaction:

be returned

fragments to send for this setting

follow

0x01: The setting value was tagged for change
or the fragment was accepted
0x02: The security code is invalid or does not
provide sufficient access to set settings
0x03: The setting identifier was not recognized
0x04: The setting value was malformed or out
of range
0x05: The setting is considered read-only
0x06: Not enough memory to store the setting
0x07: This device does not support this
transaction

2-10

2.2.6.5 DevConfig Control Transaction Message (MsgType 0x13 & 0x93)

The Devconfig Control transaction cont rol s what t he dat al o gger does with the
settings it has in memory. The application uses this transaction to tell the
datalogger to commit changes to permanent storage, cancel any changes, revert
all settings to the device defaults, or refresh the session timer.

The datalogger has a forty-second session timer that gets set or reset each time
a valid message is received from the client. When this timer expires, the
datalogger will rollback any changes that have not been committed.

DevConfig Control Command (MsgType 0x13):

Name Type Description

MsgType Byte Message type code (0x13)
TranNbr Byte Transaction number
SecurityCode UInt2 The security code of the datalogger

Section 2. Protocols and Packet Types

Name Type Description

Action Byte The action that should be taken by the

datalogger
0x01: Commit the changes and exit
0x02: Cancel any changes and exit back to a
mode where a new session can be started
0x03: Revert all settings to factory defaults.
Note that these settings will not take effect
until they are committed with another instance
of this transaction
0x04: Don’t do anything with the setting at
present but refresh the session timer
0x05: Cancel any changes and reboot the
datalogger

DevConfig Control Response (MsgType 0x93):

Name Type Description

MsgType Byte Message type code (0x93)
TranNbr Byte Transaction number
Outcome Byte The outco me of the transaction:

0x01: The settings will be committed and the
device rebooted
0x02: The security code is invalid or does not
provide sufficient access to set settings
0x 03: There are no changes to commit and the
session is ending
0x04: The changed settings will be discarded
and the device will be rebooted
0x05: The settings have reverted to device
defaults but must be committed to take effect
0x06: The session timer has been reset
0x07: The specified action cannot be carried
out because another client has already made
changes to the settings for this device

2.3 BMP5 Application Packets

BMP5 application packets are framed with a PakBus SerSyncByte, 0xbd, and
use the standard eight-byte PakBus header that was used in the PakCtrl
messages. The only difference in the header is the value of the HiProtoCode
parameter. PakCtrl messages have a HiProtoCode parameter of zero while the
header for a BMP5 message has a HiProtoCode parameter of one.

The following are the BMP5 packet types that are necessary for
communication. Keep in mind the general structure of a complete PakBus
packet since the following BMP5 packet type descriptions will only contain
information regarding the message type, transaction number and body of the
packet.

2-11

Section 2. Protocols and Packet Types

2.3.1 Please Wait Message (MsgType 0xa1)

If the datalogger anticipates it will take more than the default one second to
produce a response after receiving a command, a Please Wait message will be
sent to the client indicating the amount of time the client should wait for a
response to that command. The transaction number of the Please Wait
message will be the same as the command packet on which it is waiting.

After the Please Wait message has been sent, the datalogger will send the
normal transaction response as soon as it is ready. If the datalogger determines
that the response will still take longer than the wait time it just sent, the
datalogger will send another Please Wait message to the application before the
current wait time expires.

Please Wait Message Body (MsgType 0xa1):

Name Type Description

MsgType Byte Message type code (0xa1)
TranNbr Byte Transaction number
CmdMsgType Byte MsgType of the command on which we are

WaitSec UInt2 Number of seconds to wait for a response (30

waiting

second limit).

2.3.2 Clock Transaction (0x17 & 0x97)

The clock transaction can be used to check the current time or to adjust the
datalogger clock. Note the inherent danger of retrying a clock set command. If
the client were to simply retry a failed clock set attempt without knowing
whether the first try reached the station, there is a danger the clock will be
changed more than wanted. If a clock set attempt fails, the client should read
the clock again to determine whether additional adjustments are needed.

Clock Command Body (MsgType 0x17):

Name Type Description

MsgType Byte Message type code (0x17)
TranNbr Byte Transaction number
SecurityCode UInt2 Security code for the datalogger
Adjustment Nsec Quantity of time to add to the clock. If the

datalogger clock is ahead of the current time,
the Adjustment field should be negative.

2-12

Section 2. Protocols and Packet Types

Clock Response Body (MsgType 0x97):

Name Type Description

MsgType Byte Message type code (0x97)
TranNbr Byte Transaction number
RespCode Byte Response code:

0x00: Complete
0x01: Permission denied

{ OldTime } Nsec Difference between the datalogger clock and

January 1, 1990. This field is not returned
unless RespCode is zero.

2.3.3 File Transfer and Control Transactions

File transfer and control transactions are used to list datalogger directories,
download datalogger programs, upload datalogger programs, obtain table
definitions, and administer data files. These functions are accomplished by
downloading files to or uploading files from the datalogger and by executing
file control operations on those files. The specific message types are:

2.3.3.1 File Download Transaction (MsgType 0x1c & 0x9c)

This transaction moves a file from the client application to the datalogger. If
the file is larger than the allowed message size, the client application should
separate the file into fragments, which is called a multiple exchange
transaction. The transaction number must be the same for all file message
fragments since the datalogger uses this number to keep track of entire file
during the transaction. The CloseFlag field listed in the description below is
used to mark the end of the multiple exchange transaction.

The CR200 datalogger has limited memory resources and can not receive a
standard 1000 byte PakBus message. The CR200 dataloggers advertise the
maximum packet size in a device setting called “MaxPktSize” that can be
obtained with the PakCtrl Get Settings transaction. This setting must be used
to adjust the size of the File Download Command message. If a device does
not specify the MaxPktSize setting, the standard 1000-byte PakBus message
size is the limit.

File Download Command Body (MsgType 0xlc):

Name Type Description

MsgType Byte Message type code (0x1c)
TranNbr Byte Transaction number
SecurityCode UInt2 Security code of the datalogger
FileName ASCIIZ [0..64] The file name and the device where the file

will be stored. This field may be null after the
first exchange of a multiple fragment
transaction.

Attribute Byte A reserved byte that the application must

currently designate as 0x00.

CloseFlag Byte 0x00: Keep the file open for more exchanges

0x01: This is the final or only exchange of this
transaction.

2-13

Section 2. Protocols and Packet Types

Name Type Description

FileOffset UInt4 Describes the byte offset into the file of this

{ FileData } Byte [ ] The data being sent in this packet

File Download Response Body (MsgType 0x9c):

Name Type Description

MsgType Byte Message type code (0x9c)
TranNbr Byte Transaction number
RespCode Byte Response Code:

FileOffset UInt4 The FileOffset number from the command

fragment. This field will be zero if this is a
single exchange transaction.

0x00: Complete
0x01: Permission denied
0x02: Insufficient resources or memory full
0x09: Invalid fragment number
0x0d: Invalid file name
0x0e: File is not currently accessible

packet to which this is responding

2.3.3.2 File Upload Transaction (MsgType 0x1d & 0x9d)

This transaction moves a file from the datalogger to the client application. The
CloseFlag field, listed in the description below, closes the file and indicates the
End of File. If an attempt to read past the End of File occurs, the datalogger
provides a final response indicating FileData empty and automatically closes
the file without requiring any additional exchanges.

File Upload Command Body (MsgType 0x1d):

Name Type Description

MsgType Byte Message type code (0x1d)
TranNbr Byte Transaction number
SecurityCode UInt2 Security code for the datalogger
FileName ASCIIZ [0..64] The name of the file to be retrieved
CloseFlag Byte 0x00: Keep the file open for more exchanges

on this transaction
0x01: This transaction is the final exchange of

the transaction
FileOffset UInt4 Byte offset into the file of the fragment
Swath UInt2 The number of bytes to read

File Upload Response Body (MsgType 0x9d):

Name Type Description

MsgType Byte Message type code (0x9d)
TranNbr Byte Transaction number

2-14

Name Type Description

RespCode Byte Response Code:

FileOffset UInt4 Byte offset into the file of this fragment
{ FileData } Byte [ ] The file data beginning at FileOffset. If an

2.3.3.3 File Directory Format

Old programs and other files can be stored in the memory of the CR1000 type
datalogger. To obtain a list of the files maintained in a CR1000 type
datalogger, use the File Upload transaction and specify a file named “.DIR”. A
directory listing of the files being stored on the datalogger will be returned.
The file received in the response message has the following format:

Section 2. Protocols and Packet Types

0x00 – Complete
0x01 – Permission denied
0x0d – Invalid file name
0x0e – File is not currently accessible

attempt was made to read past the end of the
file, then this field will be empty or smaller
than size requested in the Swath parameter of
the command message.

Directory File Format:

Name Type Description

DirVersion Byte File format version
{ FileName ASCIIZ [1..64] File name
FileSize UInt4 File size in bytes
LastUpdate ASCIIZ Date of the last file update
{ Attribute } Byte [0..12] File attribute code. This field may repeat up to

12 times to specify a list of file attributes.
0x01: Running now
0x02: Run on power-up
0x03: Read only
0x04: Hidden
0x05: Program execution paused

0x00 } Byte File attribute list terminator

2.3.3.4 File Control Transaction (MsgType 0x1e & 0x9e)

The File Control transaction controls compilation and execution of the
datalogger program and manages the files on the datalogger

File Control Command Body (MsgType 0x1e):

Name Type Description

MsgType Byte Message type code (0x1e)
TranNbr Byte Transaction number
SecurityCode UInt2 Security code of the datalogger
FileName ASCIIZ [1..64] File name and device where the file exists. For

example, “CPU:CR1000Program.CR1”.

2-15

Section 2. Protocols and Packet Types

Name Type Description

FileCmd Byte Code that specifies the command to perform

with the file:

0x01: Compile and run the program and also

make it the “run on power-up” file

0x02: Set the “run on power-up” attribute.

When used with an empty file name argument,

the “run on power-up” attribute will be cleared.

0x03: Make this file hidden

0x04: Delete this file

0x05: Format the device

0x06: Compile and run the file without

deleting the data tables

0x07: Stop the running program

0x08: Stop the running program and delete the

associated files

0x09: Make this file the new datalogger OS

0x0a: Compile and run the program without

changing the “run on power-up” attribute

0x0b: Pause running program execution

0x0c: Resume running program execution

0x0d: Stop the currently running program,

delete associated data files, run the specified

file, and set it to “run on power-up”.

0x0e: Stop the currently running program,

delete associated files, run the specified file,

but don’t change the “run on power-up” setting

File Control Response Body (MsgType 0x9e):

Name Type Description

MsgType Byte Message type code (0x9e)
TranNbr Byte Transaction number
RespCode Byte 0x00 – Complete

0x01 – Permission denied

0x0d – Invalid file name

0x13 – Unsupported FileCm d code
HoldOff UInt2 Number of seconds the client should wait

before attempting the next transaction.

The steps of a complete File Control transaction are shown in this explanation
of a CR200 series datalogger program download:

1. Use a File Control command to stop the running program and delete

associated files to make room for the new program

2. Use File Download to send the new program to the datalogger

3. Use a File Control command to compile and run the new program

4. Use Get Programming Statistics to obtain the compile results

2-16

Section 2. Protocols and Packet Types

2.3.3.5 Get Programming Statistics Transaction (MsgType 0x18 & 0x98)

The Get Programming Statistics transaction retrieves available status
information from the datalogger.

Get Programming Statistics Command Body (MsgType 0x18):

Name Type Description

MsgType Byte Message type code (0x18)
TranNbr Byte Transaction number
Security Code UInt2 Security code of the datalogger

Get Programming Statistics Response Body (MsgType 0x98):

Name Type Description

MsgType Byte Message type code (0x98)
TranNbr Byte Transaction number
RespCode Byte Response Code:

0x00: Complete

0x01: Permission denied
{ OSVer ASCIIZ Datalogger operating system version
OSSig UInt2 Datalogger operating system signature
SerialNbr ASCIIZ Datalogger serial number
PowUpProg ASCIIZ Name of the “run on power-up” program
CompState Byte Compile and execution status:

0x00: No datalogger program

0x01: Datalogger program running

0x02: Program cannot compile

0x03: Program is paused
ProgName ASCIIZ [1..64] Datalogger program name
ProgSig UInt2 Datalogger program signature
CompTime NSec Time when program was compiled relative to

January 1, 1990.
CompResult } ASCIIZ [0..250] Compilation result text that exist as one or

more carriage return and line feed separated

lines of ASCII characters with null termination

after the last line

2.3.4 Data Collection and Table Control Transactions

2.3.4.1 Table Definitions

Since dataloggers store data in tables, the datalogger and the application must
understand and agree on the structure of each table in order to collect data.
Table definitions contain the parameters that describe each table, record, and
field in the datalogger and are contained in a file on the datalogger with a
“.TDF” file extension.

Table definitions are used by the application to know what ta bl es and fiel d s
exist and what data to expect from each table when collecting values from the
datalogger. The table definitions specifically describe the data tables, records,
and fields that have been established by the program in the datalogger. These
table definitions are necessary to calculate the table signature for the Collect

2-17

Section 2. Protocols and Packet Types

Data transaction and to describe what data should be returned when collecting
data from a datalogger.

2.3.4.2 Getting Table Definitions and Table Signatures

Table definitions are obtained using a File Upload transaction and are
contained in a file with a “.TDF” file extension. The application only needs to
specify the name “.TDF” and the datalogger will recognize this file extension
in the command message and return the appropriate response containing the
table definitions. The format of the “.TDF” file is shown in the following
table:

Table Definitions File Format:

Name Type Description

FslVersion Byte File format version. (Use 0x01)
{ TableName ASCIIZ Table Name
Table Size UInt4 Number of records allocated in the datalogger

TimeType Byte Data type code of the “Time Tag” field
TblTimeInto NSec “Time Into” part of the “Time Into Interval”

TblInterval NSec “Interval” part of the table interval (zero means

{ ReadOnly bit 7 0: Read/Write

FieldType bits 6..0 Data type of the field
FieldName ASCIIZ Name of the field in the table
{ AliasName } ASCIIZ Alias or “FieldName” assigned to the elements

(0) Byte Alias names list terminator
Processing ASCIIZ Generated by the datalogger, this string

Units ASCIIZ Field units
Description ASCIIZ [0..80] Description of the field
BegIdx UInt4 Beginning index. The array index number for

Dimension UInt4 Array dimension of the whole array (set to 1 if

{ SubDim } UInt4 Sub-dimension of a multidimensional array
(0) } UInt4 Sub-dimension list terminator
(0) } Byte Field list terminator

for this table

for the table interval

an event driven table)

1: Read-only

within this field. Currently not used.

designates the type of processing and
processing parameters used to generate this
field (i.e. “Max”, “Min”, “Avg”, “Tot”, etc.).

the first element of the array (1 by default or if
not an array).

not an array)

2-18

There are three implied parameters that are part of the table definitions: Table
Numbers, Field Numbers, and the Table Definition Signature. Table Number
one is the first table. Field Number one is the first field that follows the Time
Tag. Table and Field Numbers are important because they are often used to
specify the location of data in the datalogger in other commands.