Meditech: The control panel command parser

12 Jul 2015

Introduction

As mentioned elsewhere in the previous posts the Meditech control panel is under the control of the Chipkit PI micro controller board. The board has the following roles in the architecture of the system:

Manages the critical event alarms when a overheating occur and the lid open alert when the control panel is opened (this influences the behaviour of the entire system).
Shows a fast and updated short information on the alphanumeric LCD panel; the LCD screen instead is under the control of the RPI master showing more complex information with different update timing.
Set the probes status LEDs
gives immediate feedback over the active probe control (if any) via the potentiometer that assumes different functions depending on what probe the user has chosen.

So a part of the ChipKit micro controller firmware is controlled by periodical scheduled events (tasks) and interrupts running independently by the rest of the system and a part of the firmware executes commands (requests) sent by the RPI master (the main Raspberry PI 2 unit) and send requests to it.

To manage properly a reliable and efficient communication between the two device (control panel and master) has been defined a communication protocol with a rigid syntax. The communication process is bidirectional and any command is always acknowledged to the sender from the receiver.

Syntax

As every command has a different set of parameters (including the case of no parameters), what was needed was not a bare data exchange protocol but something more complex, a real syntax able do represent all the possible (and future) commands conditions. In short words, the assumptions are the following:

Almost all the possible types (int, long, float, strings) should be represented
Every command has a variable number of parameters depending on what the command do, so this aspect can't be standardized
The command should be simple to transmit and as fast as possible to be received and processed by the receiver
The syntax should support roles that can be expanded in future
Every command has a different timing in its execution
The syntax should support the implementation of future, not yet known, commands.
The syntax should be simple, to make the parser fast also on the - relatively - slow speed of the microcontroller.

By the other side we have some great advantages:

The syntax complexity does no matter as this is a machine-to-machine language
The syntax can be rigid: all the rules are software encoded so it does no matter how these are fixed
There is no need of a semantic control; these are almost all independent commands. The only option is that a command, if it is received in a wrong condition it is not executed
Special boolean condition and loop cycles are not needed. It is a sequential machine.

Note that loops and other features are supported but not needed nor used in this version as the parser support the execution of macros that can include cycle repetitions of group of commands and conditional jumps: labels, conditional jumps and cycles are macro commands (i.e. parameters recognised by the specific command "macro"

Syntax rules

The syntax rules are single character operands, including the command name itself, that is the first parameter of a command string.

'@' - Command separator: Every command should start with this character; all the characters outside the command separator are ignored and cam be used as comments. Take in account that comment are not parsed but are sent so long comments require more transmission time. The same character is used as command terminator but it is optional as it is added by the parser automatically.

';' - Field separator. Every field in a command string should be separated by the field separator character.

'<Command Code>' The command code is a single-character command name, case-sensitive.

'"' - String delimiter. Every field that is a variable-length string should be in the format "string", just as in almost any programming language.

":" - Response separator. It is the character separating the acknowledge string sent to the sender after the parser has completed the command execution.

Every command can include a subcommand, processed recursively as the commands. If the parser meet an error the parsing process is immediately stopped and the acknowledge string with the command code and the error code (numeric) is sent to the sender. An exit condition with the error code 0 means that the command execution has been completed successfully.

The limits for every type of recognised fields are the following:

Integer: 5 characters in the form 00000

Long Integer: 7 characters in the form 0000000

Floating Point: 1 characters in the form 0000000.000

Field ID (used for row, column positions in the display): 2 characters in the form 00

Boolean: 1 character in the form 0

String: variable length between two string delimiters.

The general command syntax is in the following form:

@<command>[;<subcommand>][;<field>];]@

Commands

E - Enable

Enable a probe and accept setting parameters or disable the probe if already enabled. The subcommand contains the probe subcommand name

usage: E;<subcommand>

example: @E;S

Enable the microphonic stethoscope

The Enable command only activates the set bit of the current probe. If the enable bit is not set the corresponding display layout on the control panel LCD can't be changed due the probe-dependant settings that the probe-enabled status involves. The right method to display a probe template is to enable it then send a template command to the control panel with the display layout parameters.

D - Display

This is a descriptive command only, reflecting the state of a user request from the remote IR controller. The row and column values should be integers, zero-based, inside the physical limits of the LCD display.

usage: D;<row(int)>;<column(int)>;<string>

example: @D;01;03;"Test"

This command needs less controls than expected because errors like out of bound string length, wrong cursor position etc. never occurs using the display templates. Templates include file is the same on both the master and the micro controller with the difference that the master also includes the strings definition that are sent when a display should be drawn with a template.

L - LCD Template

Parameters to generate a template layout with a variable number of parameters, depending on the requested template.

usage: L;<Template ID>;[[;<Field String>];]

example: @L;05;"Panel Test";"Running"

If the requested layout template is a probe display template the command has effect only if the probe status bit is set to on (current probe active)

I - Info

Shows the current health status parameters of the control panel (temperature, fan speed, active flags etc.)

usage: I

example: @I

T - Test

Suspend all the active interrupts and tasks and execute a full test of the control panel.

usage: T

example: @T

R - Receive

Receive from the master the requested value for one of the template fields to show on the display. In most of the cases these are strings managed by the master to save memory space on the board and support the multi-language localisation.

usage: R;<parameter ID>;<value>

example: @R;03;00123