Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Extend troubleshooting guide according to findings during matrix support chat #283

Merged
merged 20 commits into from
Mar 13, 2023
Merged

Extend troubleshooting guide according to findings during matrix support chat #283

Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
111b54f
Devide guide into boot and flashing problems and extend it according …
eLtMosen Mar 11, 2023
f692af7
Fix typos and ADB lowercases
eLtMosen Mar 11, 2023
b8a3352
Add USB 3.0 advise
eLtMosen Mar 11, 2023
7529cd5
Add ADB works but fastboot not advise
eLtMosen Mar 11, 2023
ea9fd35
Correct install page to install section
eLtMosen Mar 11, 2023
e1c7032
Implement dodoradio remark - Repeat the flash process
eLtMosen Mar 12, 2023
49a66ff
Fix dodoradio spotted typos
eLtMosen Mar 12, 2023
91668f1
Implement dodoradio remark - Boot gets stuck...
eLtMosen Mar 12, 2023
f794935
Implement dodoradio remark - Log collection
eLtMosen Mar 12, 2023
5c3a13f
Implement dodoradio remark - Glued backplates ...
eLtMosen Mar 12, 2023
c1ab29c
Implement dodoradio remark - Linux USB stick ...
eLtMosen Mar 12, 2023
f5d8e42
Fix double watch use in one sentence
eLtMosen Mar 12, 2023
e26132b
Improve textflow in worn batteries section using line breaks
eLtMosen Mar 12, 2023
792186e
Streamline fastboot fails with error text
eLtMosen Mar 12, 2023
f73c275
Streamline Watch is not detected section
eLtMosen Mar 12, 2023
0b5ca10
Add checksum hint to repeat the flash process section
eLtMosen Mar 12, 2023
a132b69
Fix beroset spotted typo - ductape
eLtMosen Mar 12, 2023
d61655d
Fix magenfire spotted leftover dot
eLtMosen Mar 12, 2023
ecd6030
Implement magnefire remark - You are likely using a nightly ...
eLtMosen Mar 12, 2023
870a2e3
Implement magnefire remark - Add android-udev-rules official repo ...
eLtMosen Mar 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 43 additions & 21 deletions templates/includes/install-problems.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,50 @@
<div id="InstallTroubleshooting" class="page-header">
<h1>Installation Troubleshooting</h1>
</div>

<h2>Boot problems</h2>
<div class="callout">
<h4>Commands fail or stop during the ~5 minute flashing process</h4>
Smartwatches are prone to lose a proper connection to their cradle over time due to sweat corroding the watch pins. This is a particularly a regular problem with dory (LG G Watch). Cleaning the pins with isopropyl alcohol or even carefully sanding them (e.g. with a nailfile) can restore a reliable connection.
<h3>Bootloop of any kind or stuck boot process</h3>
Don't panic. None of the commands we advised you to use can damage or brick your watch permanently.<br>
You can always go back to the fastboot bootloader menu, by using the <a href="https://asteroidos.org/wiki/useful-commands/#boot-to-fastboot-bootloader-menu">manual finger combos for your watch</a>.
<ul>
<li><h4>Verify that you used the correct image files</h4>Some devices like the Asus Zenwatch 2, the Fossil Gen4 models and the MTK6580 watches have more than one system image supplied, for different variants with slightly different hardware. Most watches have a graphical fastboot menu that shows the correct codename for the watch. Others need to be identified using the hardware differences noted above in the install section.</li>
<li><h4>Clean your watch and charger contacts</h4>Even in case the fastboot flash process succeeds with no errors, it can still silently fail due to connection problems caused by dirty contacts. Clean the pins and pads with isopropyl alcohol. Ideally using that old toothbrush you keep around for electronics cleaning or a microfiber cloth. Carefully sanding the contacts (e.g. with a nailfile) can help in case of obvious corrosion.</li>
<li><h4>Ensure a stable USB connection</h4>Put the watch and your computer on the same flat surface. Try to not move the cable connecting your computer and the watch during the whole flashing process. In case of worn or corroded contacts and pogo-pins that lost their springiness, it might be useful to attach the watch to its cradle or charging cable using duct tape or rubber bands.</li>
<li><h4>Repeat the flash process</h4>Some users have reported needing up to five flashing attempts for a successful result.<br>There is a small chance that the image files were corrupted during download. We do not currently provide checksums for the files. However, if you download the files again under a different filename and then compare them with <code>sha256sum filename</code>, the checksums must match.</li>
</ul>
<h3>Boot gets stuck even after repeated reflash</h3>
Congratulations, you might have found a new issue for us to solve. While this should not happen with stable builds, the nightlies are advancing quickly, and are not tested on all watches. You are likely using a nightly build, as the installation pages currently link to it. You can try again and <a href="https://release.asteroidos.org/">install a stable build when available</a>.<br>To help us solve the problem, you could try to collect logs. It is possible that the watch does not show a UI but is already accessible using <code>ssh ceres@192.168.2.15</code> or <code>adb shell</code> in the state the boot process stops. In case SSH connection works, try the following commands to write logs to local .txt files.
<ul>
<li><code>ssh root@192.168.2.15 "journalctl" > journal-watch.txt</code></li>
<li><code>ssh root@192.168.2.15 "/system/bin/logcat" > logcat-watch.txt</code></li>
</ul>
or, if your watch presents an ADB interface, use the following commands:
<ul>
<li><code>adb shell journalctl > journal-watch.txt</code></li>
<li><code>adb shell "/system/bin/logcat" > logcat-watch.txt</code></li>
</ul>
In case no connection is available, it is still interesting to see if the watch leaves any traces in your local dmesg. Try to spot USB related messages in <code>sudo dmesg -w</code> while the watch is connected and booting. Record the log using the <code>sudo dmesg > dmesg-local.txt</code> command.<br>
You can share those logs in a new <a href="https://github.com/AsteroidOS/meta-smartwatch/issues">Github issue</a> tagged with the watch codename. For support chat, you are invited to <a href="https://matrix.to/#/#Asteroid:matrix.org">join our Matrix channel</a>.
<h3>Watch only boots when powered via USB, but shuts off when booted while worn</h3>
This is a clear sign of a worn battery that will soon fail. Maybe you should replace it.<br>The boot process of AsteroidOS uses all cores of a watch to ensure a fast startup. This leads to power spikes during the boot process, which can completely shut down watches with worn out batteries. It has been observed that WearOS can still boot on watches with worn out batteries, but AsteroidOS cannot, depending on the progress of battery wear. However, AsteroidOS can usually still provide a useful 10-20 hours of uptime when the watch is worn once booted while powered up.<br>Batteries are relatively easy to replace on watches with screwed down backs. Glued back plates usually require creative solutions involving hair driers.
<h3>Watch successfully boots into the AsteroidOS user interface, but immediately reboots</h3>
This is a known behavior when the battery charge is very low. The watch usually recovers from this condition by simply boot cycling for some time. All watches also charge in fastboot or recovery mode. Letting the watch dwell on the fastboot or recovery menu screen for some time should fix the problem even faster.
</div>

<h2>Flashing problems</h2>
<div class="callout">
<h4>Flash was successful with fastboot throwing no errors, but watch does not boot</h4>
The flashing process can silently fail due to an unstable connection. Make sure you cleaned the contacts on the cradle and the watch. Redo the flashing process up to four times. On watches with especially bad connection, it can help to fixated the watch to the cradle using ductape or rubber bands.
</div>

<div class="callout">
<h4>My fastboot command displays "invalid sparse file format at header magic" when starting to flash the device</h4>
This is not a fatal error and can safely be ignored.
</div>

<div class="callout">
<h4>My fastboot command crashes or hangs at "invalid sparse file format at header magi" (with a missing "c" in magic)</h4>
This error occurs when using deprecated fastboot and ADB commands on Windows systems. If you already had those commands installed and skipped downloading our <a href="https://release.asteroidos.org/tools/adb_1_0_39+fastboot+ext2simg.zip">supplied zip file</a>, please install those commands instead.
</div>

<div class="callout">
<h4>My Asus Zenwatch 2 flashed successfully but does not boot</h4>
There are two versions of the Asus Zenwatch 2, codenamed Sparrow and Wren. Their images are not interchangeable. Please ensure you are using the right files.
<h3>Watch is not detected and all fastboot commands fail</h3>
<ul>
<li><h4>When using Linux,</h4> try prepending <code>sudo</code> to the commands to execute them with root privileges. If that works, you are missing UDEV rules for Android devices that would allow your user to execute the commands. Many package managers provide the <code>android-udev-rules</code>, which avoids the need to manually set up these UDEV rules. If the package is not available on your system, you can follow <a href="https://github.com/M0Rf30/android-udev-rules">the instructions at the official android-udev-rules repository</a>.</li>
<li><h4>On Windows systems,</h4> this usually happens due to driver issues. If you have installed an Android USB driver other than the official Google USB driver that we link to in the installation fields above, please remove it. Then reinstall the Google USB driver or update it by installing a possibly newer version.<br>We find that the Linux fastboot drivers are more reliable. It is very easy to create a bootable live Linux USB stick, for example, following <a href="https://askubuntu.com/questions/1300454/easy-full-install-usb-that-boots-both-bios-and-uefi">these instructions at askubuntu.com</a>, and then follow the above Linux installation commands after booting the live Linux USB stick.</li>
<li><h4>USB 3.0 ports</h4></li>
have caused all kinds of random and hard to track problems for many projects using ADB and fastboot. If your ADB and fastboot still can't connect after following the steps above, it might be worth switching to a USB 2.0 port. If your shiny new computer no longer has such a port, a cheap USB 2.0 HUB may help.
</ul>
<h3>ADB connection works, but fastboot does not?</h3>
The <code>fastboot oem unlock</code> command not working even though the watch could be booted into fastboot mode using <code>adb reboot bootloader</code> is a known issue on windows systems. It is caused by using a watch manufacturer USB driver with missing fastboot support. Try removing that one and install the <a href="https://developer.android.com/studio/run/win-usb">offical Google USB driver</a> we linked above in the install section.
<h3>Fastboot command stops with error during the ~5 minute flashing process</h3>
Smartwatches are prone to lose a proper connection to their cradle over time due to sweat corroding the watch pins.<br>Clean the pins and pads with isopropyl alcohol and repeat the flashing process.<br>Try to ensure a stable USB connection by putting the watch and your computer on the same flat surface. Try to not move the cable connecting your computer and the watch during the whole flashing process. In case of worn or corroded contacts and pogo-pins that lost their springiness, it might be useful to attach the watch to its cradle or charging cable using duct tape or rubber bands.
<h3>Fastboot command displays "invalid sparse file format at header magic" when starting to flash the device</h3>
This is not a fatal error and can safely be ignored. Fastboot expects images to be in sparse format. When a raw image is supplied like in case of most of the AsteroidOS watches, fastboot converts it to sparse and shows above message.
<h3>Fastboot command crashes or hangs at "invalid sparse file format at header magi" (explicitly missing the "c" in magic)</h3>
This error occurs when using deprecated fastboot and ADB versions on Windows systems. If you already had adb.exe and fastboot.exe installed and skipped downloading our <a href="https://release.asteroidos.org/tools/adb_1_0_39+fastboot+ext2simg.zip">supplied ZIP file</a>, please install and try those commands instead. Another reliable source for updated windows ADB and fastboot versions is the <a href="https://dl.google.com/android/repository/platform-tools-latest-windows.zip">official Google platform tools ZIP file</a>.
</div>