Project overview¶

Discover code¶

Important classes¶

• PebbleSupport (see class hierarchy)
• PebbleProtocol (pebble communication protocol)
• PebbleIOThread (background thread for pebble communication)
• MiBandSupport (see class hierarchy)
• BtLEQueue (communication queue for Bluetooth LE devices)
• DeviceCommunicationService (Android service channeling the communication with devices)
• DeviceService ("client side API" of DeviceCommunicationService, see GBApplication#deviceService())
• GBDevice (generic, device-unspecific)
• DeviceCoordinator (see class hierarchy)
• ControlCenterv2 (main activity)

Examples¶

Short article demonstrating adding a simple database/UI feature: Adding battery info screen to Gadgetbridge.

Overview¶

All the details about the communication/protocol with a concrete device (Pebble, Mi Band, ...) is inside the "Concrete Device Impl." component, that is, the concrete implementations of the DeviceSupport interface. Only the DeviceCommunicationService has access to those -- clients (typically Activities) talk to the DeviceService interface in order to communicate with the devices.

Bluetooth error codes¶

See here.

Logging¶

We use slf4j for logging, so just use LoggerFactory.getLogger(Your.class) and log away. The output will be written to the Android Log (so you can get it with logcat or Android Studio) as well as to the file /sdcard/Android/data/nodomain.freeyourgadget.gadgetbridge/files/gadgetbridge.log. File logging needs to be enabled in Gadgetbridge's preferences, first.

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
// ...
private static final Logger LOG = LoggerFactory.getLogger(Your.class);
// ...
LOG.error("Error accessing database", e);

GBDevice is cached in activities¶

Most activities receive the GBDevice via Intent during activity invocation. Be aware that the device in the activity is a copy of the device and thus it might not have the same updated information. So if you for example subscribe to device state updates and then want to get current data from the device (for example device.getBatteryLevel(), make sure to update the activities local copy of GBDevice:

BroadcastReceiver commandReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            LOG.debug("device receiver received " + intent.getAction());
            if (intent.getAction().equals(GBDevice.ACTION_DEVICE_CHANGED)) {
                GBDevice newDevice = intent.getParcelableExtra(GBDevice.EXTRA_DEVICE);
                if (newDevice.equals(device)) {
                    device = newDevice; // ← update local copy of the GBDevice
                    // Do your stuff here...
                }
            }
        }
    };

Information display¶

Use one of the nodomain.freeyourgadget.gadgetbridge.util.GB#toast() methods to display information to the user.

• The toast when given an exception also logs warnings and errors, so with the toast you not have to use "LOG" afterwards.
• Can safely be called from a background thread.

import nodomain.freeyourgadget.gadgetbridge.util.GB;
// ...
GB.toast("My toast message", Toast.LENGTH_SHORT, GB.ERROR, e);

Database¶

We use greenDAO for database access. See nodomain.freeyourgadget.gadgetbridge.daogen.GBDaoGenerator for entity definition and generation. Do note that we use greenDAO in version 2, the official greenDAO documentation already mentions version 3.

To add a column to a database, simply add a new field to a particular class in nodomain.freeyourgadget.gadgetbridge.daogen.GBDaoGenerator, then build the project, which will trigger generating of corresponding ...dao.class files. Also, make sure to set a new schema version Schema schema = new Schema(xx... and prepare a migration file in src/main/java/nodomain/freeyourgadget/gadgetbridge/database/schema/.

Icons¶

All icons should be provided as vector drawables, do not use PNGs anymore. If you are drawing the original design in SVG, make sure to export as regular uncompressed SVG, because Android Studio handles these files better. Then, import it to Android Studio via right click in "Project panel → New → Vector Asset → Local file". Then, use Avocado optimizer for Android VectorDrawable (VD) and AnimatedVectorDrawable (AVD) XML files. Avocado rewrites the VectorDrawable using the smallest number of <group>s and <path>s possible, reducing their file sizes and making them faster to parse and draw at runtime.

Device icons¶

For device icons (ic_device_xxx, ic_device_xxx_disabled), start from an existing icon's SVG source, you can use the Galaxy Buds icon, here is the source for the normal state and here for the disabled state. Modify this SVG (remove the buds and draw the device you need), save, then import into Android Studio as described above, then optimize with avocado. Then, in Android Studio, change the dimensions inside the XML file to this:

android:width="45sp"
android:height="45sp"
android:viewportWidth="30"
android:viewportHeight="30"

And if you want to optimize it even further, change the strokeWidth to remove unnecessary precision, for example from strokeWidth="0.498675" to strokeWidth=0.5". Look at the other device icons for examples.

Colors¶

The colors.xml defines colors which are then used throughout the app. See also styles.xml.

Preferences¶

Preferences that are not specific to the user's device but are for the whole application are in:

Prefs prefs = GBApplication.getPrefs();

User's device specific preferences - that is, each devices own preferences, go into:

SharedPreferences prefs = GBApplication.getDeviceSpecificSharedPrefs(gbDevice.getAddress());

One should try to re-use existing preferences. When adding new preferences, these should be made generic so they can be re-used, rather then being vendor or device specific, if it is not required. So for example RGB color settings can change color on a watch, led, FM transmitter or a wireless ear buds.

Adding a feature¶

The Adding battery info screen to Gadgetbridge blog post is a friendly documentation of the steps needed to add a new feature to Gadgetbridge and it touches on several important parts, adding a new database table, hooking up device Bluetooth events, storing data, adding a chart screen and so on.

Translations¶

Do not add translations by editing the language variants of strings.xml directly as this creates merge conflicts between Codeberg Git repo and Weblate Git repository. Always use Weblate, as per info in the website.

Copyright¶

All source files should contain the relevant copyright header. As an example, for Java files created specifically for Gadgetbridge:

/*  
    Copyright (C) 2023 John Smith(1)

    This file is part of Gadgetbridge.

    Gadgetbridge is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published
    by the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Gadgetbridge is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.

    You should have received a copy of the GNU Affero General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

1. A real name is not mandatory - a nickname can be used.

For source code copied or adapted from other opensource projects, the relevant copyright header should be kept, not violating that project's license.

Short introduction to Git and the related workflow¶

Git can be intimidating and being familiar with it takes some getting use to. There are numerous resources on the internet, like the Dangit, Git!?! or Git documentation, Git from the bottom up, Things I wish everyone knew about Git.

Here is a short, opinionated, by no means comprehensive guide to the typical steps that are needed when working with Gadgetbridge code and repo. Use this as a simple guide but do make sure to read-up on git more in other places, in documentation and so on. If you spot an issue, please edit it too, to help other to be more confident and comfortable when using git.

Forking the repository¶

Initial step: fork the Gadgetbridge repo on Codeberg to have your own repo. You do this by using the Fork button on the Gadgetbridge repo page. This will create your copy of the repo in Codeberg, under your username. The username will be unique to you, so in this steps, username indicates a Codeberg and you must replace it with your username if you copy/paste these commands. As this copy is sitting on the remote Codeberg server, we will refer to it as a remote or as origin. In order to work with the code, you will need to make a local copy via cloning.

Cloning your forked copy¶

To get the code to your computer, you must clone the repo.

git clone https://codeberg.org/username/Gadgetbridge.git

This will create local copy of the repository. The remote copy will be named origin, while the official Gadgetbridge repository is registered in your cloned repo as upstream.

Master branch¶

The main branch of the Gadgetbridge repo is called master.

Creating a branch¶

When adding a feature for later merge/pull request, you typically create a branch. You do a branch and do not do this in the master, because you will typically like to keep the master as is, in order to be able to have it to follow the upstream's master in Gadgetbridge repo. You can either add a branch before you start.

git checkout -b new-branch

Or you can first make some changes, and only then make the branch, for example like this:

• Do some edits.
• git add ./path_to_the_changed file(s)
• git checkout -b new-branch

Committing into the branch¶

Your changes are now being stored into your my-new-branch by committing:

git commit

Pushing your local branch to your remote on the server¶

git push origin new-branch

Switching branches¶

As long as all your changes are committed, you can switch between different branches, like this:

git checkout master in order to perhaps see how things are in the master branch and then you can go back to your new-branch git checkout new-branch.

Seeing changes between branches¶

You can see diffs between your new-branch and the master:

git diff master

You can also get the master version of a file you edited, to roll it back to the "original" state:

git checkout master ./path to a file

Syncing with the Gadgetbridge project¶

This is all cool, but while you work on your thing, the Gadgetbridge project is moving along and you must stay synced to it. You do this by switching to the master branch and pulling the remote changes:

git checkout master
git pull upstream master

This updates your local master to be the same as upstream.

Rebasing on top of the master¶

You must also ensure, that your branch is actually based on the master. You do this by rebasing on top of the master:

• Switch to the master and make sure it is up to date with upstream: git pull upstream master
• Switch back to your branch: git checkout my-branch
• Then "rebase" it on top of the remote master: git rebase upstream/master

Resetting the master to the upstream¶

Sometimes, you mess things up badly and want to make sure that your local master is really the same as the upstream master. This can be done by using the destructive reset command of git. This will cause local data loss, so be sure to know why you do this.

• You switch to your master: git checkout master
• Remove all unadded files: git clean -f -d
• And then reset it to upstream: git reset --hard upstream/master --

Squashing commits via git rebase¶

The git rebase command is very power full and allows you to do many things, like remove, re-order or squash commits, edit the commit message and so on. Read-up about it in the documentation. One of the things it can do is to allow you to selectively squash commits. This can be done in an interactive way by using the -i option and choosing a commit where you want to start. As the action of using the rebase still makes a commit, so somewhat counter intuitively you must choose "one commit before the start" of your commits:

git rebase -i one-commit-before-the-start-of-your-commits

In the text editor that is opened for you, you leave the first line intact and edit the pick word in front of the commits on the following lines. For example by changing the pick to squash (or to s), this commit will be squashed to the one above it. As mentioned, leave the first line intact. Save and close the file, which will invoke the squashing.

Force pushing¶

As the above-mentioned rebase actions overwrite git history, if you have previously pushed to your remote, you must force push now. You should not do this if this is for example a master branch and you share the repo with other people, because this breaks things for them (again, read-up about it). But for your work and/or while working alone in a dedicated branch, this is OK. You will also do this quite a bit if this branch is used as a pull/merge request.

git push -f origin new-branch

Testing a pull request¶

When people submit a pull request (PR), you can clone it and test it quite easily:

git pull upstream pull/1234/head:branch_name

This will clone a PR number 1234 into a local branch called branch_name. Now the branch is local and you can work with it like with any other branch.

Save a snapshot without creating a commit in your working branch¶

Do a git stash, followed by a git stash apply. This will create a named commit which can be accessed or checked out at any time back. List all stashed with git stash list.

An undo for git¶

As long as you added and committed your files and did not accidentally erased the .git folder, you can mostly recover all your commits even if you for example squashed or removed them or removed a complete branch. Use git reflog, (short for "reference logs") to get a list of previous commits and changes. Here you can note the commit hashes and get them back for example by cherry-picking:

git cherry-pick commit_hash