Customize the S3-BOX-3

Customize the S3-BOX-3 with your own illustrations

This tutorial will show you how to replace the Home Assistant status illustrations on the Espressif ESP32-S3-BOX-3 with your own images.

You can either prepare your own illustrations or import some from a community repository.

ESP32-S3-BOX-3 voice assistant status illustrations

The ESP32-S3-BOX-3 voice assistant has 6 illustrations to indicate its state:

Screenshot showing energy price graph. The ESP32-S3-BOX-3 states: loading, idle, listening, thinking, replying, error.

The chart shows the default illustrations. The next steps show you how to change those.

Prerequisites

Adopting the device in the ESPHome add-on

Before you can import new illustrations, you need to install the ESPHome add-on and adopt the device in the add-on.

  1. Make sure the ESP32-S3-BOX-3 is up and running and connected to your Wi-Fi.

  2. Go to Settings > Add-ons and check if you have the ESPHome add-on installed.

  3. Start the add-on and select Open web UI.

  4. In the ESPHome add-on dashboard, on the ESP32-S3-BOX-3 card, select Adopt.

    Adopt the ESP32-S3-BOX-3 in the ESPHome add-on

  5. If you like, give it a new name. Then, select Adopt.

    • Adopting an ESPHome device allows us to customize the existing software.
    • Result: The status will change to Online.
  6. Now that you have set up the ESPHome add-on, continue with one of the 2 different methods to add custom images:

Option 1: Using images from a community repository

If you want new images but don’t want to create your own, you can use images from the community. If you want to use your own images, skip this procedure and go to Option 2: Using your own images instead.

To use images from the community

  1. On the ESP32-S3-BOX-3 add-on, select edit.

    • Result: An editor opens, showing the configuration file. ESP32-S3-BOX-3 config file
  2. For inspiration, we have prepared some images for you.

  3. For this tutorial, we will use some images of Frenck.

    • Add the following lines into the substitutions block.

      substitutions:
        loading_illustration_file: https://github.com/jlpouffier/home-assistant-s3-box-community-illustrations/raw/main/frenck/illustrations/loading.png
        idle_illustration_file: https://github.com/jlpouffier/home-assistant-s3-box-community-illustrations/raw/main/frenck/illustrations/idle.png
        listening_illustration_file: https://github.com/jlpouffier/home-assistant-s3-box-community-illustrations/raw/main/frenck/illustrations/listening.png
        thinking_illustration_file: https://github.com/jlpouffier/home-assistant-s3-box-community-illustrations/raw/main/frenck/illustrations/thinking.png
        replying_illustration_file: https://github.com/jlpouffier/home-assistant-s3-box-community-illustrations/raw/main/frenck/illustrations/replying.png
        error_illustration_file: https://github.com/jlpouffier/home-assistant-s3-box-community-illustrations/raw/main/frenck/illustrations/error.png
      
  4. Save the changes and select Install:

    • Depending on your environment, the installation process can take a while. ESP32-S3-BOX-3 config file
  5. Once the installation is complete, you can see the new image on the ESP32-S3-BOX-3.

    • Now, speak a command to test the new setting. For example, OK Nabu, turn off the living room lights.

Option 2: Using your own illustrations

There are 2 parts to this:

About the image specifications

Here’s what you need to know to get the best result on your ESP32-S3-BOX-3 screen.

Using light and dark image background

In the overview diagram, you can see that the default images use different background colors. This is to make it easier to recognize a state change when you look at your screen.

In your images, you could use 2 different background colors:

  • For loading and idle: use a dark background
  • For listening, thinking, and replying: use a light background
  • For error: As you like

If your images have transparency, you can define the background color in the configuration. The procedure below shows how to change the background.

Image dimensions and file format
  • Dimensions: The screen is 320 x 240 pixels. If the image you provide is not in a 4:3 ratio, the remaining area will be filled with background color.
  • File format: PNG, JPEG, or SVG

To prepare your own images

  1. Create your own images according to the specifications defined in the section About the image specifications.
    • You could even draw your own!
    • There’s a template for it.
  2. Copy all 6 images into a folder. For example: voice_assistant_gfx.
  3. Make sure you have access to your configuration files.
  4. Copy your image folder into the configuration folder:
    • Open the config folder and open the ESPHome folder.
    • Copy your image folder in there. ESP32-S3-BOX-3 config file

To add your images to the configuration

  1. In Home Assistant, go to Settings > Add-ons > ESPHome, and Open Web UI.

  2. On the ESP32-S3-BOX-3 add-on, select edit.

    • Result: An editor opens, showing the configuration file. ESP32-S3-BOX-3 config file
  3. To add your images, add the following lines into the substitutions block.

    substitutions:
      loading_illustration_file: voice_assistant_gfx/loading.png
      idle_illustration_file: voice_assistant_gfx/idle.png
      listening_illustration_file: voice_assistant_gfx/listening.png
      thinking_illustration_file: voice_assistant_gfx/thinking.png
      replying_illustration_file: voice_assistant_gfx/replying.png
      error_illustration_file: voice_assistant_gfx/error.png
    
  4. If you used transparency in your images and you want to change the background color, add the following lines into the substitutions block:

    • The 000000 stands for black, FFFFFF stands for white in hexadecimal color code.

    • If you want to use different colors, replace the corresponding color code.

    • To find the color code, you can use a tool like the Google color picker.

      substitutions:
        ...
        loading_illustration_background_color: '000000'
        idle_illustration_background_color: '000000'
        listening_illustration_background_color: 'FFFFFF'
        thinking_illustration_background_color: 'FFFFFF'
        replying_illustration_background_color: 'FFFFFF'
        error_illustration_background_color: '000000'
      
  5. Save the changes and select Install. ESP32-S3-BOX-3 config file

  6. Save the changes.

    • Depending on your environment, the installation process can take a while.
  7. Once the installation is complete, you can see the new image on the S3-BOX.

    • Now, speak a command to test the new setting. For example, OK Nabu, turn on the light.

To draw your own images

  1. We prepared a template for you to draw your own status images. ESP32-S3-BOX-3 config file

  2. Download the file and start drawing!

    Draw Assist
  3. When you are done:

Customizing on-device wake words (microWakeWord)

You can change the on-device wake word (microWakeWord) that is used on your S3-BOX-3.

Prerequisites

  • Home Assistant 2024.2, installed with the Home Assistant Operating System. If you do not have Home Assistant installed yet, refer to the installation page for instructions.
  • Successfully installed ESPHome on the S3-BOX-3
  • ESPHome 2024.2 or later
  • Home Assistant server with at least 2 GB of RAM free
    • The firmware needs to be compiled on the server before it is installed on the S3-BOX-3.
    • Compiling requires a bit of RAM.
  • On-device wake word installed on your S3-BOX-3.

(It also works on the (now discontinued) S3-BOX and S3-BOX-Lite)

To customize the S3-BOX-3 with on-device wake words

  1. If you haven’t done so already, adopt the device in the ESPHome add-on.

  2. In Home Assistant, go to Settings > Add-ons > ESPHome, and Open Web UI.

  3. On the ESP32-S3-BOX-3 entry, select edit.

    • Result: An editor opens, showing the configuration file. ESP32-S3-BOX-3 config file
  4. To change the wake word, add the following line into the substitutions block.

    • Instead of okay_nabu, you can also use alexa or hey_jarvis.

      substitutions:
        ...
        micro_wake_word_model: hey_jarvis
      
  5. Save the changes and in the top right corner, select Install.

    • Depending on your environment, the installation process can take a while.
    • On Home Assistant Green, for example, it takes about 45 minutes.
  6. Select the ESPHome integration. Under Devices, you should see the ESP32-S3-BOX listed.

    • On the ESP32-S3-BOX-3 entry, select Device to open the device page.

    • Under Wake word engine location, select On device.

      ESP32-S3-BOX-3 on device wake word processing

  7. Now, speak a command to test the new setting. For example, Hey Jarvis, turn on the light.