Custom Firmware

A tutorial on how to create customised applications for singingcat modules

This tutorial explains several concepts:
1. forking the singingcat firmware repository
2. modifying the newly forked repository
3. setting your devices up to receive the software

Prerequisites

We use git for our firmware version control. Readers should be familiar with git. The official git documentation is here. Read this first, if not familiar with git.

Forking

We only accept modifications by third-parties, in form of patches, to our main, public firmware if we consider the modifications to be useful for everyone and they are available open-source via our main repository.
As a consequence, in order to make a customised version of our firmware you will need to create a copy of our firmware and modify this. We (and others) call this "forking". You may modify this forked copy freely. Caveat: read the next section!
You find the main firmware application under the menu software and it is called "Firmware Application". Next to its name is a link "(fork)". Click on the link. You will be asked for a name and a path. Choose the name freely, but choose it in such a way that you can identify your copy by it. The path is essentially a directory name. You will need this to check out the code to your machine. Once you submitted this, it will take a few seconds and from then on your repository will be available from our servers. You can check it out with git. You find the git command, including the url for the new repository under the menu software under the heading "Private Software Repositories". You forked it! Go ahead, clone it now...

Modifying it

You may modify any file of the firmware. However, we encourage you to modify only the source under src-app/, if possible. If you modify other files, we might not be able to build, deploy or patch (upgrade) your repository. If there is a specific thing you like to do, but it cannot be done by modifying src-app/ files, please let us know.

We document our code throughout, here are some useful links to get you started:
Documentation of userhooks.c
Documentation of Hardware Abstraction Layer

Once you made all the modifications, tested them and are ready to roll them out, commit and push them to our server

Note: we provide a Makefile that you may use to pull patches from upstream (our public repository): "make upstream"

Note: We will compile and link your software with the appropriate compilers and buildchain on our servers.

Setting your devices

You find a list of your devices here. Select the module you wish to configure for your new Repository and select its ID. (the number next to the module on the left).
Set the Module Upgrade Strategy to "Immediately" and choose your new repository from the list below.
Select "Set".
Once you completed this step, and from now on, each time you commit/push your software changes, they will be sent to this device. You won't need to log in to our website during your development workflow.