AsteroidOS - User contributions [en]

Synchronization Clients

2024-11-28T18:41:58Z

Jmlich: Amazfish on SailfishOS and Amazfish on Desktop with flatpak

AsteroidOS watches can be synchronized with a variety of devices given that they install a "synchronization client". This page lists all the known synchronization clients by platform.

= AsteroidOSSync Android application =
An official synchronization application for Android phones named AsteroidOSSync is available to [https://f-droid.org/packages/org.asteroidos.sync download on F-Droid].

This app currently offers the best experience possible with AsteroidOS.

= Gadgetbridge Android application =
Gadgetbridge support for AsteroidOS watches has been added, thanks to [https://codeberg.org/Freeyourgadget/Gadgetbridge/pulls/3013 community contribution] to the [https://codeberg.org/Freeyourgadget/Gadgetbridge/ Gadgetbridge project]. [https://f-droid.org/packages/nodomain.freeyourgadget.gadgetbridge/ Get Gadgetbridge on F-Droid].

The AsteroidOS Gadgetbridge integration is considered to be in initial stage. Nearly all features provided by AsteroidOSSync are supported. Only the remote volume control and screenshot functions are missing.

= iOS application =
There is currently no application available for iOS phones to synchronize with AsteroidOS watches. As far as we know, there hasn't been any development done on such an app yet.

However, if the watch is paired with an iOS device, AsteroidOS is capable of displaying notifications from the phone. Pairing can only done using 3rd party BLE scanner/communication apps like [https://apps.apple.com/gb/app/nrf-connect-for-mobile/id1054362403 nRF Connect] as BLE-only devices do not show up in iOS Bluetooth settings. Specific functionality like syncing time or weather forecast are however not supported!

= Ubuntu Touch/UBPorts application =
To synchronize your AsteroidOS watch to devices running Ubuntu Touch's current Focal (20.04) version, install the Amazfish app from the Ubports Open Store at https://open-store.io/app/uk.co.piggz.amazfish

The Amazfish app is receiving active development, and issues can be posted at https://github.com/piggz/harbour-amazfish/issues

For devices still running the previous discontinued Xenial (16.04) version of Ubuntu Touch, you can install the Telescope synchronization app from https://open-store.io/app/telescope.asteroidos

It appears that the Telescope app is no longer maintained, but issues can be posted at https://github.com/AsteroidOS/telescope/issues

= SailfishOS application =
An official synchronization app for SailfishOS named [https://github.com/AsteroidOS/starship Starship] has been written using [[#Library | libasteroid]]. However, it is not in a usable state yet.

[https://sailfishos-chum.github.io/apps/harbour-amazfish/ Amazfish] can be installed from chum repository.

= Desktop apps =
A community member created a desktop Linux synchronization app named [https://github.com/atx/AsteroidOSLinux AsteroidOSLinux]. It is written in Python and offers some basic scripting capabilities for AsteroidOS synchronization. The code is written in a way that makes it very easily extendable for your own usages.

A demo of the [[#Library | libasteroid]] usage named [https://github.com/AsteroidOS/asteroid-ctrl asteroid-ctrl] is also available as a C++-written CLI application. This app is cross-platform and doesn't do much on its own but can also be extended for your own usages.

[https://flathub.org/apps/uk.co.piggz.amazfish Amazfish] with kirigami flavor can be installed from flathub and used on Desktop.

= Library =
A library named [https://github.com/AsteroidOS/libasteroid libasteroid] encapsulates the Bluetooth Low Energy profiles of AsteroidOS in a simple API. It is written in C++ using QtBluetooth and is then [https://doc.qt.io/qt-5.10/qtbluetooth-index.html cross-platform]. Its code can be used as a reference implementation for other clients development or as a 3rd party library.

= New synchronization clients =

We would warmly welcome any community members interested in writing a new synchronization app to read the [[BLE profiles]] documentation and get in touch with us via our [https://matrix.to/#/#Asteroid:matrix.org Matrix channel].

BLE profiles

2024-02-12T16:50:23Z

Jmlich: Apple Notification Center Service - h2 -> h1

[[Category:Developers]]
In order to provide data synchronization capabilities between a watch and another device (typically a phone but that could also be a computer), AsteroidOS defines a variety of Bluetooth Low Energy profiles. This page tries to document those profiles so that developers can implement new synchronization apps.

[https://learn.adafruit.com/introduction-to-bluetooth-low-energy/gatt#services-and-characteristics Basic knowledge of BLE] is useful to understand this page. In this page, the ''server parts'' refer to the side of the protocol implemented by [https://github.com/AsteroidOS/asteroid-btsyncd asteroid-btsyncd] on the watch. The ''client parts'' refer to what's implemented by external apps such as [https://github.com/AsteroidOS/AsteroidOSSync/ AsteroidOSSync].

=Advertisement=

Clients can distinguish an AsteroidOS watch from another BLE device by diving into advertisement payloads. AsteroidOS advertises the following service UUID: '''00000000-0000-0000-0000-00a57e401d05'''. This information can be filtered when scanning surrounding devices.

=Battery Profile=

Clients can read an Asteroid watch's battery level using the BLE battery profile. This profile is a standard [https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.service.battery_service.xml defined by the Bluetooth Consortium] very well documented and implemented by many other devices.

==Battery Service (UUID: 0000180F-0000-1000-8000-00805f9b34fb)==
'''Battery Level Characteristic (UUID: 00002a19-0000-1000-8000-00805f9b34fb)'''

This characteristic can be read or used to be notified of a battery level change. The notified and read values consist of one byte between 0 and 100 representing the current battery level.

=Media Profile=

Apps on an asteroid watch can control client's media playback capabilities (for example with the asteroid-music) using the Media profile. This profile is custom and functions as below:

==Media Service (UUID: 00007071-0000-0000-0000-00A57E401D05)==
'''Title Characteristic (UUID: 00007001-0000-0000-0000-00A57E401D05)'''

This characteristic can be written by the client to set the name of the media that is currently being played. Set to "" if no media is played. Values should be UTF-8 strings.

'''Album Characteristic (UUID: 00007002-0000-0000-0000-00A57E401D05)'''

This characteristic can be written by the client to set the name of the album that is currently being played. Set to "" if no media is played. Values should be UTF-8 strings.

'''Artist Characteristic (UUID: 00007003-0000-0000-0000-00A57E401D05)'''

This characteristic can be written by the client to set the name of the artist that is currently being played. Set to "" if no media is played. Values should be UTF-8 strings.

'''Playing Characteristic (UUID: 00007004-0000-0000-0000-00A57E401D05)'''

This characteristic can be written by the client to set the state of the media currently being played. Possible values can be: one byte set to 1 if the media is being played or one byte set to 0 if the media is paused.

'''Command Characteristic (UUID: 00007005-0000-0000-0000-00A57E401D05)'''

This characteristic can be used by the client to be notified of a command being sent by the server. Possible events are signaled with one bytes between:

*'''0x0''': ''Previous'' (the client is expected to change media and update the writable characteristics)
*'''0x1''': ''Next'' (the client is expected to change media and update the writable characteristics)
*'''0x2''': ''Play'' (the client is expected to play the current media and update the playing characteristics according to the new state)
*'''0x3''': ''Pause'' (the client is expected to pause the current media and update the playing characteristics according to the new state)
*'''0x4''': ''Volume'' (the client is expected to change the volume to a supplied target volume and then update the Volume characteristic)

'''Volume Characteristic (UUID: 00007006-0000-0000-0000-00A57E401D05)'''

This characteristic can be written by the client to set the volume of the current media session. Supported value range is 0-100.

=Notification Profile=

Clients can create notifications on the watch side by using the Notification Profile. This profile is typically used to synchronize notifications from a phone to a watch or to send special alerts such as AsteroidOSSync's "Find my watch" feature.

==Notification Service (UUID: 00009071-0000-0000-0000-00A57E401D05)==
'''Notification Update Characteristic (UUID: 00009001-0000-0000-0000-00A57E401D05)'''
This characteristic can be written to send notifications-related commands to the watch. Commands are formated as UTF-8 strings containing an XML tree. The root element can be:

*'''insert''': to be used when the client wants to add or modify a notification on the watch side. In that case, it can contain the following sub-elements:
**''pn'': (Package name) currently ignored, should be used to identify the Android application at the origin of this notification. This field can safely be ignored by other platforms.
**''id'': (Identifier) unsigned integer freely assigned by the client to identify a notification. If the server doesn't know any notifications with this ID yet, a notification will be created. If the server already knows a notification attached to this ID, this notification will be updated according to the other insert's sub-elements.
**''an'': (Application Name) used by the watch's UI to show a human readable name of the application at the origin of this notification.
**''ai'': (Application Icon) used by the watch's UI to assign an icon to this notification. Icons should be designated by their ion-icons identifier. The complete list of supported icons can be found [https://github.com/AsteroidOS/asteroid-icons-ion here]
**''su'': (Summary) used by the watch's UI to show a title to this notification. This field is usually kept short and can be anything that should be seen first in a notification.
**''bo'': (Body) used by the watch's UI to show the content of this notification. This field should be an arbitrarily long text to be read by the user on the watch.
**''vb'': (Vibrate) specifies how the watch should notify the user of this notification. Possible values are
***''strong'' Makes the watch use a strong vibration with sound when possible when this notification is received. (This is also the default behavior if no vb element or an incorrect value is received)
***''normal'' Play a subtle vibration when the notification is received on the watch.
***''ringtone'' Vibrates in a strong pattern until the notification is removed.
***''none'' Don't make the watch vibrate at all when the notification is received.

*'''removed''': to be used when the client wants to close a notification on the watch side. In that case, it can only contain the ''id'' sub-element which contains a notification ID attached to the notification to be closed.

Examples of well-formed values:

<pre>
<insert>
<pn>com.android.mms</pn>
<id>42</id>
<an>SMS</an>
<ai>ios-text</ai>
<su>Bob</su>
<bo>Hey, check out this super cool OS! http://asteroidos.org</bo>
<vb>strong</vb>
</insert>
</pre>

<pre>
<removed>
<id>42</id>
</removed>
</pre>

'''Notification Feedback Characteristic (UUID: 00009002-0000-0000-0000-00A57E401D05)'''

Eventually, this characteristic should allow the server to send command regarding notifications to the client (e.g: close a notification or call an action) but this feature is not standardized nor documented yet. Don't hesitate to contribute!

= Apple Notification Center Service (UUID: 7905F431-B5CE-4E99-A40F-4B1E122D00D0) =

AsteroidOS implements [https://developer.apple.com/library/archive/documentation/CoreBluetooth/Reference/AppleNotificationCenterServiceSpecification/Specification/Specification.html Apple Notification Center Service]. This provides notifications to apple products without need of extra client.

This implementation provides following characteristics:

- Source Characteristic (UUID: 9FBF120D-6301-42D9-8C58-25E699A21DBD)

- Control Point Characteristic (UUID: 69D1D8F3-45E1-49A8-9821-9BBDFDAAD9D9)

- Data Source Characteristic (UUID 22EAC6E9-24D6-4BB5-BE44-B36ACE7C7BFB)

=Screenshot Profile=

A client can save the content of the server's screen using the Screenshot profile.

==Screenshot Service (UUID: 00006071-0000-0000-0000-00A57E401D05)==
'''Screenshot Request Characteristic (UUID: 00006001-0000-0000-0000-00A57E401D05)'''

This characteristic can be written by the client to any value (for example one byte set to 0) to trigger a byte stream on the Screenshot Content Characteristic.

'''Screenshot Content Characteristic (UUID: 00006002-0000-0000-0000-00A57E401D05)'''

This characteristic can be used to be notified of a screenshot content. After a write to the Screenshot Request Characteristic, the first value signaled by the Screenshot Content Characteristic should be made of four bytes containing the size of the data to be transmitted and can be used to show a progress bar during the screenshot download time. The rest of the transmission is made of chunks of raw data to be concatenated by the client in a buffer to reconstruct a screenshot of the watch's screen. The complete buffer should be a valid JPEG file but other formats could also be considered in the future.

=Time Profile=

A client can change the server's system time using the Time Profile. This should be used periodically to synchronize a watch's time with the device it is currently connected to.

==Time Service (UUID: 00005071-0000-0000-0000-00A57E401D05)==
'''Time Set Characteristic (UUID: 00005001-0000-0000-0000-00A57E401D05)'''
This characteristic can be written. It is made of 6 bytes:

*''Year'' (byte 0) Year - 1900.
*''Month'' (byte 1) A value in the range [0-11] where 0 = January and 11 = December
*''Day'' (byte 2) A value in the range [1-31]
*''Hour'' (byte 3) A value in the range [0-23]
*''Minute'' (byte 4) A value in the range [0-59]
*''Second'' (byte 5) A value in the range [0-59]

=Weather Profile=

A client can fill weather information buffers on the watch using the Weather Profile. Those information can typically be used by asteroid-weather or asteroid-launcher's Today page to show current info. For each of the characteristics except for the Weather City Characteristic, the data is interpreted as a sequence of five two-byte big-endian values that correspond to "today" through "today + 4 days".

==Weather Service (UUID: 00008071-0000-0000-0000-00A57E401D05)==

'''Weather City Characteristic (UUID: 00008001-0000-0000-0000-00A57E401D05)'''

This characteristic can be written by the client to set the name of the city whose weather information are attached to. Values should be UTF-8 strings and they do '''not''' need to be NUL-terminated.

'''Weather IDs Characteristic (UUID: 00008002-0000-0000-0000-00A57E401D05)'''

This characteristic can be written by the client with a value of 10 bytes. Each pair of bytes represents an [https://openweathermap.org/weather-conditions OWM weather condition ID] for a specific day of forecast. For instance: Bytes 0 and 1 set to 500 represent light rain today.

For example, here is a valid value:

<pre>
0x00 0xc8 0x03 0x21 0x03 0x20 0x01 0xf4 0x02 0x58
</pre>

The interpretation is:
<pre>
0x00c8 = 200 = "Thunderstorm with light rain"
0x0321 = 801 = "Few clouds: 11-25%"
0x0320 = 800 = "Clear"
0x01f4 = 500 = "Light rain"
0x0258 = 600 = "Light snow"
</pre>

'''Weather Min Temperatures Characteristic (UUID: 00008003-0000-0000-0000-00A57E401D05)'''

This characteristic can be written by the client with a value of 10 bytes. Each pair of bytes represents a minimum temperature for a specific day of forecast. Note that temperatures are given in degrees Kelvin and not Celsius, so a value of 273 (0x0111) would correspond to a temperature of 0°C or 32°F.

Example:

<pre>
0x01 0x11 0x02 0x11 0x03 0x11 0xff 0xff 0x00 0x00
</pre>

The interpretation is mathematically sound (but physically unrealistic!):
<pre>
0x0111 = 273K = 0°C
0x0211 = 529K = 256°C
0x0311 = 785K = 512°C
0xffff = 65535K = 65262°C
0x0000 = 0K = -273°C
</pre>

'''Weather Max Temperatures Characteristic (UUID: 00008004-0000-0000-0000-00A57E401D05)'''

This characteristic can be written by the client with a value of 10 bytes. Each pair of bytes represents a maximum temperature for a specific day of forecast. Interpretation is identical to that of the Weather Min Temperatures Characteristic.

Building AsteroidOS

2024-02-06T09:07:51Z

Jmlich: link was somehow broken

[[Category:Developers]]
If you decide to compile AsteroidOS from source be aware that it’s a simple process but requires a lot of disk space (potentially more than 100GB) and the first build might take you a lot of time (hours). Report any problem to the [https://github.com/AsteroidOS/asteroid/issues issue tracker]:

[https://asteroidos.org/asteroid.mp4 Video showing the build process]

= General information =

You might want to build AsteroidOS in a ''container engine'' such as [https://www.docker.com/ Docker] or [https://podman.io/ podman] because you'll get a clean build environment that works no matter what kinds of package repositories or package versions you have installed or how outdated your Linux distribution is or which Linux distribution you're using in the first place.

Another advantage of Docker specifically is that it ''should'' also work on Windows and OS X. (However, this has not been tested yet!)

Using containers also allows you to easily roll back. Without a container, if you decided to delete the AsteroidOS repository and uninstall the prerequisite software packages from your computer, you will potentially remove packages that you had installed before and might actually still need. With a container, simply deleting the container image has no other effect on the host computer.

= Clone the repository =

Clone the main repository using the following command:

<pre>
git clone https://github.com/AsteroidOS/asteroid.git
</pre>

If you haven't set a global git name and email yet, adapt the following ''git config'' commands to your information. (This is only required to clone some git repositories when building.)

<pre>
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
</pre>

Before you continue to ''Build without containers'' or ''Build with containers'', make sure you're in the asteroid directory:

<pre>
cd asteroid/
</pre>

= Build without containers =

== Downloading ==

Install the prerequisites:

{| class="wikitable"
|+ Distribution prerequisite installation
|-
! Distro !! Command
|-
| Ubuntu || <code>apt-get install git build-essential chrpath cpio diffstat gawk liblz4-tool python3 shared-mime-info texinfo wget zstd </code>
|-
| Fedora || <code>dnf install chrpath diffstat g++ lz4 perl perl-bignum python3-pip rpcgen socat texinfo</code>
|-
| Arch || <code>pacman -Sy base-devel chrpath cpio diffstat gawk lz4 python3 rpcsvc-proto shared-mime-info texinfo wget zstd</code>
|-
| Alpine || <code>apk add binutils chrpath gcc g++ gawk gcc lz4 make patch perl rpcgen</code> <br>Note: Alpine Linux does not contain diffstat in its repositories, thus you have to [https://github.com/asottile-archive/diffstat build it yourself from source].
|}

This repository basically only contains a shell script that populates <code>src/</code> with OpenEmbedded and the appropriate Asteroid layers. Then, it setups the environment for a bitbake build. The following command will setup a build for <code>dory</code> (the LG G Watch) but you can also build an image for other watches by using the corresponding codename. (Codenames can be found on the [https://asteroidos.org/watches/ Watches page].)

<pre>
source ./prepare-build.sh dory # Be careful that this script must be sourced and not only ran
</pre>

If the environment has been correctly setup, you should now be in the <code>build</code> subdirectory.

== Building ==

Once the environment is prepared, you can simply trigger a build with the following command:

<pre>
bitbake asteroid-image
</pre>
''Notes:''
1) The build process requires roughly 2GB memory per thread. It might be necessary to limit the number of threads. This can be done by prepending <code>BB_NUMBER_THREADS=n</code> to the build command. Or by adding <code>BB_NUMBER_THREADS = "n"</code> to <code>build/conf/local.conf</code>. Where <code>n</code> is the amount of threads.
2) Bitbake is a powerful tool that can also build single packages (e.g: <code>bitbake strace</code>) or [[Creating an Asteroid app#Building the Cross Compilation Toolchain|Building the SDK]] for example. Refer to its documentation for more details.

If this step was successful, you can proceed to the [[#Installing|Installing]] section below.

== Updating the Sources ==

You can update the AsteroidOS sources with the following command:

<pre>
source ./prepare-build.sh update
</pre>

= Build with containers =

These instructions have been tested on Ubuntu 19.04 (with Docker) and Fedora 34 (with podman), but should also be applicable to Debian Sid (at least at the time of writing). For other distributions the dependencies may have different names and you may have to install additional ones.

From a user's point of view, Docker and podman are quite similar and accept almost all of the exact same commands, but there are some difference. The most significant differences for building Asteroid are that podman does not use a daemon and can be run "rootless" (that is, as a non-root user). This makes some things a bit easier, but either can be used.

== Setup ==

Remove the Docker container called <code>asteroidos-toolchain</code> if it already exists:

<pre>
sudo docker rm -f asteroidos-toolchain
</pre>
or
<pre>
podman rm -f asteroidos-toolchain
</pre>

Build a container image called <code>asteroidos-toolchain</code> from the given Dockerfile:

<pre>
sudo docker build --tag asteroidos-toolchain .
</pre>
or
<pre>
podman build --tag asteroidos-toolchain .
</pre>

== Building the software ==

Now that the container with the toolchain software has been created, we can use this to build AsteroidOS. All of the tools are contained and run within the container, but we use a ''shared volume'', essentially some drive space that both the host computer and the container can read and write, for actually creating the AsteroidOS image files.

In this example, we will build AsteroidOS for <code>dory</code>(the LG G Watch). To build for a different watch than the LG G Watch, use its corresponding codename instead of <code>dory</code> when executing the <code>docker run ...</code> command. You can find the codenames for the supported watches on the [https://asteroidos.org/watches/ Watches page].

Assuming that you have carefully followed the instructions so far and are in the <code>asteroid</code> directory, you can now build the software.

'''Run this as a non root user''':

<pre>
sudo docker run \
--rm \
-it \
-v /etc/passwd:/etc/passwd:ro \
-u "$(id -u):$(id -g)" \
-v "$HOME/.gitconfig:/$HOME/.gitconfig:ro" \
-v "$(pwd):/asteroid" asteroidos-toolchain \
bash -c "source ./prepare-build.sh dory && bitbake asteroid-image"
</pre>
or
<pre>
podman run \
--rm \
-it \
-v "$(pwd)":/asteroid:z \
--userns keep-id asteroidos-toolchain \
bash -c "source ./prepare-build.sh dory && bitbake asteroid-image"
</pre>

The files created during the build are placed in the current directory; more specifically, the source files are placed in a <code>src</code> subdirectory and build artefacts, including the final binary images are placed in the <code>build</code> subdirectory.

Here is a detailed explanation of the Docker command above:

*<code>sudo docker run</code> Runs a container image
*<code>--rm</code> Cleans up after the command is run by removing temporary container storage
*<code>-it</code> Attaches the terminal to the container so that we can see the output. Otherwise it would run blindly in the background.
*<code>-u "$(id -u):$(id -g)"</code> Ensures that the current user id and group id from the host is used on files inside the container to avoid permission issues.
*<code>-v /etc/passwd:/etc/passwd</code> Ensures that the user ids and groups from the host are also available in the Docker container. (Otherwise the <code>-u</code> and <code>-g</code> would be useless.)
*<code>/etc/passwd</code> Contains the user names and their ids.
*<code>"$HOME/.gitconfig:/$HOME/.gitconfig"</code> Share your user's git config with the container.
*<code>-v "$(pwd):/asteroid"</code> Mount the current directory (which is your asteroid git repo clone) into the container.
*<code>bash -c "source ./prepare-build.sh dory && bitbake asteroid-image"</code> This is the command to be executed inside of the container with "dory" being the codename of your watch.

Here is a detailed explanation of the podman version of the command above:

*<code>podman run</code> Runs a container image
*<code>--rm</code> Cleans up after the command is run by removing temporary container storage
*<code>-it</code> Attaches the terminal to the container so that we can see the output. Otherwise it would run blindly in the background.
*<code>-v "$(pwd)":/asteroid:z</code> Mount the current directory (which is your asteroid git repo clone) into the container. The <code>:z</code> tells SELinux, if it's running, to allow multiple containers to share this mount.
*<code>--userns keep-id</code> Run as the current user inside the container
*<code>bash -c "source ./prepare-build.sh dory && bitbake asteroid-image"</code> This is the command to be executed inside of the container with <code>dory</code> being the codename of your watch.

If this step was successful, you can proceed to [[#Installing|Installing]] below.

= Installing =

After a while, whether you build with or without containers, the generated image should be available in <code>build/tmp-glibc/deploy/images/dory/</code> (for <code>dory</code> -- for other watches, the image files are in the corresponding code word directory.)

Install AsteroidOS using your usual device's instructions, which you can find linked from the [https://asteroidos.org/watches/ Watches page].

Building the SDK in a container

2024-01-24T11:01:17Z

Jmlich: Add openembedded to related pages

[[Category:Developers]]

==Summary==
This page describes how to build the Software Development Kit (SDK) for AsteroidOS using ''software containers''. If you want to build the SDK without using containers, see [[Building the SDK]] instead.

If you're not sure which you want, skip to [[With or without software containers?]]

If you're not sure why you would want an SDK, continue reading.

===What is an SDK?===

The Software Development Kit (SDK) for AsteroidOS is a set of tools and libraries for developing software to run on AsteroidOS. Since AsteroidOS is a Linux distribution, you can use just about any programming language to develop software, but most of the core applications use a combination of C++ and Qt, with CMake to build. To get things running quickly, it's recommended to download and install the prebuilt version as described in [[Installing the SDK]]. This page describes how to build the SDK from source. Be aware that this can take several hours, even on a fast computer.

====Which SDK?====
One thing to note is that while this describes "the SDK", there are actually two versions -- the main one is used to develop software that runs on ARM-based watches running AsteroidOS. The other one is the SDK for developing applications that run on the emulator, which uses qemux86. See the [[Emulator]] page for details on the qemux86 version. This page describes only the main ARM-based SDK but building the emulator version is almost the same. The only difference is that instead of this:
source ./prepare-build.sh dory
bitbake meta-toolchain-qt5
you would do this instead:
source ./prepare-build.sh qemux86
bitbake meta-toolchain-qt5

You can install both SDKs on the same machine -- they do not interfere.

==With or without software containers?==
There are two choices to build the SDK: build natively without software containers or build within a software container (such as docker or podman).

Building natively requires somewhat fewer resources (memory and disk space) than building with containers but requires software, such a compilers and other tools, to be installed on the host system. Since these software packages are different for each Linux distribution, this method requires more knowledge and patience to install required software that might not already be installed on your host computer.

The alternative, building with software containers, is somewhat more simpler in that the required software is only installed within the container and not on your host computer, but it requires much more time to compile everything. Still, this may be preferable for people who wish to keep the build environment isolated from the host computer.

The rest of this page describes how to build **with** containers. If you have decided to build natively instead, go to [[Building the SDK]]

===Build with containers===

Assuming you already prepared a docker or podman build environment as described in [[Building AsteroidOS]], build the SDK like so:

<pre>
sudo docker rm -f asteroidos-toolchain
sudo docker run -it \
--name asteroidos-toolchain \
-v /etc/passwd:/etc/passwd:ro \
-u "$(id -u):$(id -g)" \
-v "$HOME/.gitconfig:/$HOME/.gitconfig:ro" \
-v "$(pwd):/asteroid" asteroidos-toolchain \
bash -c "source ./prepare-build.sh dory && bitbake meta-toolchain-qt5"
</pre>

or

<pre>
podman run --rm -it \
-v "$(pwd)":/asteroid:z \
--userns keep-id asteroidos-toolchain \
bash -c "source ./prepare-build.sh dory && bitbake meta-toolchain-qt5"
</pre>

==Install the SDK==
Whether you have built with or without containers, if the process was successful, you should have an SDK installation script <code>tmp-glibc/deploy/sdk/oecore-x86_64-armv7vehf-neon-toolchain-nodistro.0.sh</code> (relative to the <code>build</code> directory) -- or a <code>oecore-x86_64-core2-32-toolchain-nodistro.0.sh</code> script if you are building the version of the SDK for the emulator. Follow [[installing the SDK#Installing the SDK|these steps]] to install the SDK.

==Related pages==

[[Building the SDK]]

[[installing the SDK]]

[[Building AsteroidOS]]

[[Creating an Asteroid app]]

[[OpenEmbedded]]

Frequently Asked Questions (FAQ)

2024-01-19T12:47:06Z

Jmlich: added link to agenda apps page

== What is AsteroidOS? ==
AsteroidOS is an open source Linux distribution that runs on many different smartwatches. It uses [http://www.qt.io/ Qt] and QML to provide the graphical interface.

One of the main goals of AsteroidOS is to provide users with greater control over their devices and data privacy. The operating system is fully customizable, and users can modify it to meet their specific needs.

== Which features are provided? ==
Currently, AsteroidOS has these features available:

- Always-on-Display

- Tilt-to-Wake

- Palm-to-Sleep

- Phone notifications

- Multiple app launcher styles

- Wallpapers

- [https://github.com/AsteroidOS/unofficial-watchfaces Community watchfaces]

- Nightstand mode

== Are any apps preinstalled? ==
The following apps are delivered with an AsteroidOS installation:

- [[Apps: Agenda|Agenda]], a calendar

- Alarm clock

- Calculator

- Compass

- Diamonds game

- Flashlight

- Heartrate check

- Music, a media remote control

- Settings

- Stopwatch

- Timer

- Weather forecast

== Does an app store exist? ==
A store to install apps does not yet exist. But this is something that is being considered for future implementation. There are a number of contributed apps that are not installed in the default image. These can be [[Watchface and Package Installation|installed manually]] if desired.

== How can I connect the watch to my phone? ==
A phone is not ''required'' to use AsteroidOS, but several convenient functions are available when an AsteroidOS watch is paired with one of the [[Synchronization Clients|synchronization clients listed in the documentation]]. A ''synchronization client'' is generically what we call software that runs on a phone or computer that knows how to talk via Bluetooth to an AsteroidOS device.

- Android users can use "AsteroidOSSync" which is available for [https://f-droid.org/packages/org.asteroidos.sync/ download on F-Droid]. Or try [https://f-droid.org/packages/nodomain.freeyourgadget.gadgetbridge/ Gadgetbridge from F-Droid] with initial AsteroidOS support. Mind that on Android 13 and later devices, you will need to manually enable "restricted notification access". The option is hidden behind the three dot menu in app-info.

- Ubuntu Touch users can download [https://open-store.io/app/telescope.asteroidos Telescope" from OpenStore]

- There is currently no app for iPhone, however notifications can be shared from an iPhone to the watch. See [[Synchronization Clients|this page]] for details.

== What features and apps does AsteroidOS '''not''' provide? ==
There are a great many more ''ideas'' for apps than apps at the moment. Some of the more commonly requested, but not yet available applications and features are:

- Call answering from the watch

- Fitness and health tracking application (step counter, ongoing heartrate monitor, etc.)

- Support for using the watch as a phone (for some watches that incorporate a cellular phone chip)

- ''And many more''

Some of these are being worked on, and others are just ideas at this point. If you think you might like to contribute, see our [https://github.com/AsteroidOS/asteroid/issues GitHub repository] and the [https://asteroidos.org/contact/ Contact] page. There are many opportunities for creativity!

== Is AsteroidOS based on Android? ==
No. AsteroidOS uses [[wikipedia:Hybris_(software)|libhybris]] to simplify porting to most Android and WearOS watches, but it is not Android nor is it WearOS or a derivative of either.

Hardware drivers on modern smartwatches are specifically tailored for Android and WearOS devices. These drivers are closely tied to the hardware and are not compatible with other operating systems, which usually makes porting to alternative platforms a complex and time-consuming process. Libhybris allows AsteroidOS to leverage the proprietary binary drivers and thus greatly helps porting Linux to Android based hardware.

== Can I run WearOS applications? ==
No. [[wikipedia:Wear_OS|WearOS]] is a version of Android that runs on wearable devices. AsteroidOS is a Linux distribution that does not run Android and therefore cannot run either Android or WearOS applications.

== What is different to WearOS? ==
One significant difference is that AsteroidOS is open source software, while WearOS is not. That is, if you want to change something and you are a developer, you can [[Building AsteroidOS|build the software]] yourself. Or perhaps you would like to [[Creating a Watchface|create your own watchface]].

Another significant difference is that AsteroidOS, unlike WearOS, tries to make the watch usable without pairing it with a phone. In contrast, WearOS watches only run when they are paired with a phone.

== Does AsteroidOS have any tracking features? ==
No. AsteroidOS does not collect any tracking data and you don't need to use or establish any accounts to use it. Nothing on the default installation is able to connect to the internet. While it is possible to [[IP Connection|connect an AsteroidOS watch to the internet]] this must be explicitly done by the user.

== Can my watch run AsteroidOS? ==
Maybe. Check the [[:Category:Watches|Watches]] page. It lists all devices supported by AsteroidOS. The star rating indicates the current level of support for each device's hardware features. Watches with at least 3 stars can be considered suitable for everyday use.

== My watch isn't listed. ==
Maybe you can still run Asteroid OS in the future. See the [[Porting Status|porting status]] page for details on what kinds of watches might be supported in the future and what the general requirements are for running AsteroidOS.

If you are interested in porting AsteroidOS to a new watch yourself, please read the [[Porting Guide]] page and contact us via our [https://asteroidos.org/contact/ matrix channel] in case of possible questions.

== Which features of my watch are currently supported? ==
The available AsteroidOS features depend on the watch you want to use. Review the table on the installation page for your device to get detailed support information.

Or check the [https://asteroidos.org/watches/features/ features table] to see a matrix of all AsteroidOS watches and their feature support.

== Will I be able to revert to the previous operating system? ==
Yes, very easily if you choose the "temporary install" option.

For most watches, you may choose to only temporarily install AsteroidOS alongside the existing OS, called a "dual-boot". When doing so, the <code>asteroidos.ext4</code> image is pushed to the userdata partition using ADB. With no alteration to the previous OS. The downside of this method being, AsteroidOS needs to be manually booted using <code>fastboot boot boot-image.fastboot</code> while connected via USB, after every reboot or shutdown. Else, the previous OS will start up as usual.

In case you decide to replace your previous OS using the full install method, to make the watch boot into AsteroidOS without manual intervention. It is advised that you [[Backup Guide|make a backup of your entire watch]] before flashing AsteroidOS. Only then, you will be able to re-flash those backups to restore the previous OS later.

== When can I expect updates? ==
The complete rebuild of all packages for all Watch system images and architectures takes almost a week. The build process is started at the beginning of a week. Therefore, it can be expected that new nightlies will be available on the weekend. These will contain all the changes that have been merged up to the start of the build process.

== Can I compile AsteroidOS myself? ==
If you do not want to flash a prebuilt image onto your watch or wait for the nightlies to be updated, review the [[Building AsteroidOS]] page for detailed instructions on how to compile AsteroidOS yourself.

== My question is not answered. ==
There are many additional resources. The [[Documentation]] page should be your first stop. It has a lot of useful information about both using and developing for AsteroidOS. If you can't find your answer on this web site, see [https://asteroidos.org/contact/ Contact].