# Commands

## Command System

A command system is required to send commands to the vocalizer. The following systems are supported:

[Kyber Control System](https://www.facebook.com/groups/1341505756182087/) — Support coming soon. Mention Human-Cyborg Relations when purchasing and the Kyber team will generously donate $10 to [FIRST Robotics](https://www.firstinspires.org).

DIY — Build your own control system. As a starting point, see the [C++ command API](https://github.com/roy86/HumanCyborgRelationsAPI) developed by Alec Muir.

## Commands

Commands can be sent over Serial, UART, or I2C. All commands must be wrapped in a container:  `<...>`

To send multiple commands at once, include them within a single container separated by commas: `<...,...>`

...or chain multiple containers in a single string: `<...><...>`

<table><thead><tr><th width="169">Command</th><th width="166.33333333333331">Response</th><th>Description</th></tr></thead><tbody><tr><td><strong>Stimuli</strong></td><td></td><td></td></tr><tr><td>SH0</td><td></td><td>Trigger mild happy vocalization</td></tr><tr><td>SH1</td><td></td><td>Trigger extreme happy vocalization</td></tr><tr><td>SS0</td><td></td><td>Trigger mild sad vocalization</td></tr><tr><td>SS1</td><td></td><td>Trigger extreme sad vocalization</td></tr><tr><td>SM0</td><td></td><td>Trigger mild angry vocalization</td></tr><tr><td>SM1</td><td></td><td>Trigger extreme angry vocalization</td></tr><tr><td>SC0</td><td></td><td>Trigger mild scared vocalization</td></tr><tr><td>SC1</td><td></td><td>Trigger extreme scared vocalization</td></tr><tr><td>SE</td><td></td><td>Trigger <a href="../../../features/stimuli#undefined">overload/electrocution</a> vocalization</td></tr><tr><td><strong>Muse</strong></td><td></td><td></td></tr><tr><td>M1</td><td></td><td>Enable <a href="../../features/muse">muse</a></td></tr><tr><td>M0</td><td></td><td>Disable <a href="../../features/muse">muse</a></td></tr><tr><td>MT</td><td></td><td>Toggle <a href="../../features/muse">muse</a></td></tr><tr><td>MM</td><td></td><td>Trigger single musing</td></tr><tr><td>MN#</td><td></td><td>Set minimum gap (seconds) between musings</td></tr><tr><td>MX#</td><td></td><td>Set maximum gap (seconds) between musings</td></tr><tr><td><strong>SD WAV</strong></td><td></td><td></td></tr><tr><td>CA####</td><td></td><td>Play <a href="../sd-card#undefined">WAV file</a> number <code>0000</code>-<code>9999</code> on WAV channel A</td></tr><tr><td>CB####</td><td></td><td>Play <a href="../sd-card#undefined">WAV file</a> number <code>0000</code>-<code>9999</code> on WAV channel B</td></tr><tr><td>CA####C####</td><td></td><td>Play random <a href="../sd-card#undefined">WAV file</a> between file number <code>0000</code>-<code>9999</code> and file number <code>0000</code>-<code>9999</code> on WAV channel A</td></tr><tr><td>CB####C####</td><td></td><td>Play random <a href="../sd-card#undefined">WAV file</a> between file number <code>0000</code>-<code>9999</code> and file number <code>0000</code>-<code>9999</code> on WAV channel B</td></tr><tr><td><strong>Stop</strong></td><td></td><td></td></tr><tr><td>PSV</td><td></td><td>Stop vocalizer immediately</td></tr><tr><td>PSG</td><td></td><td>Stop vocalizer gracefully (will continue to play until next phoneme on which it is gramatically correct to end a sentence)</td></tr><tr><td>PSA</td><td></td><td>Stop WAV channel A immediately</td></tr><tr><td>PSB</td><td></td><td>Stop WAV channel B immediately</td></tr><tr><td><strong>Volume</strong></td><td></td><td></td></tr><tr><td>PVV#</td><td></td><td>Set vocalizer volume <code>0</code>-<code>100</code> (†)</td></tr><tr><td>PVA#</td><td></td><td>Set WAV channel A volume <code>0</code>-<code>100</code> (†)</td></tr><tr><td>PVB#</td><td></td><td>Set WAV channel B volume <code>0</code>-<code>100</code> (†)</td></tr><tr><td><strong>Override</strong></td><td></td><td></td></tr><tr><td>OA0</td><td></td><td>Disable <a href="../../../features/speech#improvisational-vs-canonical-mode">Canonical</a> mode and enable <a href="../../../features/speech#improvisational-vs-canonical-mode">Improvisational</a> mode (*)</td></tr><tr><td>OA1</td><td></td><td>Enable <a href="../../../features/speech#improvisational-vs-canonical-mode">Canonical</a> mode and disable <a href="../../../features/speech#improvisational-vs-canonical-mode">Improvisational</a> mode (*)</td></tr><tr><td>O1</td><td></td><td>Enable <a href="../../../features/emotions#personality-chip-override">Personality Chip Override</a> (*)</td></tr><tr><td>O0</td><td></td><td>Disable <a href="../../../features/emotions#personality-chip-override">Personality Chip Override</a> (*)</td></tr><tr><td>OR</td><td></td><td>Reset all <a href="../../features/emotions">emotions</a> to 0</td></tr><tr><td>OH#</td><td></td><td>Set Happy <a href="../../features/emotions">emotion</a> to <code>0</code>-<code>100</code></td></tr><tr><td>OS#</td><td></td><td>Set Sad <a href="../../features/emotions">emotion</a> to <code>0</code>-<code>100</code></td></tr><tr><td>OM#</td><td></td><td>Set Mad <a href="../../features/emotions">emotion</a> to <code>0</code>-<code>100</code></td></tr><tr><td>OC#</td><td></td><td>Set Scared <a href="../../features/emotions">emotion</a> to <code>0</code>-<code>100</code></td></tr><tr><td><strong>Record</strong></td><td></td><td>---</td></tr><tr><td>RRP#</td><td></td><td>Play from <a href="../../features/memory">memory</a> slot <code>0</code>-<code>9</code></td></tr><tr><td>RRS#</td><td></td><td>Save to <a href="../../features/memory">memory</a> slot <code>0</code>-<code>9</code> (*)</td></tr><tr><td>R0</td><td></td><td>Set <a href="broken-reference">strict memory playback</a> (*)</td></tr><tr><td>R1</td><td></td><td>Set <a href="broken-reference">organic memory playback</a> (*)</td></tr><tr><td><strong>Query</strong></td><td></td><td></td></tr><tr><td>QEH</td><td><code>&#x3C;QEH,#></code></td><td>Returns the Happy <a href="../../features/emotions">emotion</a> as an integer from <code>0</code>-<code>100</code></td></tr><tr><td>QES</td><td><code>&#x3C;QES,#></code></td><td>Returns the Sad <a href="../../features/emotions">emotion</a> as an integer from <code>0</code>-<code>100</code></td></tr><tr><td>QEM</td><td><code>&#x3C;QEM,#></code></td><td>Returns the Angry <a href="../../features/emotions">emotion</a> as an integer from <code>0</code>-<code>100</code></td></tr><tr><td>QEC</td><td><code>&#x3C;QEC,#></code></td><td>Returns the Scared <a href="../../features/emotions">emotion</a> as an integer from <code>0</code>-<code>100</code></td></tr><tr><td>QE</td><td><code>&#x3C;QE,#,#,#,#></code></td><td>Returns the value of each <a href="../../features/emotions">emotion</a> as an integer from <code>0</code>-<code>100</code> in the following order: happy,sad,mad,scared</td></tr><tr><td>QO</td><td><code>&#x3C;QO,#></code></td><td>Returns <code>0</code> if <a href="broken-reference">personality chip override</a> is disabled, or <code>1</code> if enabled</td></tr><tr><td>QM</td><td><code>&#x3C;QM,#></code></td><td>Returns <code>0</code> if <a href="../../features/muse">muse</a> is disabled, or <code>1</code> if  enabled</td></tr><tr><td>QF</td><td><code>&#x3C;QF,#></code></td><td>Returns an integer from <code>0</code>-<code>9999</code> representing the total number of <a href="../sd-card#undefined">WAV files</a> detected on the SD</td></tr><tr><td>QT</td><td><code>&#x3C;QT,#></code></td><td>Returns a float representing the total original duration of the currently playing vocalization, or <code>0</code> if no vocalization is currently playing</td></tr><tr><td>QPV</td><td><code>&#x3C;QPV,#></code></td><td>Returns <code>0</code> if the vocalizer is not currently vocalizing, or <code>1</code> if it is</td></tr><tr><td>QPA</td><td><code>&#x3C;QPA,#></code></td><td>Returns an integer from <code>0</code>-<code>9999</code> representing the <a href="../sd-card#undefined">WAV file</a> number currently playing on WAV channel A (or <code>-1</code> if nothing is playing)</td></tr><tr><td>QPB</td><td><code>&#x3C;QPB,#></code></td><td>Returns an integer from <code>0</code>-<code>9999</code> representing the <a href="../sd-card#undefined">WAV file</a> number currently playing on WAV channel B (or <code>-1</code> if nothing is playing)</td></tr><tr><td>QVV</td><td><code>&#x3C;QVV,#></code></td><td>Returns an integer from <code>0</code>-<code>100</code> representing the vocalizer volume</td></tr><tr><td>QVA</td><td><code>&#x3C;QVA,#></code></td><td>Returns an integer from <code>0</code>-<code>100</code> representing WAV channel A volume</td></tr><tr><td>QVB</td><td><code>&#x3C;QVB,#></code></td><td>Returns an integer from <code>0</code>-<code>100</code> representing WAV channel B volume</td></tr><tr><td>QD</td><td><code>&#x3C;QD,#,...,#></code></td><td>Returns key metrics. Comma separated list with the results of these commands: QEH,QES,QEM,QEC,QO,QM,QF,QT,QPV,QPA,QPB</td></tr></tbody></table>

(\*) = Persistently stored in [R2D2Vocalizer.txt](https://docs.humancyborgrelations.com/r2d2/platforms/embedded/sd-card/r2d2vocalizer.txt)

(†) = Persistently stored in [Config.txt](https://docs.humancyborgrelations.com/r2d2/platforms/embedded/sd-card/config.txt)

## Command Examples

`<SH1>` — Trigger extreme happy vocalization.

`<CA0025>` — Play SD WAV file number 0025 on WAV channel A.

`<CB0003C0185>` — Play random SD WAV File between file number 0003 and file number 0185 on WAV channel B.

`<QEH>` — Query Happy emotion. Receive: `<QEH,12>`

`<QE>` — Query all emotions. Receive: `<QE,4,28,100,68>`

*Multiple commands can be chained:*

`<SH1,M1>` — Trigger extreme happy vocalization and enable muse.

`<SH1><M1>` — Alternate syntax for same command as above.

`<SM0,QM>` — Trigger mild angry vocalization and query muse state. Receive: `<QM0>`<br>
