Baracoda IDBlue Supplementary Manual

Data Capture

for Workforce

in Motion

IDBlue

Communication Protocol

©Baracoda

TM

– December 2008

IDBlue – Communication Protocol v2.4.1 - 2 -

Data Capture

for Workforce

in Motion

SUMMARY

SUMMARY ................................................................... 2

REVISION HISTORY .......................................................... 4

DOCUMENT CONVENTIONS ...................................................... 6

COMMUNICATION OVERVIEW .................................................... 7

B

LUETOOTH

C

ODE

.......................................................... 7

S

ERIAL

I

NFORMATION

........................................................... 7

P

ACKET

S

TRUCTURE

............................................................. 8

A

SYNCHRONOUS

E

VENTS

.......................................................... 8

D

EVELOPER

T

IPS

.............................................................. 9

DEVICE OPERATING MODES ................................................... 10

D

ISCONNECTED

M

ODE

........................................................... 10

T

AG

V

ERIFY

......................................................... 10

S

TORE

T

IMESTAMP

+

T

AG

I

D

+

B

LOCK

0

D

ATA

................................ 10

C

ATHEXIS

WEB ........................................................ 10

C

ONNECTED

M

ODE

............................................................. 11

N

ORMAL

............................................................. 11

R

EACTIVE

........................................................... 11

R

EAD

B

LOCK

N ....................................................... 11

W

RITE

B

LOCK

N ....................................................... 11

R

EAD

B

LOCKS

........................................................ 11

DEVICE CONFIGURATION ..................................................... 12

C

ONTINUOUS

S

CANNING

F

LAG

..................................................... 12

C

ONNECTED

M

ODE

P

ARAMETERS

.................................................... 13

COMMANDS ................................................................. 14

R

ESPONSES

................................................................. 16

C

ORE

F

UNCTIONS

............................................................. 17

C

ONFIGURATION

F

UNCTIONS

...................................................... 20

B

LUETOOTH

F

UNCTIONS

......................................................... 23

I

NTERNAL

D

ATABASE

F

UNCTIONS

................................................... 26

RFID COMMANDS ............................................................ 28

DEPRECATED FUNCTIONS ..................................................... 33

APPENDIX A – PROPERTIES .................................................. 42

APPENDIX B - PROTOCOLS ................................................... 45

APPENDIX C - CHECKSUM GENERATION ......................................... 46

IDBlue – Communication Protocol v2.4.1 - 3 -

Data Capture

for Workforce

in Motion

GLOSSARY ................................................................. 47

IDBlue – Communication Protocol v2.4.1 - 4 -

Data Capture

for Workforce

in Motion

Revision History

Changes to the original manual are listed below.

Document Date Description

2.4.0 10 July 06 Initial release

2.4.1 31 Dec. 08 Upgrade Graphic Presentation

IDBlue – Communication Protocol v2.4.1 - 5 -

Data Capture

for Workforce

in Motion

Introduction

Overview

The intent of this document is to provide software developers with a general specification for

interfacing with the IDBlue™ device. It provides a description of the byte-level protocol used to

communicate with an IDBlue™ device, and enables end-users to develop their own drivers and

applications for any platform supporting a Bluetooth serial port profile (SPP).

Note: Cathexis recommends that our partners and customers use our supported drivers

whenever possible. This document is intended for the use of clients who wish to use

IDBlue™ on a platform for which Cathexis does not yet provide a software development kit

(SDK). For information on which platforms have supported SDK’s, please visit

www.cathexis.com.

This document details how to use all of the features of the IDBlue™ device, including configuration

and RFID operations.

Background

This document assumes that the reader has some experience in developing device drivers for

microelectronic devices. Also, a background in data communication protocols is helpful.

Knowledge of serial communications and Bluetooth® access using the requisite development

environment is highly recommended.

IDBlue – Communication Protocol v2.4.1 - 6 -

Data Capture

for Workforce

in Motion

Document Conventions

The following text conventions and symbols are used throughout this manual.

IDBlue – Communication Protocol v2.4.1 - 7 -

Data Capture

for Workforce

in Motion

Communication Overview

In order to communicate with IDBlue™, a Bluetooth® connection must be established to the device

using the serial port profile (SPP). It is beyond the scope of this document on how to establish this

connection, is it varies greatly between platforms.

When developing a driver library for IDBlue™ this connection is typically established either via a pre-

configured Bluetooth® serial port, or the Bluetooth® libraries provided by the platform and

programming language.

Bluetooth PIN Code

The default Bluetooth PIN code for all IDBlue devices is “0000” (i.e. four zeroes). This PIN code is

required to Bond or Pair with the device (this is a prerequisite of establishing a serial connection

through the SPP profile).

Serial Information

The serial port communication parameters are as follows:

Baud Rate 19,200 bps

Data Bits 8

Stop bits 1

Parity None

Flow Control None

These are the default communication settings for IDBlue™ and cannot be changed. A connection to

an IDBlue™ device must be initiated from the host because the IDBlue device operates in “Slave”

mode.

IDBlue – Communication Protocol v2.4.1 - 8 -

Data Capture

for Workforce

in Motion

Packet Structure

Packets are a sequence of bytes sent to the IDBlue device via a serial port connection.

The table below shows the formatting for all request and response packets used to communicate

with the IDBlue™ device.

Note: the data length does not include the checksum.

* Please see Appendix C - Checksum Generation for information on how to calculate

the packet checksum.

Asynchronous Events

When the user presses the button on the device an asynchronous event is created, sending a packet

to the computer. To designate this packet as an asynchronous event, and not a possible response to

an earlier command issued over the serial connection, a special packet (ASYNCH) is sent before the

main packet to indicate that it is a asynchronous event. This has the form:

Response format (Asynchronous Header)

This is true for all modes of operation during a button press, excluding reactive mode.

Applications (and driver libraries) should interpret the response packet immediately following an

ASYNCH (asynchronous header) packet as an asynchronous event.

In reactive mode, only a button press response (as seen below) is sent.

Response format (Button Pressed)

IDBlue – Communication Protocol v2.4.1 - 9 -

Data Capture

for Workforce

in Motion

Developer Tips

• Tag IDs are sent and received in LSB order, but need to be displayed as MSB order. The byte

array containing the tag ID should be reversed when either sending a command to the

device, or receiving a response from the device.

• The data length value does not include the checksum, only the payload.

IDBlue – Communication Protocol v2.4.1 - 10 -

Data Capture

for Workforce

in Motion

Device Operating Modes

The IDBlue™ device has a number of operating modes, each performing different operations when

the hardware button the device is pressed. These modes are divided into Connected modes (when

the device has an active Bluetooth® connection to a PDA or other computing device) and

Disconnected (when the device does not have an active Bluetooth® connection).

Note: each of these operating modes is affected by the Continuous Scanning Flag – please refer to

the configuration section for details.

Disconnected Mode

The IDBlue™ device supports three disconnected modes, as listed below.

Tag Verify

Tag VerifyTag Verify

Tag Verify

In Tag Verify mode, when the hardware button is pressed, the device will:

• Indicate a start of RFID operations by turning the LED orange

• Attempt to scan a tag using the currently configured RFID protocol.

• If a tag is successfully scanned, the device will indicate with a green LED and audio beep (if

audio feedback is enabled).

Store Timestamp + Tag Id + Block 0 Data

Store Timestamp + Tag Id + Block 0 DataStore Timestamp + Tag Id + Block 0 Data

Store Timestamp + Tag Id + Block 0 Data

In Tag Store mode (aka Store Timestamp + Tag Id + Block 0 Data), when the hardware button is

pressed, the device will:

• Check for a valid timestamp value (note: this check can be disabled through the

TIMESTAMPREQUIRED property).

• If no valid timestamp is present (i.e. the device’s timestamp has not been set), the LED will

blink double-red.

• If a valid timestamp is present, the device will indicate a start of RFID operations by turning

the LED orange.

• Attempt to read block 0 from a tag using the currently configured RFID protocol.

• If a tag is successfully scanned, the device will indicate with a green LED and audio beep (if

audio feedback is enabled).

The current timestamp, tag ID, and contents of byte 0 (in block 0) on the tag will

then be stored in the internal tag database (see Tag Store for details). This data

can later be accessed through the GET_TAG command.

CathexisWEB

CathexisWEBCathexisWEB

CathexisWEB

This operating mode is reserved for use by Cathexis.

IDBlue – Communication Protocol v2.4.1 - 11 -

Data Capture

for Workforce

in Motion

Connected Mode

Normal

NormalNormal

Normal

In Normal mode, when the hardware button is pressed, the device will:

• Indicate a start of RFID operations by turning the LED orange

• Attempt to scan a tag using the currently configured RFID protocol.

• If a tag is successfully scanned, the device will indicate with a green LED and audio beep (if

audio feedback is enabled).

• An asynchronous GET_TAG_ID response packet will be sent to the connected device.

Reactive

ReactiveReactive

Reactive

In Reactive mode, when the hardware button is pressed, the device will:

• Send an asynchronous button pressed packet to the connected host.

Read Block N

Read Block NRead Block N

Read Block N

In Read Block N mode, when the hardware button is pressed, the device will:

• Indicate a start of RFID operations by turning the LED orange

• Attempt to read block N (where N is the current value of the BLOCKINDEX property) using

the currently configured RFID protocol.

• If a tag is successfully scanned, the device will indicate with a green LED and audio beep (if

audio feedback is enabled).

• An asynchronous READ_BLOCK response packet will be sent to the connected device.

Write Block N

Write Block NWrite Block N

Write Block N

In Write Block N mode, when the hardware button is pressed, the device will:

• Indicate a start of RFID operations by turning the LED orange

• Attempt to write block N (where N is the current value of the BLOCKINDEX property) using

the currently configured RFID protocol, using the Block data found in the BLOCKDATA

property.

• If a tag is successfully scanned, the device will indicate with a green LED and audio beep (if

audio feedback is enabled).

• An asynchronous WROTE_BLOCK response packet will be sent to the connected device.

Read Blocks

Read BlocksRead Blocks

Read Blocks

In Read Blocks mode, when the hardware button is pressed, the device will:

• Indicate a start of RFID operations by turning the LED orange

• Attempt to read block N+M (where N is the current value of the BLOCKINDEX property and

M is the number of blocks to read from the BLOCKCOUNT property) using the currently

configured RFID protocol.

• If a tag is successfully scanned, the device will indicate with a green LED and audio beep (if

audio feedback is enabled).

• An asynchronous READ_BLOCKS response packet will be sent to the connected device.

IDBlue – Communication Protocol v2.4.1 - 12 -

Data Capture

for Workforce

in Motion

Device Configuration

The IDBlue™ device supports a number of configuration properties. These properties are either

persistent properties (saved to the on-board EEPROM, and “remembered” when the device is shut

down), or session properties (active until the next device shutdown).

In firmware versions prior to 2.4, the IDBlue™ was configured through two sets of discrete

configuration commands; one for default/persistent properties, and one for session properties. That

configuration model has been replaced by these four commands, providing a streamlined and more

extensible method for device configuration:

• LOAD_DEFAULT_AS_SESSION. Overrides the current session properties of the device with

the saved persistent settings. This is the same operation performed by the IDBlue™ during

power-up.

• SAVE_SESSION_AS_DEFAULT. Writes the current session properties of the device to the

EEPROM, persisting these values between shutdowns.

• GET_PROPERTY. Retrieves the current value of a session property.

• SET_PROPERTY. Sets the current value of a session property.

These four commands allow for the configuration of every IDBlue™ parameter, except for the

Bluetooth® name and PIN code. Developer-focused information on certain ky properties is presented

below, with the full table of properties is listed in Appendix A – Properties.

Continuous Scanning Flag

One of the powerful new features introduced in the 2.4 firmware release is the continuous scanning

flag. This mode enables each of the connected and disconnected asynchronous operations (note:

except for the REACTIVE / Button Press mode) to “continuously” scan for tags without requiring the

user to repeatedly push the IDBlue™ hardware button.

This is ideal for scenarios involving bulk scanning, reading or writing of tags. To enable this feature

set the CONTINUOUSSCANNING property to true. With this flag active, a hardware button press will

enable the asynchronous mode; for example, in Normal (or Tag Scan) mode, the device will:

• Start scanning for tags when the hardware button is pressed

• Stop scanning for tags when the hardware button is pressed again

The continuous scan will time out after a certain period of time if no tags are found; this timeout

period is controlled by the CONTINUOUSSCANNINGTIMEOUT property.

In addition, in disconnected Tag Store mode, a duplicate tag filter may be enabled by configuring the

DUPLICATEELIMINATIONTIMEOUT property to a value greater than zero (0).

This filter will cause the not scan or store the same tag ID for a certain period of time.

Note: this filter only applies to the last tag scanned.

Also, in cases where the usage scenario does not require valid timestamps for tags stored in Tag

Store mode, the REQUIRETIMESTAMP property may be set to false. This will configure the IDBlue™

device not to check for a valid timestamp before storing a tag ID, invalid timestamp (all 0’s) and

contents of byte 0.

IDBlue – Communication Protocol v2.4.1 - 13 -

Data Capture

for Workforce

in Motion

Connected Mode Parameters

Four configuration properties affect the connected operating mode; these are the

CONNECTEDMODE, BLOCKINDEX, BLOCKCOUNT and BLOCKDATA. ConnectedMode sets the base

operating mode, with the data-centric modes (reading and writing) using the other properties.

When updating the ConnectedMode to a mode other than NORMAL, or REACTIVE, ensure that the

appropriate BLOCKINDEX, BLOCKCOUNT and/or BLOCKDATA properties are also updated.

IDBlue – Communication Protocol v2.4.1 - 14 -

Data Capture

for Workforce

in Motion

Commands

Communication between the IDBlue™ device and host occurs using a series of requests and

responses. Requests are packets sent to the IDBlue™ device from the host. They are used by the host

to ask for information or for the device to perform some task.

Responses are sent to the from the IDBlue™ device. They are the result sent back to the host after a

request has been issued (or after an asynchronous event has occurred).

Below is a table summarizing the valid requests and responses.

Note: All byte values are given in hexadecimal.

IDBlue – Communication Protocol v2.4.1 - 15 -

Data Capture

for Workforce

in Motion

IDBlue – Communication Protocol v2.4.1 - 16 -

Data Capture

for Workforce

in Motion

Responses

This section describes the stock responses which can be returned from the device.

Note: most commands have a custom response format, which is described in the command

definition.

ACK (F1h)

Description

Some requests use this packet to affirm that data was correctly received.

NACK (1Fh)

Description

This packet is sent to the host device when an error has occurred in processing the request packet or

if the request could not be carried out properly. It is also returned when a malformed or invalid

request is sent (e.g. invalid checksum in request).

ASYNCH (70h)

Description

This packet is used to notify the host that asynchronous data will follow. The type of asynchronous

response sent depends on the current connected operating mode of the device.

BUTTON_PRESS (FFh)

Description

This packet is used to notify the host that the user has pushed the button on the device.

This packet will only be sent when the device is in reactive mode.

IDBlue – Communication Protocol v2.4.1 - 17 -

Data Capture

for Workforce

in Motion

Core Functions

NO_OP (00h)

Description

This request does nothing. It may be used to verify that an IDBlue™ device is connected. It returns an

ACK packet as response.

Parameters

None.

GET_STATUS (23h)

Description

This request returns status information about the device including battery level, firmware version,

and hardware.

Parameters

Battery level

The battery life remaining for the device, represented as a percentage (0 – 100%)

Firmware / Hardware Version

This is a 4 byte representation of the hardware and firmware version residing on the

device:

Byte 0 = hardware version

Byte 1 = Major version

Byte 2 = Minor version (MSB)

Byte 3 = Major version (LSB)

IDBlue – Communication Protocol v2.4.1 - 18 -

Data Capture

for Workforce

in Motion

REQ_START (80h)

Description

This request signals the start of one or more reactive mode requests. The host should send this

packet when it receives a button press event from the IDBlue™ device, and then proceeds to stream

other requests to the device.

Parameters

Result

1 on success, 0 if the request failed.

Returns

REQ_START response packet or NACK.

Note: the device will automatically display feedback (i.e. LED goes to orange) if it is operating in “Reactive” mode.

REQ_DONE (88h)

Description

This packet signals the end of one or more reactive mode requests. The host sends this packet when

it has finished streaming commands to the IDBlue™ device (see REQ_START).

This request should only be issued if a REQ_START request has already been sent to the device, or if

the device is in “Reactive” operating mode (see SET_DEFAULT_CONFIG).

When the device receives this request, it provides user feedback based on the status value.

Parameters

Status

The host uses this field to tell the IDBlue™ device if the stream of commands it sent was successful,

or unsuccessful. A value of 1 indicates success, 0 indicates failure. The host application should decide

if the series of requests was successful or not.

The LED on the device will glow green on success and red on failure, for 500 ms. If the audio buzzer is

enabled, the device will also beep on success.

Result

1 on success, 0 if the request failed.

Returns

REQ_DONE response packet or NACK.

IDBlue – Communication Protocol v2.4.1 - 19 -

Data Capture

for Workforce

in Motion

POWER_DOWN (91h)

Description

This requests the device to turn off. It offers a method to shut down the IDBlue™ device from a

software application.

Parameters

Result

1 on success, 0 if the request failed.

Returns

NACK if device could not be turned off.

BEEP (03h)

Description

Causes the device to emit one of the standard audio tones, or beeps. Note: if audio feedback is

disabled (through the BUZZERENABLED property) the command will succeed, but no audio tone will

be emitted. This is designed to provide additional user feedback in a custom application.

Result

1 on success, 0 if the request failed.

Returns

NACK if invalid type specified.

IDBlue – Communication Protocol v2.4.1 - 20 -

Data Capture

for Workforce

in Motion

Configuration Functions

SAVE_SESSION_AS_DEFAULT (10h) [New]

Description

Saves the session configured properties as the default configuration, which is written to EEPROM and

loaded on device activation. The session properties are configured using the SET_PROPERTY

command.

Parameters

Result

1 if successful, 0 otherwise.

Returns

SAVE_SESSION_AS_DEFAULT response packet, or NACK if an error occurred.

LOAD_DEFAULT_AS_SESSION (11h) [New]

Description

Loads the default configuration from EEPROM. This overwrites any session settings.

Parameters

Result

1 if successful, 0 otherwise.

Returns

LOAD_DEFAULT_AS_SESSION response packet, or NACK if an error occurred.

Page is loading ...

Baracoda IDBlue Supplementary Manual

Baracoda IDBlue Supplementary Manual

Related papers

Other documents