Official Snips Animation Feedback For Makers Kits/Dev Kits, supporting all kinds of APA102 based LED hardwares.
Branch: master
Clone or download
Latest commit 37d4cb4 Jan 28, 2019

README.md

snips-skill-respeaker

Version MIT License

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.