Interface Protocol

The UART interface of Tibbit #43-1 operates in one of two communications modes:

  • Command mode (default), which allows the host system to configure the Tibbit, and also perform single ("spot") analog-to-digital conversions.
  • Data streaming mode, in which the Tibbit continuously outputs ADC measurements for the enabled channels at the specified sampling rate and in the selected format.

In the command mode, the host system communicates with the Tibbit using a command-and-reply protocol. All commands and replies have the following format:

STX

Command or Reply

CR

The STX (ASCII code 0x02) and CR (ASCII code 0x0D) characters provide the command or reply packet encapsulation. Everything before STX and after CR is ignored. Incomplete (an STX without CR) commands and replies are ignored.

The Tibbit will send a reply for each correctly encapsulated command issued by the host, except the D command.

The material that follows does not show the encapsulating <STX> and <CR> characters, but their presence is always implied.

Available commands

Table 3 — Available Commands

Command

Description

Commands for switching the communications mode

C

Switches the Tibbit into the command mode.

D

Switches the Tibbit into the data streaming mode. No reply is provided for this command.

User-level commands for configuring the analog-to-digital conversion and streaming. These commands apply to the RAM (current) settings.

SM

Sets the sampling mode (single-ended or differential). Applies to single reads using the RA and RH commands, as well as the data streaming mode.

SD

Specifies the data output format. Applies only to the data streaming mode.

SR

Specifies the sampling rate. Applies only to the data streaming mode.

SC

Enables the specified channels for sampling. Applies only to the data streaming mode.

Calibration commands (the calibration is performed at the factory — do not manipulate these parameters unless you know what you are doing). These commands apply to the RAM (current) settings.

SA

Sets the values of the A parameters. Applies to single reads using the RA and RH commands, as well as the data streaming mode.

SBP

Sets the values of the BP parameters. Applies to single reads using the RA and RH commands, as well as the data streaming mode.

SBN

Sets the values of the BN parameters. Applies to single reads using the RA and RH commands, as well as the data streaming mode.

RAM read-back and EEPROM-related commands

GC

Returns the current values of the RAM (current) settings.

GE

Returns the values of the EEPROM (post-reset) settings. Executing this command does not alter the values of the RAM (current) settings.

SE

Copies the RAM (current) settings into the EEPROM (post-reset) settings.

FE

Copies the EEPROM (post-reset) settings into the RAM (current) settings.

SF

Restores all settings to their factory defaults (including the factory-programmed calibration values). This command overwrites the RAM (current) settings and the EEPROM (post-reset) settings.

Miscellaneous commands

RA

Obtains a single read on the specified channel(s) while staying in the command mode. The data is returned in the ASCII format.

RH

Obtains a single read on the specified channel(s) while staying in the command mode. The data is returned in the hexadecimal format.

V

Returns the version of the PIC microcontroller's firmware.

Table 4 — Standard Replies

Reply

Description

A

Command accepted. If the reply carries any data, this data will follow the A reply code.

C

Syntax error. No additional data ever follows this reply code.

O

Parameter out of range. No additional data ever follows this reply code.

F

Execution failed. This can only be related to the EEPROM operations. No additional data ever follows this reply code.

Commands for switching the communications mode

Command

C

Description

Instructs the Tibbit to exit the data streaming mode and enter the command mode. If the device was in the data streaming mode, it will stop sending the data stream and start accepting commands from the host. This is the only command that is recognized while the Tibbit is in the data streaming mode; all other commands are ignored.

Note: After the power-up (reset), the Tibbit is in the command mode.

Syntax

Command: C
Reply: A


Command

D

Description

Instructs the Tibbit to exit the command mode and enter the data streaming mode. This is the only command to which the Tibbit does not offer any reply. Instead, the data streaming commences immediately upon the receipt of this command.

Note: After the power-up (reset), the Tibbit is in the command mode.

Syntax

Command: D
Reply: (the Tibbit will start streaming the data directly)

User-level commands for configuring the ADC conversion and streaming

Command

SM

Description

Sets the sampling mode. Applies to single reads using the RA and RH commands, as well as the data streaming mode. This setting is stored in the RAM and applies immediately.

Syntax

Command: SMp, where p is the sampling mode: 0 — single-ended (four channels available), 1 — differential (two channels available)
Reply: A

Default value

0

Example

SM1 (selects the differential mode)


Command

SD

Description

Specifies the data output format. Applies only to the data streaming mode. This setting is stored in the RAM and applies immediately.

Syntax

Command: SDp, where p is the data output format: 0 — ASCII, 1 — binary, 2 — hexadecimal
Reply: A

Default value

0

Example

SD2 (selects the hexadecimal data mode)


Command

SR

Description

Specifies the sampling rate. Applies only to the data streaming mode. This setting is stored in the RAM and applies immediately.

Syntax

Command: SRp, where p is the sampling rate expressed as the number of sampling groups per second, in the 1 to 1000 range
Reply: A

Note: Since a sampling group includes the analog-to-digital conversion results for each enabled channel, each such group may include up to four values. 1000 samples/second is a permissible rate when the binary output format is enabled (see the SD command) and only one ADC channel is active. Refer to Specifications for the maximum recommended sampling rates depending on the data output format and the number of channels used.

Default value

1

Example

SR200 (200 sampling groups per second — a comfortable sampling rate for any data output format and any number of active channels)


Command

SC

Description

Enables the specified channels for sampling. Applies only to the data streaming mode. This setting is stored in the RAM and applies immediately.

Syntax

Command: SCp, where p is a comma-delimited list of active channels, from 1 to 4
Reply: A

Note 1: Only CH1 and CH2 are available in the differential mode (see the SM command). If CH3 and CH4 are specified while in the differential mode, the command will be rejected with the O status code.

Note 2: The channels are sampled in the order in which they are listed in this command. This affects not only the timing of the ADC sampling, but also the order in which the channel data will be sent in the data streaming mode.

Default value

1,2,3,4

Example

SC4,2 (enable CH2 and CH2; the channels will be sampled in the 4-2 order)

Calibration commands

All calibration parameters are set at the factory — do not change unless you know what you are doing!

These commands allow you to calibrate the ADC's linearity and offset. While these commands are normally only used during the production of the Tibbit, they remain available, and you can use them to recalibrate the device.

The A, BP, and BN parameters are used to calibrate individual channels. In the table below:

  • Vo is the compensated output of an ADC channel
  • Vi is the averaged raw output of an ADC channel

Table 5 — Calibration Formulas

Single-ended mode, positive input voltages

Vo = 0.0078125 × A × Vi + 0.00244140625 × BP

Single-ended mode, negative input voltages

Vo = 0.0078125 × A × Vi + 0.00244140625 × BN

Differential mode, positive input voltages

Vo = 0.0078125 × A × Vi + 2 × 0.00244140625 × BP

Differential mode, negative input voltages

Vo = 0.0078125 × A × Vi + 2 × 0.00244140625 × BN


Command

SA

Description

Sets the values of the A parameters. Applies to single reads using the RA and RH commands, as well as the data streaming mode. This setting is stored in the RAM and applies immediately.

Syntax

Command: SAp, where p is a comma-delimited list of six values — four for single-ended channels 1~4 and two for differential channels 1 and 2
Reply: A

Default values

Preset at the factory during the calibration process

Example

Command: SA128,128,128,128,128,128 (Sets the A parameter as follows:

Single-ended channel 1: A=128
Single-ended channel 2: A=128
Single-ended channel 3: A=128
Single-ended channel 3: A=128
Differential channel 1: A=128
Differential channel 2: A=128)


Command

SBP

Description

Sets the values of the BP parameters. Applies to single reads using the RA and RH commands, as well as the data streaming mode. This setting is stored in the RAM and applies immediately.

Syntax

Command: SBPp, where p is a comma-delimited list of six values — four for single-ended channels 1~4 and two for differential channels 1 and 2
Reply: A

Default values

Preset at the factory during the calibration process

Example

SBP8,8,8,8,8,4,3 (Sets the BP parameter as follows:

Single-ended channel 1: BP=8
Single-ended channel 2: BP=8
Single-ended channel 3: BP=8
Single-ended channel 3: BP=8
Differential channel 1: BP=4
Differential channel 2: BP=3)


Command

SBN

Description

Sets the values of the BN parameters. Applies to single reads using the RA and RH commands, as well as the data streaming mode. This setting is stored in the RAM and applies immediately.

Syntax

Command: SBNp, where p is a comma-delimited list of six values — four for single-ended channels 1~4 and two for differential channels 1 and 2
Reply: A

Default values

Preset at the factory during the calibration process

Example

SBN5,5,5,5,2,2 (Sets the BN parameter as follows:

Single-ended channel 1: BN=5
Single-ended channel 2: BN=5
Single-ended channel 3: BN=5
Single-ended channel 3: BN=5
Differential channel 1: BN=2
Differential channel 2: BN=2)

Command

GC

Description

Returns the current values of all RAM (current) settings.

Syntax

Command: GC
Reply: Asetting_str, where the setting_str contains the list of semicolon-separated RAM (current) setting values in the name=value(s) format; if a setting has several values, these values are separated by commas. Each name corresponds to the command used for changing the setting's value. For example, "SR=1000" would mean that the sampling rate (see the SR command) is set to 1000.

Example

Command: GC
Reply: ASR=1000;SM=1;SC=1,2;SD=0;SA=128,128,128,128,128,128;SBP=8,8,8,8,4,3;SBN=5,5,5,5,2,2;


Command

GE

Description

Returns the values of the EEPROM (post-reset) settings. Executing this command does not alter the values of the RAM (current) settings.

Syntax

Command: GE
Reply: Asetting_str, see the GC command for the setting_str description and example


Command

SE

Description

Copies the RAM (current) settings into the EEPROM (post-reset) settings. The next time the Tibbit boots up, these values will be copied into the RAM and used as operating parameters.

Syntax

Command: SE
Reply: A

Note: This command writes into the Tibbit's EEPROM. Tibbo recommends that you be extra careful with this command to avoid excessive EEPROM writing. While modern EEPROMs have a significant number of allowed write cycles, there is still a limit. For more information, see Prolonging and Estimating EEPROM Life. If the write to the EEPROM fails, this command will return the F status code.


Command

FE

Description

Copies the EEPROM (post-reset) settings into the RAM (current) settings. After this, the Tibbit will be running as if it just booted up. This is because the settings stored in the EEPROM are also fetched at boot.

Syntax

Command: FE
Reply: A

Note: The integrity of the EEPROM (post-reset) settings is protected by a checksum. If the checksum verification fails during the execution of this command, no EEPROM setting values will be copied into the RAM and the command will return the F status code.


Command

SF

Description

Restores all settings to their factory defaults (including the factory-programmed calibration values). This command overwrites the RAM (current) and EEPROM (post-reset) settings.

Syntax

Command: FE
Reply: A

Note 1: The integrity of the EEPROM (post-reset) settings is protected by a checksum. If the checksum verification fails during the execution of this command, no EEPROM setting values will be copied into the RAM, and the command will return the F status code.

Note 2: This command writes into the Tibbit's EEPROM. Tibbo recommends that you be extra careful with this command to avoid excessive EEPROM writing. While modern EEPROMs have a significant number of allowed write cycles, there is still a limit. For more information, see Prolonging and Estimating EEPROM Life. If the write to the EEPROM fails, this command will return the F status code.

Miscellaneous commands

Command

RA

Description

Obtains a single read on the specified channel(s) while staying in the command mode. The data is returned in the ASCII format.

Syntax

Command: RAp, where p is a comma-delimited list of active channels, from 1 to 4
Reply: Aadc_value(s), where the adc_values string is formatted as explained in the Data Output Formats topic, under ASCII format.

Note 1: Only CH1 and CH2 are available in the differential mode (see the SM command).  If CH3 and CH4 are specified while in the differential mode, the command will be rejected with the O status code.

Note 2: The channels are sampled in the order in which they are listed in this command.

Example

Command: RA4,1 (assuming the single-ended mode)
Reply: A7.2800,-4.2713; (channel 4: 7.2800V, channel 1: –4.2713V)


Command

RH

Description

Obtains a single read on the specified channel(s) while staying in the command mode. The data is returned in the hexadecimal format.

Syntax

Command: RAp, where p is a comma-delimited list of active channels, from 1 to 4
Reply: Aadc_value(s), where the adc_values string is formatted as explained in the Data Output Formats topic, under Hexadecimal format.

Note 1: Only CH1 and CH2 are available in the differential mode (see the SM command).  If CH3 and CH4 are specified while in the differential mode, the command will be rejected with the O status code.

Note 2: The channels are sampled in the order in which they are listed in this command.

Example

Command: RA4,1 (assuming the single-ended mode)
Reply: A099B,666A; (channel 4: 099B, channel 1: 666A)


Command

V

Description

Returns the version of the PIC microcontroller's firmware.

Syntax

Command: V
Reply: Aver_string

Example

Command: V
Reply: ATibbo Inc. Tibbit#43-1 FW1.1b