BitScope Control Plane Protocol

Table of Contents

1 Overview

This document defines the client/server protocol used to manage BitScope Cluster Modules.

The protocol is accessed via:

  1. command line interface, or
  2. websockets machine interface.

A set of python command line programs are available for websocket interface.

2 Protocol

Commands are issued and replies are returned in response.

The protocol sequence is:

  1. The client issues a command to the server.
  2. The server returns a reply to the client.
  3. A reply is only ever sent in response to a command.
  4. A reply may comprise a command response or error response.
  5. The protocol is atomic, queued commands are not allowed.

All commands and replies use similar context sensitive semantics and syntax comprising a command, reply or error token, an optional object reference and zero or more arguments.

Each command token may be abbreviated to the shortest possible string that is unique among the commands strings defined for the protocol and many arguments are optional. This makes using the protocol from the command line convenient.

3 Syntax

These meta-characters are used to describe syntactical elements of the protocol:

Character Grammatical Meaning
A-Z Symbols
? Preceding item is optional
- Range of characters
+ Preceding item appears one or more times
* Preceding item appears zero or more times
[] Character set
() Grouped
| Alternatives

The commands comprise a series of symbols complying with these syntactical definitions.

Symbol Usage Regular Expression
TOK Command/Reply and Enumerated Value tokens. [a-z_][0-9a-z_]*
STR Character string “[a-z0-9A-Z_]+”
INT Signed integer values (decimal) [-+]?[0-9]+
ORD Unsigned integer value (decimal) `[0-9]+`
HEX Unsigned integer values (hexadecimal) [0-9A-Fa-f]+
FLOAT Floating point number (decimal) [-+]?([0-9]*[.])?[0-9]+
BOOL Boolean value true | false

3.1 Commands

COMMAND INDEX ? ARGUMENT *

COMMAND TOK Command token
INDEX ORD Optional object reference
ARGUMENT * Zero or more arguments

3.2 Replies

REPLY INDEX ? RESULT *

REPLY TOK Command token
INDEX ORD Optional object reference
RESULT * Zero or more result values

3.3 Errors

error INDEX ? STATUS CODE

INDEX INT Command object reference
STATUS => ok | busy | bad | CODE
ok TOK Command completed successfully
busy TOK Busy executing command
bad TOK Unrecognised command or syntax error
CODE => ID NAME
ID INT Error code
NAME STR Error string

4 Commands

The full set of commands and their associated replies are in this section.

The token used for the reply is the same as that of its command.

If an error occurs, an error may be returned instead of a reply.

4.1 module

Select the cluster module to be controlled. If there is only one, or one is running the client locally on the module itself, this command is redundant.

module INDEX?

INDEX ORD Index of cluster module from 0 to N-1 where N = number of modules in the cluster. If N is not specified, report previously selected module. If N is legal, the previously selected module is used.

This command replies with:

module INDEX

INDEX ORD Index of the selected cluster module.<br>If none selected, returns -1.

4.2 ping

Test communication with the Blade Runner control plane on the selected cluster module.

ping MESSAGE ?

MESSAGE STR Optional test message

This command replies with:

ping MESSAGE ?

MESSAGE STR Optional test message

4.3 led

Control the led on the bitbar cluster control boards. This is typically used to indicate correct or erroneous operation.

led PACK BAR STATE ?

PACK ORD Index of cluster pack from 0 to N-1 where N = number of cluster packs in the module.
BLADE ORD Index of the bar in the cluster pack 0 to N-1 where N = number of bars on the blades used by the pack.
STATE BOOL true to turn led on, false to turn led off. If not specified, report led state only.

which replies with:

led PACK BAR STATE

PACK ORD Index of cluster pack from 0 to N-1 where N = number of cluster packs in the module.
BLADE ORD Index of the bar in the cluster pack 0 to N-1 where N = number of bars used by the pack.
STATE BOOL true if LED is on <br> false if LED is off

4.4 power

Controls power to each cluster module node individually.

The cluster module is built from one or more cluster packs each of which comprise one or more nodes.

power PACK NODE STATE ?

PACK ORD Index of cluster pack from 0 to N-1 where N = number of cluster packs in the module.
NODE ORD Index of the node in the cluster pack 0 to N-1 where N = number of nodes in the selected cluster pack.
STATE BOOL true to turn node on and false to turn node off. If not specified, report power state only.

which replies with:

power PACK NODE STATE

PACK ORD Index of cluster pack.
NODE ORD Index of the node in the cluster pack.
STATE BOOL true if node is on or false if node is off

4.5 blade

Enquire the current status of a cluster module blade.

The cluster module is built from one or more cluster packs each of which comprise one or more blades where each blade mounts one or more nodes. See the power and node commands for information about controlling and acquiring data from nodes.

blade PACK BLADE

PACK ORD Index of cluster pack from 0 to N-1 where N = number of cluster packs in the module.
BLADE ORD Index of the blade in the cluster pack 0 to N-1 where N = number of blades in the selected cluster pack.

which replies with:

blade PACK NODE SUPPLY CURRENT VOLTAGE TEMPERATURE

PACK ORD Index of cluster pack
BLADE ORD Index of the blade in the cluster pack.
SUPPLY FLOAT Instantaneous 24 volt supply reading in Volts
CURRENT FLOAT Instantaneous current consumed by blade in Amps
VOLTAGE FLOAT Instantaneous 5 volt supply reading in Volts
TEMPERATURE FLOAT Instantaneous temperature in Celsius

4.6 node

Enquire the current status of a cluster module node. The cluster module is built from one or more cluster packs each of which comprise one or more nodes.

node PACK NODE

PACK ORD Index of cluster pack from 0 to N-1 where N = number of cluster packs in the module.
NODE ORD Index of the node in the cluster pack 0 to N-1 where N = number of nodes in the selected cluster pack.

which replies with:

node PACK NODE CURRENT TEMPERATURE ON FLAGS CONSOLE

PACK ORD Index of cluster pack.
NODE ORD Index of the node in the cluster pack.
CURRENT FLOAT Instantaneous current consumed by node in amps.
ON BOOL On status of the node.
FLAGS HEX Value of node user controllable flags.
CONSOLE ORD Number of bytes ready in node console buffer

4.7 console

Read diagnostic data from the selected node's console port.

console PACK NODE COUNT

PACK INT Index of cluster pack from 0 to N-1 where N = number of cluster packs in the module.
NODE INT Index of the node in the cluster pack 0 to N-1 where N = number of nodes in the selected cluster pack.
COUNT INT Maximum number of ASCII characters to read from the node console.

console PACK NODE COUNT DATA

PACK INT Index of cluster pack.
NODE INT Index of the node in the cluster pack.
COUNT INT Number of ASCII characters read from the node console
DATA STR Console ASCII data. If COUNT is zero, then DATA will be “” (empty string).

5 References

Permalink docs.bitscope.com/G4T3ZVH5
Document ID G4T3ZVH5 06
Copyright © 2018~2020 BitScope Designs