1. Home
  2. Docs
  3. MANUALS AND DATASHEETS
  4. EasyVR 3 Plus Manual
  5. EasyVR Programming

EasyVR Programming

Communication Protocol

Introduction

Communication with the EasyVR module uses a standard UART interface compatible with 3.3-5V TTL/CMOS logical levels, according to the powering voltage VCC.

A typical connection to an MCU-based host:

The initial configuration at power on is 9600 baud, 8 bit data, No parity, 1 bit stop. The baud rate can be changed later to operate in the range 9600 – 115200 baud.

The communication protocol only uses printable ASCII characters, which can be divided in two main groups:

  • Command and status characters, respectively on the TX and RX lines, chosen among lower-case letters.
  • Command arguments or status details, again on the TX and RX lines, spanning the range of capital letters.

Each command sent on the TX line, with zero or more additional argument bytes, receives an answer on the RX line in the form of a status byte followed by zero or more arguments.

There is a minimum delay before each byte sent out from the EasyVR module to the RX line, that is initially set to 20 ms and can be selected later in the ranges 0 – 9 ms, 10 – 90 ms, and 100 ms – 1 s. That accounts for slower or faster host systems and therefore suitable also for software-based serial communication (bit-banging) or communication proxies/bridges.

Since the EasyVR serial interface also is software-based, a very short delay might be needed before transmitting a character to the module, especially if the host is very fast, to allow the EasyVR to get back listening to a new character.

The communication is host-driven and each byte of the reply to a command has to be acknowledged by the host to receive additional status data, using the space character. The reply is aborted if any other character is received and so there is no need to read all the bytes of a reply if not required.

Invalid combinations of commands or arguments are signaled by a specific status byte, that the host should be prepared to receive if the communication fails. Also a reasonable timeout should be used to recover from unexpected failures.

If the host does not send all the required arguments of a command, the command is ignored by the module, without further notification, and the host can start sending another command.

The module automatically goes to lowest power sleep mode after power on. To initiate communication, send any character to wake-up the module.

Arguments Mapping

Command or status messages sent over the serial link may have one or more numerical arguments in the range -1 to 31, which are encoded using mostly characters in the range of uppercase letters. These are some useful constants to handle arguments easily:

ARG_MIN

‘@’ (40h) Minimum argument value (-1)

ARG_MAX

‘`’ (60h) Maximum argument value (+31)

ARG_ZERO

‘A’ (41h) Zero argument value (0)

ARG_ACK

‘ ‘ (20h) Read more status arguments

Having those constants defined in your code can simplify the validity checks and the encoding/decoding process. For example (in pseudo-code):

# encode value 5
FIVE = 5 + ARG_ZERO
# decode value 5
FIVE – ARG_ZERO = 5
# validity check
IF ARG < ARG_MIN OR ARG > ARG_MAX THEN ERROR

Just to make things clearer, here is a table showing how the argument mapping works:

ASCII @ A B C Y Z ^ [ ] _ `
HEX 40 41 42 43 59 5A 5B 5C 5D 5E 5F 60
Value -1 0 1 2 24 25 26 27 28 29 30 31

Command Details

This section describes the format of all the command strings accepted by the module. Please note that numeric arguments of command requests are mapped to upper-case letters (see above section).

Some commands share the same lower case letter, because there were no command identifiers available when the protocol has been expanded, but the first argument is used to discriminate.

CMD_BREAK

‘b’ (62h) Abort recognition, training or playback in progress if any or do nothing

Known issues:

In firmware ID 0, any other character received during recognition will prevent this command from stopping recognition that will continue until timeout or other recognition results.

Expected replies: STS_SUCCESS, STS_INTERR, STS_AWAKEN (if sleeping)

CMD_SLEEP

‘s’ (73h) Go to the specified power-down mode
[1] Sleep mode (0-8):

0 = wake on received character only

1 = wake on whistle or received character

2 = wake on loud sound or received character

3-5 = wake on double clap (with varying sensitivity) or received character

6-8 = wake on triple clap (with varying sensitivity) or received character

Expected replies: STS_SUCCESS

CMD_ID

‘x’ (78h) Request firmware identification
Expected replies: STS_ID

CMD_DELAY

‘y’ (79h) Set transmit delay
[1] Time (0-10 = 0-10 ms, 11-19 = 20-100 ms, 20-28 = 200-1000 ms)
Expected replies: STS_SUCCESS

CMD_BAUDRATE

‘a’ (61h) Set communication baud-rate
[1] Speed mode:

1 = 115200

2 = 57600

3 = 38400

6 = 19200

12 = 9600

Expected replies: STS_SUCCESS

CMD_LEVEL

‘v’ (76h) Set SD level
[1] Strictness control setting (1-5):

1 = easy

2 = default

5 = hard

A higher setting will result in more recognition errors.

Expected replies: STS_SUCCESS

CMD_KNOB

‘k’ (6Bh) Set SI knob to specified level
[1] Confidence threshold level (0-4):

0 = loosest: more valid results

2 = typical value (default)

4 = tightest: fewer valid results

Note: knob is ignored for trigger words

Expected replies: STS_SUCCESS

CMD_MIC_DIST

‘k’ (6Bh) Set the microphone operating distance
[1] Fixed to (-1)
[2] Distance settings (1-3):

1 = “headset” (around 5cm from speaker’s mouth)

2 = “arm’s length” (default setting, from about 50cm to 1m)

3 = “far mic” (up to around 3m)

Expected replies: STS_SUCCESS

CMD_TRAILING

‘t’ (74h) Set trailing silence for SI recognition
[1] Fixed to (-1)
[2] Amount of silence at the end of an utterance (0-31):

0 = 100ms

… in steps of 25ms

31 = 875ms

Expected replies: STS_SUCCESS

CMD_FAST_SD

‘f’ (66h) Set fast operating mode for SD/SV recognition
[1] Fixed to (-1)
[2] Operating mode (0 = normal/default, 1 = fast/low-latency)
Expected replies: STS_TOKEN, STS_TIMEOUT

CMD_LANGUAGE

‘l’ (6Ch) Set SI language
[1] Language:

0 = English

1 = Italian

2 = Japanese

3 = German

4 = Spanish

5 = French

Expected replies: STS_SUCCESS

CMD_TIMEOUT

‘o’ (6Fh) Set recognition timeout
[1] Timeout (-1 = default, 0 = infinite, 1-31 = seconds)
Expected replies: STS_SUCCESS

CMD_RECOG_SI

‘i’ (69h) Activate SI recognition from specified word set
[1] Word set index (0-3)
Expected replies: STS_SIMILAR, STS_TIMEOUT, STS_ERROR

CMD_TRAIN_SD

‘t’ (74h) Train specified SD/SV command
[1] Group index (0 = trigger, 1-15 = generic, 16 = password)
[2] Command position (0-31)
Expected replies: STS_SUCCESS, STS_RESULT, STS_SIMILAR, STS_TIMEOUT, STS_ERROR

CMD_GROUP_SD

‘g’ (67h) Insert new SD/SV command
[1] Group index (0 = trigger, 1-15 = generic, 16 = password)
[2] Position (0-31)
Expected replies: STS_SUCCESS, STS_OUT_OF_MEM

CMD_UNGROUP_SD

‘u’ (75h) Remove SD/SV command
[1] Group index (0 = trigger, 1-15 = generic, 16 = password)
[2] Position (0-31)
Expected replies: STS_SUCCESS

CMD_RECOG_SD

‘d’ (64h) Activate SD/SV recognition
[1] Group index (0 = trigger, 1-15 = generic, 16 = password)
Expected replies: STS_RESULT, STS_SIMILAR, STS_TIMEOUT, STS_ERROR

CMD_ERASE_SD

‘e’ (65h) Erase training of SD/SV command
[1] Group index (0 = trigger, 1-15 = generic, 16 = password)
[2] Command position (0-31)
Expected replies: STS_SUCCESS

CMD_NAME_SD

‘n’ (6Eh) Label SD/SV command
[1] Group index (0 = trigger, 1-15 = generic, 16 = password)
[2] Command position (0-31)
[3] Length of label (0-31)
[4-n] Text for label (ASCII characters from ‘A’ to ‘`’)

EasyVR Commander encodes digits 0-9 as A-J prefixed by ‘^’

Expected replies: STS_SUCCESS

CMD_COUNT_SD

‘c’ (63h) Request count of SD/SV commands in the specified group
[1] Group index (0 = trigger, 1-15 = generic, 16 = password)
Expected replies: STS_COUNT

CMD_DUMP_SD

‘p’ (70h) Read SD/SV command data (label and training)
[1] Group index (0 = trigger, 1-15 = generic, 16 = password)
[2] Command position (0-31)
Expected replies: STS_DATA

CMD_MASK_SD

‘m’ (6Dh) Request bit-mask of non-empty groups
Expected replies: STS_MASK

CMD_RESETALL

‘r’ (72h) Reset all (erase commands/groups and messages)
‘R’ (52h) Confirmation character
Expected replies: STS_SUCCESS

CMD_RESET_SD

‘r’ (72h) Reset only commands and groups
‘D’ (52h) Confirmation character
Expected replies: STS_SUCCESS

CMD_RESET_RP

‘r’ (72h) Reset only message recordings
‘M’ (52h) Confirmation character
Expected replies: STS_SUCCESS

CMD_QUERY_IO

‘q’ (71h) Configure, query or modify general purpose I/O pins
[1] Pin number (1 = pin IO1, 2 = pin IO2, 3 = pin IO3)
[2] Pin mode (0 = output low, 1 = output high, 2 = input*, 3 = input strong**, 4 = input weak***)

* High impedance input (no pull-up)

**Strong means ~10K internal pull-up

***Weak means ~200K internal pull-up (default after power up)

Expected replies: STS_SUCCESS (mode 0-1), STS_PIN (mode 2-4)

CMD_PLAY_SX

‘w’ (77h) Wave table entry playback
[1-2] Two positive values that form a 10-bit index to the sound table (index = [1] * 32 + [2], 0 = built-in “beep”, 1-1023 = sound index)
[3] Playback volume (0-31, 0 = min volume, 15 = full scale, 31 = double gain)
Expected replies: STS_SUCCESS, STS_ERROR

CMD_PLAY_DTMF

‘w’ (77h) Play a DTMF key tone or dial tone
[1] Fixed to (-1)
[2] Index of phone tone to play (0-9 for digits, 10 for ‘*’ key, 11 for ‘#’ key and 12-15 for extra keys ‘A’ to ‘D’, -1 for the dial tone)
[3] Tone duration minus 1 (0-31 in 40ms units for keys, in seconds for the dial tone)
Expected replies: STS_SUCCESS

CMD_DUMP_SX

‘h’ (68h) Read wave table data
Expected replies: STS_TABLE_SX, STS_OUT_OF_MEM

 

CMD_DUMP_SI

‘z’ (7Ah) Read custom and built-in grammars data
[1] Index of SI grammar to read (0-31) or (-1) to get the total count of SI grammars (including the first 4 built-in word sets)
Expected replies: STS_GRAMMAR, STS_COUNT

CMD_SEND_SN

‘j’ (6Ah) Send a SonicNetTM token
[1] Length of token (4 or 8 in bits)
[2-3] Two positive values that form an 8-bit token index (index = [2] * 32 + [3], 0-15 for 4-bit tokens or 0-255 for 8-bits tokens)
[4-5] Two positive values that form a 10-bit delay for token output since the next sound playback (delay = [4] * 32 + [5], 0 = send immediately, 1-1023 = delay in units of 27.46ms)
Expected replies: STS_SUCCESS

CMD_RECV_SN

‘f’ (66h) Receive a SonicNetTM token
[1] Length of token (4 or 8 in bits)
[2] Rejection level (0-2 = higher values mean fewer results, 1 = default)
[3-4] Two positive values that form a 10-bit timeout for token detection (timeout = [3] * 32 + [4], 0 = wait forever, 1-1023 = timeout in units of 27.46ms)
Expected replies: STS_TOKEN, STS_TIMEOUT

CMD_LIPSYNC

‘l’ (6Ch) Start real-time lip-sync
[1] Fixed to (-1)
[2-3] Activation threshold (10-bit value = [2] * 32 + [3]):

270 = default setting

[4-5] Timeout option (8-bit value = [4] * 16 + [5]):

0 = no timeout (can be interrupted)

1-255 = duration in seconds

Expected replies: STS_LIPSYNC

CMD_RECORD_RP

‘r’ (72h) Record a message
[1] Fixed to (-1)
[2] Message index (0-31)
[3] Data format (8)
[4] Timeout option (0-31):

0 = no timeout (can be interrupted)

1-31 = duration in seconds

Expected replies: STS_SUCCESS, STS_ERROR

CMD_PLAY_RP

‘p’ (70h) Play a message recording
[1] Fixed to (-1)
[2] Message index (0-31)
[3] Playback options (bit-mask):

Bit 2 (4) = playback speed (0 = normal, 1 = fast)

Bit 1-0 (0-3) = volume attenuation (0 = normal, 1 = -2.2dB, 2 = -4.5dB, 3 = -6.7dB)

Expected replies: STS_SUCCESS, STS_ERROR

CMD_ERASE_RP

‘e’ (65h) Erase a message recording
[1] Fixed to (-1)
[2] Message index (0-31)
Expected replies: STS_SUCCESS, STS_ERROR

CMD_VERIFY_RP

‘v’ (76h) Verify file-system integrity for message recordings
[1] Fixed to (-1)
[2] Type of operation:

0 = check only

1 = check and fix errors

Expected replies: STS_SUCCESS, STS_ERROR

CMD_SERVICE + SVC_EXPORT_SD

‘~’ (7Eh) Service protocol expansion
‘X’ (58h) Export command raw data
[1] Group index (0 = trigger, 1-15 = generic, 16 = password)
[2] Command position (0-31)
Expected replies: STS_SERVICE + SVC_DUMP_SD

CMD_SERVICE + SVC_IMPORT_SD

‘~’ (7Eh) Service protocol expansion
‘I’ (49h) Import command raw data
[1] Group index (0 = trigger, 1-15 = generic, 16 = password)
[2] Command position (0-31)
[3-514] Raw command data (encoded as hex nibbles – byte = [n] * 16 + [n+1])
[515-518] Data checksum (16-bit sum of all 256 bytes, starting at 1234h)
Expected replies: STS_SUCCESS, STS_INTERR (if checksum fails)

CMD_SERVICE + SVC_VERIFY_SD

‘~’ (7Eh) Service protocol expansion
‘V’ (56h) Verify command raw data
[1] Group index (0 = trigger, 1-15 = generic, 16 = password)
[2] Command position (0-31)
Expected replies: STS_SUCCESS, STS_RESULT, STS_SIMILAR, STS_ERROR

Status Details

Replies to commands follow this format. Please note that numeric arguments of status replies are mapped to upper-case letters (see the related section).

STS_MASK

‘k’ (6Bh) Mask of non-empty groups
[1-8] 4-bit values that form 32-bit mask, LSB first
In reply to: CMD_MASK_SD

STS_COUNT

‘c’ (63h) Count of commands or total number of SI grammars
[1] Integer (0-31 = command/grammar count, -1 = 32 commands/grammars)
In reply to: CMD_COUNT_SD, CMD_DUMP_SI

STS_AWAKEN

‘w’ (77h) Wake-up (back from power-down mode)
In reply to: Any character after power on or sleep mode

STS_DATA

‘d’ (64h) Provide command data
[1] Training information (-1=empty, 1-6 = training count, +8 = SD/SV conflict, +16 = SI conflict)
Known issues:
In firmware ID 0, command creation/deletion might cause other empty commands training
count to change to 7. Treat count values of -1, 0 or 7 as empty training markers. Never train
commands more than 2 or 3 times.
[2] Conflicting command position (0-31, only meaningful when trained)
[3] Length of label (0-31)
[4-n] Text of label (ASCII characters from ‘A’ to ‘`’)
EasyVR Commander encodes digits 0-9 as A-J prefixed by ‘^’
In reply to: CMD_DUMP_SD

STS_ERROR

‘e’ (65h) Signal recognition error
[1-2] Two positive values that form an 8-bit error code (error = [1] * 16 + [2], see appendix)
In reply to: CMD_RECOG_SI, CMD_RECOG_SD, CMD_TRAIN_SD, CMD_PLAY_SX

STS_INVALID

‘v’ (76h) Invalid command or argument
In reply to: Any invalid command or argument

STS_TIMEOUT

‘t’ (74h) Timeout expired
In reply to: CMD_RECOG_SI, CMD_RECOG_SD, CMD_TRAIN_SD

STS_LIPSYNC

‘l’ (6Ch) Lip-sync streaming data
[1-N] Mouth position (0-31):
0 = fully closed
31 = fully open
Note:
New values are available at request around every 27ms until timeout occurs or command is
interrupted. A new status is sent at the end (see STS_TIMEOUT, STS_INTERR).
In reply to: CMD_LIPSYNC

STS_INTERR

‘i’ (69h) Interrupted recognition
In reply to: CMD_BREAK while in training, recognition or playback

STS_SUCCESS

‘o’ (6Fh) OK or no errors status
In reply to: CMD_BREAK, CMD_DELAY, CMD_BAUDRATE, CMD_TIMEOUT, CMD_KNOB, CMD_LEVEL, CMD_LANGUAGE, CMD_SLEEP, CMD_GROUP_SD, CMD_UNGROUP_SD, CMD_ERASE_SD, CMD_NAME_SD, CMD_RESETALL, CMD_QUERY_IO, CMD_PLAY_SX, etc.

STS_RESULT

‘r’ (72h) Recognized SD/SV command or Training similar to SD/SV command
[1] Command position (0-31)
In reply to: CMD_RECOG_SD, CMD_TRAIN_SD

STS_SIMILAR

‘s’ (73h) Recognized SI word or Training similar to SI word
[1] Word index (0-31)
In reply to: CMD_RECOG_SI, CMD_RECOG_SD, CMD_TRAIN_SD

STS_OUT_OF_MEM

‘m’ (6Dh) Memory error (no more room for commands or sound table not present)
In reply to: CMD_GROUP_SD, CMD_DUMP_SX

STS_ID

‘x’ (78h) Provide firmware identification
[1] Version identifier (0 = VRbot, 1-7 = EasyVR 2, 8-15 = EasyVR 3, 16+ = EasyVR 3 Plus)
In reply to: CMD_ID

STS_PIN

‘p’ (70h) Provide pin input status
[1] Logic level (0 = input low, 1 = input high)
In reply to: CMD_QUERY_IO

STS_TABLE_SX

‘d’ (64h) Provide sound table data
[1-2] Two positive values that form a 10-bit count of entries in the sound table (count = [1] * 32 +[2])
[3] Length of table name (0-31)
[4-n] Text of table name (ASCII characters from ‘A’ to ‘`’)
In reply to: CMD_DUMP_SX

STS_GRAMMAR

‘z’ (7Ah) Provide custom grammar data
[1] Some flags for this grammar (currently16 is returned for trigger grammars, 0 for commands)
[2] Number of commands in this grammar (0-31)
[3] Length of first command label (0-31)
[4-n] Text of first command label (ASCII characters from ‘A’ to ‘`’)
Repeat last two fields for all the commands in this grammar
In reply to: CMD_DUMP_SI

STS_TOKEN

‘f’ (66h) Detected a SonicNetTM token
[1-2] Two positive values that form the index of a received token (index = [1] * 32 + [2], 0-15 for 4-bit tokens or 0-255 for 8-bits tokens)
In reply to: CMD_RECV_SN

STS_SERVICE + SVC_DUMP_SD

‘~’ (7Eh) Service protocol expansion
‘D’ (44h) Provide command raw data
[1-512] Raw command data (encoded as hex nibbles – byte = [n] * 16 + [n+1])
[513-516] Data checksum (16-bit sum of all 256 bytes, starting at 1234h)
In reply to: CMD_SERVICE + SVC_EXPORT_SD

Articles

How can we help?