snips-skill-respeaker
This action code animates RGB LEDs and controls button as a human interface for Snips Voice Platform.
User are not only expected to attach a ReSpeaker Hat as the hardware, but also the customised RGB LED (APA102) strip and button are also supported.
Features
LED Animations
On idle: random led breathe in green
On listen: all leds start to blink in blue
On speak: all leds start to breathe in purple
To mute: all leds breathe once in yellow
To unmute: all leds breathe once in green
On disabled: all leds turn off
Button
Short press: start a new conversion without saying hotword
Double press: toggle the animation feedback
Long press: toggle the sound feedback
Official Hardware Support
Platforms / ReSpeakers | 2-Mic Hat | 4-Mic Hat | 6-Mic Hat | Core V2 |
---|---|---|---|---|
Raspberry Pi 0 | ||||
Raspberry Pi 3 | ||||
Raspberry Pi 3+ | ||||
ReSpeaker Core V2 |
Known Issue: the button on the ReSpeaker Core V2 is not yet supported due to its special accessing design
If you would like to customise the hardware, please refer to Build Your Own Hardware section.
Installation
sam
:
By using Beware that
sam
only supports Raspberry Pi platform. For other platforms, please refer to manual installation guide.
sam install actions -g https://github.com/snipsco/snips-skill-respeaker.git
To be able to access GPIO and SPI hardware, _snips-skills
user need to be appended with spi
, gpio
, audio
groups. Run the following command on your snips device:
sudo usermod -a -G spi,gpio,audio _snips-skills
Manually:
If there is no
snips-skill-server
installed yet, please run the following command:
sudo apt-get install snips-skill-server
Firstly, add your current user to the snips-skills-admin
group:
sudo usermod -a -G snips-skills-admin $USER
Secondly, add _snips-skills
user to the spi
, gpio
, audio
groups:
sudo usermod -a -G spi,gpio,audio _snips-skills
Finally, clone the repository and manually run setup.sh
:
git clone https://github.com/snipsco/snips-skill-respeaker.git
cp -r snips-skill-respeaker /var/lib/snips/skills/
cd /var/lib/snips/skills/snips-skill-respeaker
./setup.sh
Configurations
All the configuration options are written in config.ini
file. There are three sections used to represent three different kinds of parameters. Please refer to your actual usage to modify.
[secret]
This section contains the options which will be asked to input from user during the installation. (Using sam)
Device Info
Config | Description | Value | Default |
---|---|---|---|
site_id |
Snips device ID | Refering to the actual snips.toml |
default |
To make satellite work correctly, please change here
MQTT
Config | Description | Value | Default |
---|---|---|---|
mqtt_host |
MQTT host name | <ip address> /<hostname> |
localhost |
mqtt_port |
MQTT port number | <mqtt port> |
1883 |
mqtt_username |
Optional - MQTT username | <mqtt username> |
null |
mqtt_password |
Optional - MQTT password | <mqtt password> |
null |
To make satellite work correctly, please change here
[global]
This section contains all the changeable options which may make the action more suit your expectation.
Hardware Info
Config | Description | Value | Default |
---|---|---|---|
model |
Hardware specification file name | Refering to the hardware_specs list | respeaker_2_mic_hat |
If you would like to use an APA102 LEDs strip or an external button, please reach here to create your own hardware configuration file.
Brightness
Config | Description | Value | Default |
---|---|---|---|
led_bri |
Max brightness of LEDs | 0 :255 |
64 |
Animation
Config | Description | Value | Default |
---|---|---|---|
on_idle |
Random LED breathe in green | true , false |
true |
on_listen |
All LEDs start to blink in blue | true , false |
true |
on_speak |
All LEDs start to breathe in purple | true , false |
true |
to_mute |
All LEDs breathe once in orange | true , false |
true |
to_unmute |
All LEDs breathe once in green | true , false |
true |
Colour
Config | Description | Value | Default |
---|---|---|---|
idle_colour |
LEDs colour while idle | red , green , blue , yellow , purple , teal , orange |
green |
listen_colour |
LEDs colour while listening | red , green , blue , yellow , purple , teal , orange |
blue |
speak_colour |
LEDs colour while speaking | red , green , blue , yellow , purple , teal , orange |
purple |
mute_colour |
LEDs colour while muting | red , green , blue , yellow , purple , teal , orange |
yellow |
unmute_colour |
LEDs colour while unmuting | red , green , blue , yellow , purple , teal , orange |
green |
Nightmode
Config | Description | Value | Default |
---|---|---|---|
nightmode |
If enable night mode | true , false |
true |
go_sleep |
The time when it sleep | HH:MM (24h) |
22:15 |
go_wake |
The time when it wake up | HH:MM (24h) |
8:35 |
To be able to use this function, please properly set your timezone
Timezone setting:
sudo raspi-config
->Localisation Options
->Change Timezone
Default feedback sound
Config | Description | Value | Default |
---|---|---|---|
feedback_sound |
If enable the feedback sound by default | true :false |
true |
[static]
This section only contains one option, config_ver
, which is used to track the config.ini
file version. You are not supposed to change this value at any time.
A general update will work basing the old config.ini
without any problem if there is no change required for adding new config options. But this also means that the config entities might be changed at some point. During the installation/updating, setup.sh
will always check if the old config.ini
file meets the latest requirement. If it doesn't, it will be overwrote by a new default config. The old config information will be dropped.
In this case, please do make sure that you have to re-modify the options' value after the installation/updating if needed.
Build Your Own Hardware
If you would like to have a customised setup, a APA102 IC based RGB LED strip will be needed. (ws2812 will be supported in the future)
Step 1
Create a file under hardware_specs
folder, name it with the custom_
as prefix and end with .json
:
cd hardware_specs
touch custom_<YOUR_HW_CONFIG_NAME>.json
Name this file in the correct way will prevent it being tracked by git
tool, so that the update will not overwrite this specification file.
Step 2
Fill this file with a json formate specification. This json file should contain the following attributes:
Specification Json
Key | Type | Value |
---|---|---|
led_num |
Integer | Number of LEDs |
spi_bus |
Integer | SPI bus number |
spi_dev |
Integer | SPI device number |
power |
Object | Optional - See below |
button |
Object | Optional - See below |
Power Specs
If your LED strip has a power control, specify the GPIO that uses.
Key | Type | Value |
---|---|---|
gpio_pin |
Integer | Number of the GPIO port |
gpio_val |
Integer | Output level, 1 for high and 0 for low |
Button Specs
If you have a button connected, specify the GPIO that uses.
You may need an external pull-up/pull-down resistor connected to your button.
Key | Type | Value |
---|---|---|
gpio_pin |
Integer | Number of the GPIO port |
gpio_val |
Integer | Active level, 1 for high and 0 for low |
If you have a 24 LED strip with a power control on GPIO5, and you would also have a button connected to GPIO17, the following is an example that you need to put to the specification file:
{
"led_num":24,
"spi_bus":0,
"spi_dev":0,
"power":{
"gpio_pin":5,
"gpio_val":1
},
"button":{
"gpio_pin":17,
"gpio_val":0
}
}
Step 3
Change the config.ini
, find the key model
, give your hardware specification file name with out .json
.
Step 4
Relaunch snips-skill-server
sudo systemctl restart snips-skill-server
Command Line Mode
If you would like to debug your hardware configuration, you can run the animation program with command line parameters. CMD input parameters will have higher priority than the parameters in the config.ini
file, the missing parameters will be fetched from the config.ini
file.
Usage: ./action-led_animation_x <options> command
Global options:
-H, --help this help
-d, --debug debug mode
-v, --verbose enable verbose mode
-V, --version print version of this program
MQTT connection options:
-h, --mqtt-host hostname of mqtt broker (default localhost)
-p, --mqtt-port port of mqtt broker (default 1883)
-P, --mqtt-pass password of mqtt broker
-U, --mqtt-user username of mqtt broker
APA102 LED options:
-N, --led-n number of leds
-D, --spi-dev spi device to use (default /dev/spidev0.0)
Snips device info:
-S, --site-id siteId to use (default default)
Enable/Disable LED feedback
Mode change follows hermes procotol.
Enable
Topic:
hermes/feedback/led/toggleOn
Payload:
Key | Type | Value |
---|---|---|
siteId | String | Site where feedback led will be toggled On |
Disable
Topic:
hermes/feedback/led/toggleOff
Payload:
Key | Type | Value |
---|---|---|
siteId | String | Site where feedback led will be toggled Off |
To Do
- Support WS281x RGB LEDs
Contributing
Please see the Contribution Guidelines.
Copyright
This library is provided by Snips as Open Source software. See LICENSE for more information.