This document contains information about how Crumpet talks to Tail Company gear, and explains some of the decisions we have taken. This document may be interesting if you want to create your own gear-controlling app. Just bear in mind why we have taken these decisions, so as not to damage your gear.
This document is in flux with the launch of MiTail, and is updated regularly.
For information on the basic concepts of the application's codebase, and for information on how you should approach the code if you wish to contribute, please see our HACKING document.
Please see separate document entitled "EarGear Protocol" for full details
Over Bluetooth, you find the device by its ID, then you find its service (like its battery gauge) and the its characteristic (what's the power level?) and then Connect. And read the info, and show it, or write to it!
Device name is "(!)Tail1" (for DIGITAiL) or "mitail" for MiTail Device Service [0xffe0] (for DIGITAiL) Device Characteristic [0xffe1]
Note: You cannot use DIGITAiL when it is connected to the power supply.
Device name is "mitail"
Device Service is 3af2108b-d066-42da-a7d4-55648fa0a9b6
5bfd6484-ddee-4723-bfe6-b653372bbfd6 - Rx characteristic c6612b64-0087-4974-939e-68968ef294b0 - Tx characteristic
All aspects of the Tail are controlled through these services and these characteristics.
Note: you can use MiTail whilst its charging.
--
There are 11 built in moves you can call up immediately.
TAILS1 - SLOW_WAG1 11.53 secs
TAILS2 - SLOW_WAG2 7.10 secs
TAILS3 - SLOW_WAG3 8.50 secs
TAILFA - FAST_WAG 9.96 secs
TAILSH - SHORT_WAG 7.46 secs
TAILHA - HAPPY_WAG 8.86 secs
TAILER - ERECT 5.80 secs
TAILEP - ERECT_PULSE 9.76 secs
TAILT1 - TREMBLE1 4.06 secs
TAILT2 - TREMBLE2 5.55 secs
TAILET - ERECT_TREM 4.73 secs
and a Home Move: TAILHM
There are 6 built in LED patterns.
LEDREC - intermittent (on/off)
LEDTRI - triangular (fade in/out)
LEDSAW - sawtooth (fade in/off)
LEDSOS - Morse SOS
LEDFLA - flame simulation
LEDSTR - strobo
and an Leds off command: LEDOFF
It is always recommended to connect a power source to MiTail before updating the firmware and Crumpet will enforce this. We can detect whether external power is connected, but not whether it is the mains, or a powerpack.
Crumpet will insist that the tail is both connected to the mains or a powerpack, and has more than 50 percent charge, before beginning the update. Crumpet also does the version checking of the firmware. Is it more recent? Ok, ill flash it. The tail doesnt check this. It will accept whatever it is sent, as long as it agrees with the MD5 checksum which accompanies it.
At the end of a succesful OTA update, the tail will reboot, as long as its connected to external power. If it is not connected to external power, it will power off at the end of the update and need to be manually switched back on. However, Crumpet will not perform the update unless the mains or power packs are detected.
The filename of the update sent to the tail doesn't matter. All the code is rewritten when flashed, except for the bootloader. There are 2 partitions (A and B). Lets say A has the current booted code in it and the tail is running from there. We start an OTA update. MiTail copies the new file to partition B. On successful receipt, it then marks that partion for a temporary boot and reboots. If all is well, it makes it permanent. If not, it reverts to partion A
VER - returns the firmware version number
PING - returns OK
SHUTDOWN - powers off the unit (will lose the connection!)
BATT - returns Bn (n= 0,1,2,3,4 number of 'bars')
USERMOVE and USERLEDS which deal with user created moves or LED patterns
Also, DIGITAiL commands are case insensitive. MiTail commands must be in all caps.
AUTOMODE is another command, created for iOS devices, where sending bluetooth in the background is prohibited.
Note about Battery Level: the batteries are read charge-wise only when the app asks. There is a super-quick flash of any connected LEDS when the reading is done. The charge level is returned BATTn with n showing charge. If the Tail determines the charge is low, the tail will flash the internal red led.
We will split the app in to two parts from the Users point of view.
Slower, gentler, relaxed:
Slow Wag 1
Slow Wag 2
Slow Wag 3
Faster, happier, excited:
Fast Wag
Short Wag
Happy Wag
Erect
Angry, frustrated, tense:
Tremble 1
Tremble 2
Tremble Erect
Pulse Erect
Building the app is a multi step process, so please make sure you do the steps in the right order.
To clone the repository, you must also remember to clone the submodules. Using the git command line this would be done like so:
git clone --recursive (repository URL goes here) $HOME/DIGITAiL
If you have already cloned the repository before reading this, you will need to initialise the submodules. Again using the command line, this would be done like so:
cd DIGITAiL
git submodule update --init --recursive
(this will need a touch of help from someone more used to working on Windows)
These instructions assume you are building on the command line. You are entirely able to build things using an IDE (such as KDevelop), but the command line instructions give the most terse set of steps, and it should be possible to extract needed information for building using your favourite graphical tools from the listings below.
Once you have cloned the source code, you will need a few bits of software to be able to build and run the app.
- Basic C++ building tools
- CMake 3.2 or later
- Extra Cmake Modules version 5.68 for KDE/kirigami or later
- Development packages for Qt version 5.12 or later
The following lines will install the packages you need:
sudo zypper install --type pattern devel_C_C++ devel_qt5
sudo zypper install extra-cmake-modules
sudo zypper install libQt5QuickControls2-devel libqt5-qtbase-private-headers-devel
You should install at least the following packages:
sudo apt install g++ # or sudo apt install build-essential
sudo apt install cmake
sudo apt install extra-cmake-modules # ECM
sudo apt install qtbase5-dev qtdeclarative5-dev qtmultimedia5-dev qtquickcontrols2-5-dev libqt5svg5-dev libqt5bluetooth5 qtconnectivity5-dev libqt5svg5-dev qtbase5-private-dev libqt5remoteobjects5-dev libqt5remoteobjects5-bin
Once these have been installed, you are ready to build. You should always build software out-of-source, which means creating a directory somewhere and performing the actual building there. Enter the clone directory as created above by the clone command. Unless you have moved around the filesystem, you should already be in the directory containing the source code.
mkdir build
cd build
cmake .. #For successfull CMake on Ubuntu 20.04 need to override ECM version in $HOME/DIGITAiL/3rdparty/kirigami/CMakeLists.txt as "find_package(ECM 5.68.0 NO_MODULE) #find_package(ECM 5.72.0 NO_MODULE)"
make
If any errors occur during the cmake step, you may find that you have either not followed the steps above correctly, or that you are missing some piece of software or another required for the build. The way to fix this will vary depending on your distribution.
You may also notice some warnings during the CMake configuration step about policy changes. Don't worry about those, they're less dangerous than they seem.
Once the make command has completed successfully, you should find yourself with a binary named digital inside the src subdirectory of your build directory. As the app is split into two (a service part and the visible app which controls that service), you can run this by running the following two commands, each in their separate shell:
These are runtime requirements:
sudo apt install qml-module-qt-labs-calendar qml-module-qtmultimedia
./bin/digitail -service
./bin/digitail
You should now have a nice little app show up on your desktop which suggests the ability to control tails.
Building an Android APK is done using KDE's Craft system (which uses the KDE Android docker for Qt 5.15). The blueprints for this can be found at the following repository, which also includes instructions for how to perform the build:
https://github.com/MasterTailer/craft-blueprints-thetailcompany