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 17 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.
Jump to
Jump to file
Failed to load files.
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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great idea! This makes me wonder if we should provide the sha256sum information on the install pages themselves too since we already know the checksums in advance: https://release.asteroidos.org/nightlies/beluga/MD5SUMS

(This also means that the We do not currently provide checksums for the files. claim, is incorrect 😉 )

Copy link
Member Author

@eLtMosen eLtMosen Mar 12, 2023 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a great surprise! Coool, i thought it would be complicated to add checksums so did not ask but came up with the re-download work around.
Let's keep the We do not currently... sentence until the checksums are actually shown on the website?
Making a new issue for that:
#284

eLtMosen marked this conversation as resolved.
Show resolved Hide resolved
</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. Since the watches install pages link to the nightlies currently, you likely used those. 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.
eLtMosen marked this conversation as resolved.
Show resolved Hide resolved
<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.</li>
MagneFire marked this conversation as resolved.
Show resolved Hide resolved
<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>