Teddycloud ESP32 newbie documentation

Hi there,

within this post I try to make an newbie documentation for installing Teddycloud on a ESP32 Box.

:bangbang: ALWAYS READ THE OFFICIAL DOCUMENTATION FIRST :bangbang:

:small_orange_diamond: Intro

We will make use of docker in this write up and try to cover all steps needed, so people with less knowledge may be capable of getting their own private toniescloud.
In this guide we will use a Raspberry Pi OS (every other Linux distribution will be finde too and you should be able to do this on windows too)

:small_orange_diamond: Tools

For this you need a USB UART adapter, almost any adapter that can handle 3.3V should work, I tried two adapters, one wouldn’t work, the one that worked is this one:
https://www.amazon.de/gp/product/B01N9RZK6I/
(Attention USB Mini B :))

The Toniebox has a debug interface, connections for the UART have to be soldered to this, if you can’t really solder like me, the following clamp is a recommendation from the Revoxxcommunity: https://www.amazon.de/gp/product/B0BV79V2DW/
This does not fit exactly, but if you place it on the contacts at a slight angle, it works very well, a photo is attached later in the text.

:small_orange_diamond: Hardware

The first thing we have to do is unscrew the box, for this we have to unscrew the lid, if you can’t do it like the guys from Revoxx here: https://www.youtube.com/watch?v=GOZRjaEhrcQ
You can use this method: https://www.youtube.com/watch?v=eiMxkXM8YDs

Now that the box is open in front of you, you can see the contacts to which the UART must be connected in the following picture. Here you can either solder a socket, a cable or whatever the hobbyist can think of.
For the non-makers like me, the above-mentioned clamp works wonderfully.

Here you will see the clamp in action, it’s not aligned perfectlys. Try to place the pins as centrally as possible on the contacts:

:small_orange_diamond: Software

You may need to connect your Toniebox to your wifi and update its firmware. Many boxes are shipped with a production firmware only that needs to be updated, before the box works as it should.

The installation of the esptool is not absolutely necessary, as the steps for flashing and patching the image can be done in the web interface of the Teddycloud, but I always found it convenient to have the tool at hand in case the browser doesn’t really want to communicate with the UART.

git clone https://github.com/espressif/esptool
cd esptool
sudo python3 setup.py install

Now let’s get and install the teddycloud’s docker containers. The prebuild docker image can be found here: https://ghcr.io/toniebox-reverse-engineering/teddycloud:latest.
If you’re too lazy to write your own docker-compose file, Team RevvoX already got one for you, you can find this in the github repos: https://github.com/toniebox-reverse-engineering/teddycloud/tree/master/docker/docker-compose.yaml
If you use the prewritten compose file, please check the routing of port 443.
A ‘docker compose up -d’ will get your teddycloud up:

wget https://raw.githubusercontent.com/toniebox-reverse-engineering/teddycloud/master/docker/docker-compose.yaml
docker compose up -d

If you don’t expect any errors, you should now have teddycloud up and running and you now should start up Chrome and go to your new teddycloud server. You may try any other browser as well, but afaik Chrome gives you the best possible web to serial connection.

When teddycloud is running, let’s test the UART connection, to do this, connect your UART to the USB port of your computer and to the contacts on the Toniebox.
Start a serialmonitor to watch whats happening, I will use ‘screen’ for this, my USB Uart is connected to /dev/ttyUSB0. You can check which device you need, just type ‘dmesg’ into you CLI right after you connected the UART. Here you see the command and the output after starting the Box in normal mode.

screen /dev/ttyUSB0 115200

ESP-ROM:esp32s3-20210327
Build: Mar 27 2021
rst:0x1 (POWERON), boot:0x8 (SPI_FAST_FLASH_BOOT)
SPIWP:0xee
mode:DIO, clock div:1
load:0x3fcd0108,len:0x118
load:0x403b6000,len:0xb84
load:0x403ba000, len:0x2790
entry 0x403b61c0

Your output looks similar to this one? Then disconnect the box from the power supply, short the jumper J100. Thanks to Flo we have a unmodded ESP32 board here:

There will be no green light, the LED will only flash one time red, no sounds are played, the output in the serial console looks something like this:

ESP-ROM:esp32s3-20210327
Build: Mar 27 2021
rst: 0x1 (POWERON), boot: 0x0 (DOWNLOAD(USB/UARTO))
waiting for download

Now exit the serialmonitor (ctrl+a, ), switch to the web interface and click on “Read ESP”.
Back to the terminal:

docker exec -it teddycloud bash
cd /teddycloud
teddycloud ESP32CERT extract data/firmware/ESP32_<mac>.bin certs/client
mv certs/client/CLIENT.DER certs/client/client.der
mv certs/client/PRIVATE.DER certs/client/private.der
mv certs/client/CA.DER certs/client/ca.der

With teddyCloud you can also patch and write the new image with your custom CA and a DNS/IP so the box connects to teddyCloud. If you have a Fritzbox you can set it to tc.fritz.box, if not set it to the IP of teddyCloud.
For Fritzbox: You’ll just have to set the name of your server in your fritzbox to tc (Heimnetz → Netzwerk → Netzwerkverbindungen → bearbeiten).

Now reassemble your box and take a look to ‘docker logs teddycloud --follow’. You should see the box connecting and you now can have starting fun with your teddycloud.

Big thanks to Team revoxx, especially 0xdeadbee who helps out a lot.
Thanks to 3musketiere and Florian, I grabbed your images and infos as well.
To keep it short: Thanks for all the fish from: https://t.me/toniebox_reverse_engineering

:small_orange_diamond: Troubleshooting // FAQ:

:speech_balloon:Webinterface can’t connect, no output on serial console

Please recheck the connection with the UART. Be aware, most serial2usb UARTS need to swap TX/RX.
So connect Boards Tx to Rx on your UART. Rx to Tx and GND to GND.

:speech_balloon:Glibberish output on serial console, reading flash keeps terminating

Recheck the connection to the debug port on the ESP32. Especially if working with clamps take a look to the connection, is it aligned properly?

:speech_balloon:After reading flash with webinterface, I cannot reconnect to the serial and flash my patched image

Reconnect UARTS’s USB connection and reboot the box into debug mode.
Alt: use esptool to flash your patched image. For me the image is found in:
/var/lib/docker/volumes/docker_firmware/_data
The flash command reads:
esptool.py -b 921600 write_flash 0x0 patched[MACADRESS].bin

:speech_balloon:How can I update my teddcloud instance?

Navigate to the location of your docker-compose.yaml

docker compose down
docker compose pull
docker compose up -d

:speech_balloon:How can I switch to devleopment builds?

Edit the docker-compose.yaml:

version: '3'
services:
  teddycloud:
    container_name: teddycloud
    hostname: teddycloud
    image: ghcr.io/toniebox-reverse-engineering/teddycloud:develop
    ports:
    #  - 80:80 #optional
      - 443:443 #Port is needed for the connection for the box
    volumes:
      - certs:/teddycloud/certs
      - config:/teddycloud/config
      - content:/teddycloud/data/content
      - library:/teddycloud/data/library
      - firmware:/teddycloud/data/firmware
    restart: unless-stopped
volumes:
  certs:
  config:
  content:
  library:
  firmware:
5 Likes

Hope this is the right place for a hint: I soldered some Servo Cable like that onto the Jumber pads and the pads for the UART. Now I can flash the ESP by just getting the Inner part of the Box outside (1 screw), without removing the battery holder. If you do not cut them too short (like me) you can even make them accessible from the underside after only removing the bayonet fitting. But then you would need to find a way to cut and restore power :thinking:

As you usually only access the UART once, there is no need to solder a permanent wire onto it.

For the ESP32 devices, you could just solder in the 3 PIN battery socket onto the pads and solder some jumper wires onto the connector. But sure, use what you have available.

The socket is a 3 Pin JST PH with 2mm.

Here is a PCB with soldered sockets.

This reminds me to ask you to please put a vanilla ESP board in the wiki and maybe even with a marked J100 :).
You mentioned in the talk that you still have 1-2 lying around and this would maybe help others out too. With old eyes, no idea and no glasses, those jumpers are not this easy to find.

Nope, I only have one esp32 here, the others are cc3235 and cc3200

Hoping there will be a custom ESP32 Firmware, too, one day :slight_smile:

it’s in the making.

Hey @Wurst420,
thanks for the great writeup!
Two issues I see (so far):

In the step to launch teddycloud it should read:

docker-compose -f docker/docker-compose.yaml up -d

And then (maybe a personal issue): When I connect with the screen command, I only get gibberish on the command line, looks like the baud rate is wrong(?).

Thanks for your effort!

If the box boots without J100, the esp32 also prints its boot state, but the box will continue with baudrate 921600 and protobuf. Maybe thats your issue.

Hey @0xbadbee, thanks for trying to help me out. Does it mean I can just

screen /dev/ttyUSB0 921600

I don’t know what the protobuf of your answer means…

Protobuf is binary encoded data. It is the same data sent via rtnl to the cloud. So nothing really useful without an encoder for that.

When I got glibberish output only, the uart was not connected correct, after adjusting my clamp (and going to 9600 baud) it worked for me.

@0xbadbee is it this high: 921600?
Or is it a typo?

Baud means characters per second. So yes, it is pretty high.

But you are mixing this up with the dump speed in the esptool.

Understood, but how do I then get the output that @Wurst420 mentions in the newbie documentation?

With the screen command. If this doesn’t work, check your connections.

1 Like

IIRC docker-compose is deprecated

Thanks for all the great help so far, but it seems like I am too stupid to figure out how to now upload own content and assign it to a tag via the web interface. What are the steps :melting_face:

After you put a new tag onto the box there will be a new directory created. Use the teddycloud interface to upload and convert it to a taf file.
Afterwards you may have to rename the file to have no .taf ending and be the same name like the .json inside the folder where the music file was uploaded. Freshness check on the box and it should do it’s job

1 Like

Thank you for all the documentation but i am stuck at the “readESP32” step or the serial monitoring step so see if the Box booted at UART/download mode.

What is the Situation right now:

I have a Windows 11 laptop
I have the j100 jumper soldered and if i connect the Box with the charger, no led is flashing or shining on the box.
I connected the TXD RXD and GND via wire and soldering to an UART USB connector.

I do not get a connection with any method i am trying. there is simply no response. (Teddycloud web interface says can not connect)
Putty session simply says nothing on the screen

Got linux (kali) within a VMBox and tried the “screen /dev/ttyUSB0 115200” command but the terminal just did not respond after i executing the command. (I activated the USB connection within the VMBox)

What i did for troubleshooting:

Bought another UART connector (from the guide within this forum)
resoldered every connection and replaced all wires
Got myself kali to see if it was a Windows problem
Tried different combinations with attached peripherals (e.g: Ears, batterie)
Completly reseted (back to factory settings) the box and updated firmware again

I simply can not monitor or get any other response from the box via UART.

Did somebody had a similar problem?

When you look at the pinout of the image in the top post the order from left to right is TxD, RxD, GND. This is the pinout of the PCB.
You have to connect RX of your UART to TxD of the Toniebox, TX to RxD and GND to GND.
So the order of your soldered pins is RX, TX, GND

The logic behind this is: What one client transmits (TX) will the other one receive (RX)

1 Like