From 289129717cace233dc8e21f2037e1a314d27b855 Mon Sep 17 00:00:00 2001 From: simonmicro Date: Sun, 18 Aug 2024 13:50:05 +0200 Subject: [PATCH] Reworked and updated troubleshooting steps Signed-off-by: simonmicro --- docs/firmware/troubleshooting.md | 47 ++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 17 deletions(-) diff --git a/docs/firmware/troubleshooting.md b/docs/firmware/troubleshooting.md index 4990a5708..6d71360f6 100644 --- a/docs/firmware/troubleshooting.md +++ b/docs/firmware/troubleshooting.md @@ -1,13 +1,38 @@ # Troubleshooting -## Always double check the cable +## Build problems +...as we have some automations setup to always test-build many different configurations, we are quite sure that the code is working out of the box. If you have problems, maybe the following hints can help you. Or you found a bug... please let us know! -We have seen a number of "charge only" cables in the community. Try to upload using a different cable. +### Fixing `fatal error: Arduino_TFT.h: No such file or directory` -## Check the driver +You did not clone the repository with the `--recursive-submodules` flag. + +!!! note "Tip" + After changing or updating/pulling a branch, run the commands notes inside the `README.md` to update the submodules and the PlatformIO packages. + +### Fixing `error: unknown type name ‘wait_queue_t’; did you mean ‘wait_event’?` + +On Fedora Silverblue 34 `make` outputs `error: unknown type name ‘wait_queue_t’; did you mean ‘wait_event’?`. +This can be fixed by using [this fork from juliagoda](https://github.com/juliagoda/CH341SER). + +### Fixing `raise UnidentifiedImageError(msg)` + +Open-Smartwatch can automatically embed assets (binary files) into the firmware. If you see this error, you may have forgotten to clone this repository with Git LFS enabled. Please see the `README.md` for instructions on how to clone the repository with Git LFS. + +## Upload problems +You compiled the firmware successfully (`Successfully created esp32 image.`), but the upload fails for some reason. Here are some common problems and solutions. + +### Always double check the USB-cable! + +We have seen a number of "charge-only" or broken cables in the community. Try to upload using a different cable. + +### Is the driver working correctly? On non-Linux machines you may need to install additional drivers, as noted in the [Getting Started](getting_started.md) guide. +!!! note "Checking the connection (Linux only)" + If you are using Linux, make sure the device `/dev/ttyUSB0` or `/dev/ttyACM0` is present when you plug in the device. If it is not, the kernel is unable to communicate with the USB-to-serial chip on the device. + ### Driver is there, but device is busy On Linux, you may need to remove the `brltty` package to free up the serial port. @@ -17,20 +42,8 @@ sudo apt-get remove brltty ``` !!! info "What is brltty?" - `brltty` is a daemon that provides access to the Linux/Unix console (text mode) for a blind person using a refreshable braille display. It is not needed for most users, but is annoyingly always claiming all available serial ports. - -## Arduino_TFT.h: No such file or directory - -You did not clone the repository with the `--recursive-submodules` flag. - -!!! note "Tip" - After changing or updating/pulling a branch, run the commands notes inside the `README.md` to update the submodules and the PlatformIO packages. + `brltty` is a daemon that provides access to the Linux/Unix console (text mode) for a blind person using a refreshable braille display. It is not needed for most users, but is annoyingly always claiming all available serial ports and therefore blocking PlatformIO communication with the device. -## Failed to connect to ESP32: Timed out waiting for packet header +### Failed to connect to ESP32: Timed out waiting for packet header You did not hold down BTN1(FLASH) and then tap the RESET button on the watch whilst PlatformIO was trying to connect. - -## Fixing `error: unknown type name ‘wait_queue_t’; did you mean ‘wait_event’?` - -On Fedora Silverblue 34 `make` outputs `error: unknown type name ‘wait_queue_t’; did you mean ‘wait_event’?`. -This can be fixed by using [this fork from juliagoda](https://github.com/juliagoda/CH341SER).