Home

C++ API Library

Please Read This First for R2 Vocalizer -> Human-Cyborg Relations R2-D2 Vocalizer

Please Read This First for Astromech Vocalizer -> Human-Cyborg Relations Astromech Vocalizer

Note: This WIKI is not for the Human-Cyborg Relations R2-D2 Vocalizer. This WIKI is about the C++ API Library and how it is used to interface and control the vocaliser using a micro-controller such as Arduino or ESP

The Hardware

This library is to be used for controlling the Human-Cyborg Relations R2-D2 Vocaliser Teensy Port and requires a specific hardware setup to interface to.

You will need:

1. A control board such as an Arduino Uno/Mega or Nano. Other microcontrollers are possible but untested at this time.
2. A HCR Teensy Setup as outlined here: https://humancyborgrelations.gitbook.io/r2d2/platforms/teensy/supplies
3. Either a connection via Serial or I2C between the boards

---

The Software

To setup the HCR Teensy, please follow these instructions: https://humancyborgrelations.gitbook.io/r2d2/platforms/teensy/software-setup

SD Card Setup

The SD Card in the Teensy Vocaliser has 2 text files which contains a lot of information HCR uses to setup and store its configuration.

Please see SD Card Setup for more details as this API command library will need the correct connection configuration enabled on the Teensy Vocaliser

---

Command Library

Structure

The C++/Arduino Code structure is within the format below. It is important that commands are issued before the update and queries are run after as the cycle of the HCR loop is Command > Update/Execute > Respond

// Initialize Vocalizer

void setup() {
  // Setup Vocalizer Parameters
}

void loop() {
  // Issue Commands to Vocalizer
  // Update Vocaliser
  // Get Responses from Vocalizer
}

Initilise

HCRVocalizer

HCRVocalizer is the primary class of the API for your client device. In this demo we call it "HCR" but use what is best fit for your code.

There are a number of options to declare but the syntax is as follows for each of the possible connections supported:

//  Connection via I2C
HCRVocalizer HCR(0x10,Wire); // I2C (HCR I2C Address, Wire(, clock rate))

// Connection via a Specic Serial Port e.g. Serial, Serial1, Serial2...
HCRVocalizer HCR(&Serial,9600); // Serial (Stream Port, baud rate)

// Connection via a Serial Port on certain pins
HCRVocalizer HCR(16,17,9600); // Serial (RX Pin, TX Pin, baud rate)

The I2C Address is used for identifying the specific device on a connection BUS. In I2C this is important as it will only send commands to that specific device.

The &Port in the serial definition is important to correctly pass the serial port to the function for setup.

The clock/baud rate is the speed of the port when connecting to other devices

---

Setup

Begin()

Used in the setup function to create the needed connections

class Setup() {
    HCR.begin();
}

The begin() has an optional parameter to declare the periodic refresh sync between controller and Teensy Vocaliser. This value is in milliseconds.

During Setup, you can also prepare the first package of commands to be sent in the first send such as emotional state overrides, musing etc.

Setup Examples

class Setup() {
    HCR.begin(125); // Refresh Speed (Default:125 ms)
    HCR.OverrideEmotions(1); // Override emotions and prevent emotions normalising
    HCR.SetEmotion(HAPPY,89); // Set Happy to 89%
    HCR.SetEmotion(SAD,22); // Set Sadness to 22%
}

---

Loop

The loop with HCR has a very specific cycle of Command > Update > Respond where commands are issued to the HCR Teensy Vocaliser, it will execute and respond with a dataframe with all the current state data. This current state data is also periodically refereshed based on your initialisation parameters.

void loop() {
  // Issue Stimulation or Trigger Commands to Vocalizer
  // Update Vocaliser
  // Get Responses from Vocalizer
}

Emotion Commands

These commands can be run in setup or in a loop function.

Stimulate / Trigger

Stimulate a response from the HCR AI with either a moderate or strong response.

HCR.Stimulate(int emotion_category,int value);
HCR.Trigger(int emotion_category,int value);

Emotion Categories and strength to use:

Variable	Value
HAPPY	0
SAD	1
MAD	2
SCARED	3
EMOTE_MODERATE	0
EMOTE_STRONG	1

Happy

HCR.Stimulate(HAPPY,EMOTE_MODERATE);
// or
HCR.Stimulate(0,0);

Sad

HCR.Stimulate(SAD,EMOTE_STRONG);

Mad

HCR.Stimulate(MAD,EMOTE_MODERATE);

Scared

HCR.Stimulate(SCARED,EMOTE_MODERATE);

Overload (Electrocution)

HCR.Overload();

GetEmotion

Returns int of the emote score for HAPPY out of 100

HCR.GetEmotion(HAPPY);

Returns int of the emote score for SAD out of 100

HCR.GetEmotion(SAD);

Returns int of the emote score for MAD out of 100

HCR.GetEmotion(MAD);

Returns int of the emote score for SCARED out of 100

HCR.GetEmotion(SCARED);

SetEmotion

Sets the specific emotion score based on the integer of 0-99 Reminder that without override, the scores will normalise to 0 over time

HCR.SetEmotion(HAPPY,89);

HCR.SetEmotion(SAD,22);

HCR.SetEmotion(MAD,0);

HCR.SetEmotion(SCARED,0);

StopEmote

Stops the current Emote from playing

HCR.StopEmote();

GetDuration

Returns float of current emote duration

HCR.GetDuration();

IsPlaying

Returns a binary integer if a vocalisation is playing

HCR.IsPlaying();

When indicating a specific WAV channel, returns a binary integer if the channel is playing

HCR.IsPlaying(CH_A);

---

Overrides

OverrideEmotions

Stops the normalisation of emotional states and allows each state to remain at its current level

Enable

HCR.OverrideEmotions(1);

Disable

HCR.OverrideEmotions(0);

GetOverride

Returns integer if override is enabled

HCR.GetOverride();

ResetEmotions

Resets all emotional states to 0

HCR.ResetEmotions();

---

Musing

Trigger Muse

Trigger a random muse to play

HCR.Muse();

Muse Timers

Set Minimum and Maximum Gap Timer between Muses in seconds

e.g. Set Muse of between 5 and 50 seconds

HCR.Muse(5,50);

SetMuse

Turn on/off random periodical mumbling audio animation

Enable

HCR.SetMuse(1);

Disable

HCR.SetMuse(0);

GetMuse

Returns the binary integer state if Muse is enabled or disabled

HCR.GetMuse();

---

SDCARD AUDIO

Reminder all files must have a suffix of ..._<0000-9999>.WAV

PlayWAV

Play a WAV file from the SD from either A or B channel with either a name or the file number.

Channel	Value	Description
CH_V	0	Vocalizer Channel
CH_A	1	WAV Channel A
CH_B	2	WAV Channel B
CH_O	3	Any/All Channel

WAV Channel A with a specific file name as a string

HCR.PlayWAV(CH_A,"0000");

WAV Channel B with a file number

HCR.PlayWAV(CH_B,1);

StopWAV

Stops the WAV file being played and if it should be slowly faded out

WAV Channel A

HCR.StopWAV(CH_A,FADE);

WAV Channel B

HCR.StopWAV(CH_B);

GetWAVCount

Returns an interger of the number of compatible WAV files detected on the SD Card

HCR.GetWAVCount();

GetPlayingWAV

Returns the ID number of the WAV file playing or returns -1 if nothing is playing

WAV Channel A

HCR.GetPlayingWAV(CH_A);

WAV Channel B

HCR.GetPlayingWAV(CH_B);

---

Volume Controls

SetVolume

Sets the float volume from 0-100 of each available channel

Vocalizer Channel

HCR.SetVolume(CH_V,99);

WAV Channel A

HCR.SetVolume(CH_A,50);

WAV Channel B

HCR.SetVolume(CH_B,50);

Get Volume

Returns the volume as a float (00.00) of the channel specified

Vocalizer Channel

HCR.getVolume(CH_V);