USB command interface

When present, “#” refers to the Arduino pin number used in the operation

command	value	action
?#ai	int	returns NUM_ANALOG_INPUTS
?ai	0..1023	returns current value of numbered analog input
!ai:watch	0..1	sets up ai pin for averaging
?ai:mean	long	returns <ai>*k
?#bi	int	returns NUM_DIGITAL_PINS
?bi	0..1	returns current value of numbered digital input
!bo	0..1	sets numbered digital output to value v
!pwm	0..255	sets numbered PWM digital output to value v
!pin	0..1	sets mode of digital pin to value v (value: 1=OUTPUT, not 1=INPUT)
!t	long	sets averaging time, ms
?t	long	returns averaging time, ms
?t:min	long	returns minimum allowed averaging time, ms
?t:max	long	returns maximum allowed averaging time, ms
!k	long	sets averaging factor (k)
?k	long	returns averaging factor (k)
?k:min	long	returns minimum allowed averaging factor (k)
?k:max	long	returns maximum allowed averaging factor (k)
?v	string	returns version string
?id	0	returns identification string
?rate	long	returns number of updates (technically: loops) per second
other		returns “ERROR_UNKNOWN_COMMAND:text”

notes:

1. must use lower case (as shown in table)
2. integers must be specified in decimal (no octal or hex interpreted)
3. pin numbers are not checked for correctness in the current version
4. ? commands return an integer
5. ! commands return Ok
6. Errors, starting with ERROR_ will substitute for expected output

---

commands

Note

Note about code examples below

In all code examples below, command input to the Arduino is shown as:

>>> some command

Response from the Arduino appears on the next line. When entering commands, do not type the “>>>” symbols.

?#ai

purpose:

How many ANALOG IN channels on this Arduino?

command:

?#ai

returns:

value of NUM_ANALOG_INPUTS as defined for this model of Arduino

example:

(on Arduino Mega2560)

>>> ?#ai
16

?ai

purpose:

read an ANALOG IN channel value

command:

?ai pin

returns:

Returns the analog input pin value specified. The returned value is between 0 and 1023 (10-bit ADC) which represents a measured voltage between 0 and 5 VDC. The pin must be within the range of 0..NUM_ANALOG_INPUTS

example:

>>> ?ai 0
171

!ai:watch

purpose:

Enables (or disables) signal averaging for the specified analog input pin. Note that it is possible to turn this feature on and off at run time.

command:

!ai:watch pin 1|0

returns:

Ok

default:

by default, no ai pins are averaged

example:

>>> !ai:watch 0 1
Ok

To optimize the time to process the Arduino’s loop() function, only those ANALOG IN channels to be averaged will be watched. By default, when the Arduino sketch starts, no channels are watched. (That is, the configuration of watched channels is not stored in persistent memory on the Arduino.)

?ai:mean

purpose:

read a time-averaged ANALOG IN channel value

command:

?ai:mean pin

returns:

Returns the average analog input pin value specified, multiplied by a factor \(k\). The factor is requested by the ?k command and set by the !k command. The returned value is between 0 and 1023 (10-bit ADC) which represents a measured voltage between 0 and 5 VDC. The pin must be within the range of 0..NUM_ANALOG_INPUTS (use ?#ai to get NUM_ANALOG_INPUTS) and must first be configured for signal averaging by calling !ai:watch pin 1.

example:

>>> !ai:watch 0
Ok
>>> ?ai:mean 0
171000

?#bi

purpose:

How many DIGITAL channels on this Arduino?

command:

?#bi

returns:

value of NUM_DIGITAL_PINS as defined for this model of Arduino.

example:

(on Arduino Mega2560)

>>> ?#bi
70

?bi

purpose:

Reads the digital input pin specified in the first argument. The returned value is either 0 or 1. The pin must be within the range of 0..NUM_DIGITAL_PINS. (Use ?#bi to get NUM_DIGITAL_PINS.)

command:

?bi pin

returns:

0|1

example:

>>> ?bi 3
0

!bo

purpose:

Sets the digital output pin specified in the first argument to the value specified in the second argument. If the syntax is correct and the value is within range, returns Ok. The pin must be within the range of 0..NUM_DIGITAL_PINS and must first be configured for output by calling !pin pin 1. (Use ?#bi to get NUM_DIGITAL_PINS.)

command:

!bo pin value

returns:

Ok

example:

>>> !pin 6 1
Ok
>>> !bo 6 0
Ok

Note

Selection of a digital pin as INPUT (0) or OUTPUT (1) is based on the hardware wiring for that channel. While configurable at run time, it is not expected to change this after its first setting.

!pwm

purpose:

Sets the PWM-enabled digital output pin specified in the first argument to the value specified in the second argument. If the syntax is correct and the value is within range, returns Ok. The pin must first be configured for output by calling !pin pin 1.

The pin number is checked for PWM hardware-support by a call to the digitalPinHasPWM(pin) macro (which is defined by the Arduino SDK for each supported board type in <Arduino>/hardware/arduino/variants/*/pins_arduino.h).

command:

!pwm pin value

returns:

Ok

example:

>>> !pwm 11 127
Ok

!pin

purpose:

Configures the digital output pin specified in the first argument for output as a binary digital output and also as a PWM digital output if the hardware enables this.

value	meaning
0	use pin as input
1	use pin as output

command:

!pin pin value

returns:

Ok

default:

all pins are configured for input by default

example:

>>> !pin 11 1
Ok

Note

Selection of a digital pin as INPUT (0) or OUTPUT (1) is based on the hardware wiring for that channel. While configurable at run time, it is not expected to change this after its first setting.

!t

purpose:

Sets the length of the averaging period (milliseconds). The argument period_ms (noted here as \(t\)) must satisfy \(t_l <= t <= t_h\) or an error is returned. Here \(t_l\) is returned by ?t:min and \(t_h\) is returned by ?t:max.

The period can be changed at run time as fits the application.

command:

!t period_ms

returns:

Ok

example:

>>> !t 100
Ok

?t

purpose:

Read the length of the averaging period (milliseconds).

command:

?t

returns:

length of averaging period (ms)

default:

1000

example:

>>> ?t
1000

?t:min

purpose:

Returns \(t_l\), the minimum permitted length of the averaging period (milliseconds). The minimum length is fixed, somewhat arbitrarily, to allow for at least a couple of updates if as many as 16 AI channels are to be averaged.

command:

?t:min

returns:

minimum allowed value of averaging period (ms)

default:

5

example:

>>> ?t:min
5

?t:max

purpose:

Returns \(t_h\), the maximum permitted length of the averaging period (milliseconds). The maximum length is fixed, somewhat arbitrarily, to ~1 hour. Is any longer really necessary?

command:

?t:max

returns:

maximum allowed value of averaging period (ms)

default:

3600000

example:

>>>
1000000

!k

purpose:

Sets the multiplier to use when reporting averaged AI values. The argument multiplier (noted here as \(k\)) must satisfy \(k_l <= k <= k_h\) or an error is returned. Here \(k_l\) is returned by ?k:min and \(k_h\) is returned by ?k:max.

command:

!k multiplier

returns:

Ok

example:

>>> !k 100
Ok

?k

command:

?k

returns:

multiplier \(k\) used when reporting averaged AI values

default:

1000

example:

>>> ?k
1000

?k:min

purpose:

Returns \(k_l\), the minimum permitted multiplier used when reporting averaged AI values. The minimum multiplier is set, logically, at 1.

command:

?k:min

returns:

minimum allowed value of multiplier \(k\)

default:

1

example:

>>> ?k:min
1

?k:max

purpose:

Returns \(k_h\), the maximum permitted multiplier used when reporting averaged AI values. The maximum length is fixed, somewhat arbitrarily, at some large number.

command:

?k:max

returns:

maximum allowed value of multiplier \(k\)

default:

1000000

example:

>>> ?k:max
1000000

?rate

purpose:

How many ADC readings per second?

command:

?rate

returns:

Returns the number of update loops per second. Each additional AI to be watched will decrease this number due to the operations of reading, accumulating, and averaging the signal.

The update rate serves no purpose to the operation of the Arduino as an I/O controller. It is only provided as a diagnostic signal for the remote control system.

example:

(Arduino Mega2560 with no AI channels watched)

>>> ?rate
25867

?v

command:?v returns:Returns the software version string.

example:

>>> ?v
2013-12-01

(Actual value will be different than shown.)

?id

command:?id returns:Returns the software identifying string.

example:

>>> ?id
cmd_response

Example Commands

1. Read analog input from pin 0:

>>> ?ai 0
41

2. Set digital pin 11 for PWM output:

>>> !pin 11 1
Ok

3. Set PWM output pin 11 to 128:

>>> !pwm 11 128
Ok

4. Show how a bad command (no space between baseCmd and pin) is handled:

>>> !pwm11 128
ERROR_UNKNOWN_COMMAND:!pwm11 128

Communications Parameters

term	value
communications rate	115200
line terminator	\n
buffer length (chars)	40
command length (chars)	16

file: cmd_reponse.ino

The full Arduino cmd_response.ino code listing is too large for this documentation.

EPICS Streams protocol:  cmd_response.ino