Facet

General information

Facet is a menu bar app for macOS, and a system tray app for Linux, that records your time from a TimeFlip2 device. You give each of the device's twelve faces something to work on, and then you put the device down on the face you are working on. There is no timer to start and none to stop. This page is about the one design decision that separates Facet from the other apps that talk to the same device, and the rest of the guide is a page per tab of the Settings window.

A face points at an activity, it is not the activity

Facet keeps three separate things, and the difference between them is the whole point:

  • a face, one of the twelve sides of the device, which holds nothing but a pointer to a category;
  • a category, the thing you are actually working on, with a name, a colour, an icon and optionally a daily limit;
  • an entry, one stretch of recorded time, filed against a category.

Time is recorded against the category. It is never recorded against the face. A face is a physical position on a piece of plastic, and all it ever says is which category is currently reached by putting the device down that way up.

Why that matters if you work in tickets

The usual arrangement in a tracker like this is that the face is the activity: you name face 4, and the name on face 4 is what its time is reported under. That works until the ticket you were on is finished and the next one starts, which for anybody working out of JIRA, Linear or an issue tracker of any kind is roughly every other day.

What goes wrong. Face 4 is named JIRA-1256 and you spend six hours on it. The ticket closes, the next one opens, and you rename face 4 to JIRA-1264, on which you then spend another six hours. Ask for a report and it says twelve hours on JIRA-1264. JIRA-1256 is not on it at all, and not as a row reading zero: the name is gone. It existed in one place, on the face, and you typed over it, so there is nothing left to search for and nothing to ask the report to show you. The first six hours were only ever attached to the face, and the face is called JIRA-1264 now, so the name the report prints is the name it is reading today.

The two figures are not merely mislabelled, they are added together, and no report can take them apart again. Nothing recorded says the face changed name halfway through, so the only way back to six and six is to know the exact moment you renamed it and to narrow the report to either side of it. That means keeping the start and end date of every ticket you have ever put on that face, by hand, forever, and being right about all of them. Pick a range and you can get a figure; the total can never be right again.

In Facet those first six hours belong to a category called JIRA-1256, and face 4 is only a pointer at it. Starting the next ticket means pointing face 4 at a different category, which is a different act entirely: JIRA-1256 holds its six hours, JIRA-1264 holds its own six, and asking for the total on either one is just reading it off. There is no cut-off date to remember, because the two were never in the same bucket.

Setting what a face is for is one gesture: turn the device to the face you want, then click a category in the list on the Faces tab. Nothing is typed, so nothing can collide with a name that already exists. Renaming a category is a different act again, and it is on the Categories page.

You do not need a device to start

Facet works with no device paired, so you can put it to use today and order the hardware later.

There is no mode to turn on and no switch to find. When nothing is paired, Facet times by hand: pick a category on the Faces tab and the clock starts on it. The time goes to the same place a device's time goes, so the status icon reads the same, the reports come out the same, and time recorded before your device arrives is not a second-class kind of time.

Pair a device afterwards and it takes over from that moment, with no restart and nothing to migrate. Forget the device again and the clock comes back to you the same way. If a paired device cannot be found when Facet starts, Facet asks what to do, and one of the answers is to time by hand for that run; the Faces page has the detail.

The status icon

Facet's icon lives in the menu bar on macOS and in the system tray on Linux. It is the app, most of the time: its colour says what mode Facet is in, and hovering over it says what is running and how long it has been running, with no window open. On Linux desktops that can draw text beside a tray icon, such as the MATE panel on Linux Mint, the same line sits beside it.

  • A right click opens the menu: Pause (or Resume), Lock (or Unlock), Settings, About and Quit. On Linux, your desktop decides how its tray menus open. Lock is greyed out unless a device is connected. Pause is greyed out when there is nothing to pause, when the device is locked or not connected, and when resuming would pass a spent daily limit.
  • A left click pauses or resumes whatever is being timed, so you can stop and start the clock without opening anything.
    • While Facet is timing by hand, a click pauses it and another starts it again, immediately.
    • With a device connected, a single click stops the device counting or starts it again, and a quick double click locks the device or unlocks it. The single click waits out the double-click interval, so a second click cancels the pause and becomes the lock rather than doing both. While the device is locked, a single click does nothing: unlock it first.
    • With nothing being timed, a left click does nothing.
  • A category that has spent its daily limit cannot be resumed, from the menu or by clicking. Pausing always works, and so does unlocking the device.

The play or pause symbol carries the colour: cyan while Facet is timing by hand, green while the device is doing the timing, and yellow when a paired device cannot be reached, where the last face it reported is still on show but nothing can confirm it any more. A paused clock is white, or red once the category has spent its daily limit. A red padlock follows the symbol while the device is locked, and a low battery adds low battery to the line you see on hover.

Quitting Facet locks the device, pausing it first when that is set on the Device tab, so nothing is recorded while Facet is closed. After a restart, choose Unlock from the menu, and Resume if the device was paused.

What Facet does not do

Facet has no connection to JIRA or to any other issue tracker. A ticket number in Facet is a category name you typed, nothing reads your board, and nothing is posted back to it. Your categories and your recorded time are held in an ordinary SQLite file on your own computer and are not sent anywhere, with one exception you have to turn on yourself: the optional Google Calendar sync, which is covered in the privacy policy.

The rest of this guide

A page for each tab of the Settings window, in the order the window draws them:

  • Faces. Which category each face is timing, and the clock for the one in use.
  • Categories. Making, naming, colouring and retiring the activities time is recorded against, and setting a daily limit on one.
  • Report. What the recorded time adds up to, per category, over a range of days.
  • App. Facet's own preferences, including when your day starts, the Google Calendar connection, and the debug trace.
  • Device. The device itself: pairing it, its battery and firmware, and the settings that live on the hardware.
  • About. The version, what Facet is built with, and its licences. It is also on the status icon's menu.

Anything else

Questions and faults: facet@tux.com.au. When a fault is easier to show than to describe, the Debug section of the App tab records what Facet did while it went wrong and saves it as one file to send in.