isabella232 / snips-skill-respeaker

Official Snips Animation Feedback For Makers Kits/Dev Kits, supporting all kinds of APA102 based LED hardwares.

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

By using sam:

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.