Manage cookies

We use cookies to improve our services. Read more about how we use cookies and how you can refuse them.

The necessary cookies help to make the website work properly.

Anonymous statistical cookies help to understand how visitors use the website.

  • General
    3 min | 3274

    #Timeular: Track your time using an Octahedron on Linux

    General | 3 min | 3274

    Last year, I bought a Timeular tracker and I've been using it the past months to check the time I spent on my activities and plan my days better. Furthermore, on work-from-home days, it's hard to track how many hours I work per day, and the tracker helps me a lot with this! Therefore, I still recommend it.

    I also wrote an article about the tracker and the Timeular application: Timeular: Tracking your time using an Octahedron. Both work great on Windows, Mac OS, and Android. However, Timeular doesn't offer a Linux/Ubuntu application and that's VERY ANNOYING!

    zei in base compressed.png
    Fig 1: ZEI Tracker.

    Thus, if you are using Linux, Timeular recommends using the smartphone application to track your activities. But this is not the same! I've already tried it, but it didn't work as great! My workday was like this: I was at the office, I needed to go outside to have lunch. Therefore, I took my smartphone, went outside and the tracker lost the connection with the phone (the max. range is about 5 meters). The application reported this and the smartphone vibrated. Then, I came back and found that the application didn't synchronize with the tracker (it happened more often than I thought). I had to open the application, and I tried one/two/three times to connect to the tracker, and occasionally it worked again. Sometimes I forgot to do that, and I lost the tracking. On Windows, this wasn't a problem because the tracker stayed connected to the notebook all the time.

    Timeular is offering a beta version for Linux here. I recommend using that. It works well.
    Timeular Application
    Fig 2: Timeular application (MAC/Windows).

    In the published article, I linked a GO application that runs on Linux and connects to the tracker. This worked for me, but it had some issues (sometimes it lost the connection too), and it didn't have any option to enter notes and tags to the task. Therefore, the application tracked the time and I had to edit the tracking using my smartphone to add the extra information. Furthermore, it wasn't very easy to install and that is why, last night, I decided to write an application in Python. This app connects to the tracker and sends the tracking data to the Timeular servers. Timeular offers an API to do that. Thus, I took every code that I found on Github to write an application. So it's not a clean application, but it works even better than the application written using GO. :P

    Software and Hardware

    Run the Application on Linux

    Follow these steps to run the application on Linux (tested on Ubuntu 18.04 LTS).

    1. Install the pre-requisities:
      sudo apt-get install python3-pip libglib2.0-dev python-tk
      sudo pip3 install bluepy

      If the installation of bluepy fails, you should install it from the sources:

      sudo apt-get install git build-essential libglib2.0-dev
      git clone
      cd bluepy
      python3 build
      sudo python3 install
    2. Clone the lemariva/timeular-python repository typing the following:
      git clone
    3. Register and Create an API key on your profile page
    4. Open the application typing:
    5. Click on File > Settings to enter the credentials (apiKey and apiSecret) and the MAC address of your Tracker. You can get the MAC address of your tracker using the menu option Bluetooth > Scan (see Fig. 3). Make sure that the tracker's LED is blinking blue.

      The BLE scanner needs sudo privileges, therefore you need to run the application using:

      sudo python3
    6. Click on Timeular > Connect to connect the app to the tracker and the Timeular servers. The tracker should be also blinking blue to make the connection possible. You don't need any sudo rights here. If you see something like this:
      Connected Succesfully to CC:0A:57:DE:3E:AD
      Connected to

      This means everything is working.

    7. Flip the tracker to start your activity tracking.
    8. If you need to write a note, you can do it in the text box under Note (see. Fig 4). You can include tags using hashtag (e.g. #timeular). Click on Save to send it.
    Create a registry
    Fig. 3: Searching for the Timeular Tracker.
    Create a device
    Fig. 4: Tracking an Activity.
    Limitations: The application is very basic and only connects to Timeular servers to report the position of the tracker. You can't see all of your day's entries, analysis, or link a side of the octahedron to an activity. Integrations are also not supported. These features can be performed using the smartphone application.

    I will no longer develop this application to cover those topics. I think Timeular should be working on a Linux application as soon as possible. I will fix bugs if I find them or you report them. However, if you want to further develop the app, you can fork this repository and even give me pull requests.