This is a short article to document a process of adding a fairly simple feature to Gadgetbridge. This article is intended to newcomers wanting to participate in Gadgetbridge development who do have some understanding of programming in Java for Android (in Android Studio). Written by a fellow novice programmer in the Android Java ecosystem, it hopes to serve as a basic introduction to some of the concepts used in the Gadgetbridge codebase. There is more information in our wiki, like the Developer documentation and if you are looking for an advice how to add a new device support into Gadgetbridge, there is a comprehensive New device tutorial.


Gadgetbridge has been showing the wearable device's battery level and low battery warning almost forever since it's beginning. What we want to add is a screen showing us a graph of battery level over time + maybe even some more known details about the battery itself if the device provides it.

First, we need to do some digging and find out how Gadgetbridge knows about device battery stats. This is the first biggest hold-up, because getting familiar with the codebase does take some time but is an essential part of the process. Do spend some time digging through the code to understand the patterns, packages and code layout.

Hooking into device events

Where do we begin... searching in files Ctrl-Shift-F for battery sounds like a good place to start for us, but it is a bit too vague, so we try searching for battery low, since we know this can come up in the notification. We get some strings in the strings.xml, so let's find a usage of one of them, notif_battery_low_title via same global search in files. One of the places where this is used is handleGBDeviceEvent(GBDeviceEventBatteryInfo deviceEvent) in AbstractDeviceSupport. This seems to be a good hit, because if we look at usage of this method via Ctrl-B, we can see it being used in most if not all of the implemented devices. This final method is a good place where we can catch the event of getting battery info as it is received from the device. Here, we can hook our routine to store this data into database. We can also note and explore a bit the GBDeviceEventBatteryInfo class used in the handleGBDeviceEvent(GBDeviceEventBatteryInfo deviceEvent), as it provides more details about the battery, if a particular device supports that, for example number of charges, last charge time and so on.


To store the data, we need a database table. In Gadgetbridge, database access is provided via greenDAO - Object Relational Mapper for Android. Tables are defined in src/nodomain/freeyourgadget/gadgetbridge/daogen/ as entities. In the GBDaoGenerator we define our entity, containing properties, which are mapped to database columns. To store different data per device, we must ensure to add mapping to our devices with the addToOne(device, deviceId). The above defined entities will be auto-generated in the nodomain.freeyourgadget.gadgetbridge.entities package. Experiment as needed but make sure to test your object model well and check logcat for error messages, because the DAO can insert values to the database but still throw errors if for example indexes are not set correctly.

After the table definition is done, we must also bump the database schema version: Schema schema = new Schema(VERSION, MAIN_PACKAGE + ".entities");, this is important for database migrations.


At this point, we are getting our battery data, are storing it into database and would like to show a line chart showing battery level over time. To define a new activity (screen), it is important to extend the AbstractGBActivity because it will taking care of the theme (light and dark) language switching and so on.


Gadgetbridge has several places where charts are already used, for that the MPAndroidChart library is being utilized. Some convenience classes are already defined and should be reused, like the AbstractChartFragment, which is especially useful if you want to show activity data like steps or heart rate.


When displaying log messages, never use the e.printStacktrace(). Either use the predefined logger private static final Logger LOG = LoggerFactory.getLogger(Your.class);, or you can also use the toast GB.toast(getContext(), "Error doing xyz: " + e.getMessage(), Toast.LENGTH_LONG, GB.ERROR, e);, this will show the toast, log the stacktrace in logcat and write the logs (if enabled).

General advice

  • Make sure to auto-format the code you write, but leave existing code as is, even if not formatted well, because formatting it would break existing PRs and it also destroys information about the original author.
  • There are many convenience and utility classes already defined in Gadgetbridge which should be re-used instead of defining again (for example from the nodomain.freeyourgadget.gadgetbridge.util package).
  • Abstract classes definitions are very commonly used throughout and should also be used where useful.
  • Pay attention to the warnings and suggestion Android Studio provides, in general code and also in activity layouts.
  • Try and test your work diligently - there is no bug tracking code in Gadgetbridge and if the app has issues or randomly crashes on some user devices, there is no way to learn about it, unless people make the effort and report it. If you have multiple Android phones, ideally test on them, to see how different Android version behave, what different screen sizes and pixel densities look like.
  • Also, do not forget to test in both light and dark theme.


So this is it, a quick introduction to a very small portion of Gadgetbridge internals. And where is our Battery info screen? Well, the initial code is here and a picture is below, but it needs much more work, like better axis formatting, moving between days... because like always, the small fine details take 80% of the real work. I will keep working on it and it will be released when ready :)