Technical Overview and Terminology

This document will go through, in detail, how the Flic 2 and its libraries work.

The physical button, Flic, will in this document be referenced to as both Flic and "the button" interchangeably. The phone, tablet, or computer used to connect to a button will be referenced as a "device".

The framework consists of two classes, a Manager class and a Button class. The manager keeps track of all the buttons that are associated with the particular device and app. It remembers all the paired buttons and makes sure to preserve them in the event of an application crash or termination. Pairing a button is as easy as creating a manager and starting a scan. Whenever a nearby Flic is found, a button object is created and assigned to that particular Flic. All click events triggered on the Flic will be delivered to the user via that button object.

All Flics will be verified as genuine by the library before you receive any trigger events. This is mainly needed in order to make sure that all events that are delivered through the API originates from a genuine button and not fake/corrupt hardware. The Verification Process section further down in this document will go through this in more detail.

Advertising

When the Flic is not connected to a device then the only way for it to be discovered and connected to is through advertising. Advertising is the button's way of letting it's surrounding know that it is available. Typically if the Flic is not connected then the advertisement would start on a button press and then go on until either a device connects to it or until it reaches a certain timeout that is dependent on what mode the Flic is configured to be in. If the Flic's LED flashes orange (or red if there are no pairings stored) when it is pressed, then it means that it is advertising and thus not yet connected.

Pending Connection

A pending connection is a non timeout connection request on the device that is constantly waiting for a certain Flic to appear. Once the phone discovers the button's advertisements it will immediately connect to it. If the connection is successful, then the connection state of the button object will switch to connected. Typically a pending connection will occur either if a user calls the connect method on the Button object or if it was connected before but the connection was lost. More information on the available modes can be found further down in this document.

Connected

The connected state is the only state in which the Flic and the device can exchange data. The connected state is not the same as being verified/ready. As mentioned, a button will only forward events after it has been verified, which is notified by a ready callback. Typically this verification only takes a few milliseconds.

Disconnected

The disconnected state is the state where the Flic and the device are not connected to each other, nor looking for each other. This state consumes no power on the device and minimal power on the Flic, provided that the advertisement has not manually been started again by the user.

Flic Trigger Modes

For Flic we have defined five different trigger events that can be sent when a user interacts with a button. These events are the following:

• Down
• Up
• Click
• Double Click
• Hold

To make all of these events work together in an uncomplicated way we have three different trigger modes (settings) that you as a developer can choose between depending on what fits your application the best. They are described in more detail in the API documentation for each platform. Regardless of which mode you want to use, Down and Up will always be available as well.

Verification Process

Before a user can start using a Flic it has to go through a verification process in order to verify the authenticity of both the Flic itself, as well as the software that it communicates to. The main purpose of this is to allow the and user to feel secure that all the events that are delivered through the framework originates from a genuine Flic button. For a lot of use-cases this is critical.

In short, the verification process is there in order to facilitate the following needs:

• The App to verify the authenticity of the Flic, and verify that it is allowed to communicate with this particular Flic.
• The Flic to verify the authenticity of the App (if already paired), to make sure that events are delivered to the correct device and app.

Full Verification

The full verification process (pairing setup) has to be completed on each Flic one time before it can be used. This will be done on the first connect to a new device. During this process a cryptographic key exchange will occurs between the Flic and the app. These keys will then be used on each subsequent connections (see Quick Verify below). When complete, you will get the Ready callback. If, for some reason, something goes wrong during this process then an error callback will be sent.

Quick Verification

The quick verification process (pairing verification) will be performed each time a previously verified Flic connects to a device, no matter the reason for it. The purpose of this is to verify that it is the same Flic that reconnects and that it is not a fake/corrupt hardware trying to spoof, or replay, a connection. This process typically only takes a few milliseconds. An error callback will be sent here if something goes wrong.

Privacy Modes

The Flic has two different privacy modes that it can operate in, Public and Private:

• Public Mode

  A temporary mode. A Flic will only accept new pairings from Apps when it is in public mode. Buttons that are in public mode will advertise a separate pairing service identifier that allows them to be discovered by the Manager's scan wizard.

• Private Mode

  The default mode. A Flic that is in private mode will not accept any new pairings to be made. Only apps that are already paired will be allowed to connect. While in this mode, the button will never advertise the pairing service identifier which means that it will not be discovered by the Manager's scan wizard. This prevents apps from accidentally connecting to buttons that belong to someone else.

Switching Between Modes

If the button is in the private mode then it can only be switched to public by:

• Pressing down on the Flic and holding it for at least 6 seconds.
• Pressing down on the Flic and holding it for at least 1.5 seconds when a Flic is brand new or factory reset.

Once switched, the Flic will stay in the public state for up to 30 seconds. After this, it will go back to private.

Factory reset

If you for some reason want to perform a factory reset of the Flic then it can be achieved by following these steps:

1. Remove the battery of the Flic.
2. Insert the battery again.
3. Within 5 seconds of inserting the battery, push down on the Flic and keep it pressed for at least 10 seconds. Upon release the button will disconnect from any connected device, reset its memory, then reboot. A few red blinks on the LED will confirm this.

Resetting the button will set it back to the factory default setting and all pairing will be removed.

Battery Usage

When it comes to battery usage there are a few things that are important to know about in order to minimize the battery usage on both the Flic and the device. The key thing is to always choose the most battery conservative implementation that works with your application. For example, if you are developing a real-time game that only runs in the foreground, then you should make sure to disconnect the button whenever the app is no longer in the foreground. It would not make sense to keep an active connection beyond that point.

Scanning

In each of our frameworks we provide a scan wizard that takes care of the scanning and pairing of new buttons. Scanning should ideally only occur when a user explicitly wants to add a new button. We do not recommend running any sort of automatic, or scheduled, scanning in your app. Scanning in the background of a mobile app is not recommended.

On Board LED

The Flic has an on board LED that can be used whenever it is connected. The LED is by far the most power consuming component on the Flic so we recommend that you don't use it too frequently. By default the Flic's LED will shine orange when it is advertising. If a connection is established, it will blink green when the button is pressed.

Network Data Usage

The frameworks will only use a network connection for their automatic firmware update feature (see Firmware update). We do not use the network connection for any other purposes.

Firmware Update

The framework will occasionally poll our backend server to see if there is a new firmware upgrade available for the Flic buttons. This is an important feature since it will allow us to automatically upgrade to new firmware versions seamlessly in the background in case a new, and better, firmware is available. For bulk orders of Flic buttons (possibly white-label orders) you have option to choose if, or when, a new firmware version will be pushed out to your specific buttons. This may for example be in case your company wants to quality assure the new firmware first.

Further Reading

If you are interested learn more about how the Flic 2 protocol works, then you may have a look at the Flic 2 Protocol Specification document.