Qt and the unu dashboard

10.11.2020 Tobias Nätterlund No comments

KDAB has been working closely together with unu to create the dashboard application for their next-generation of electric scooters. You can find out about these affordable, innovative, urban transport solutions and book a test ride here.

unu is now launching the scooters. So in this blog post, we will have a look at some of the internals of the dashboard application to see what is going on behind the scenes while driving. We will see how the data travels from the physical scooter hardware up to the UI layer of the dashboard application, by using Qt’s meta-object functionality on parts of the journey.

Structure

The software on the unu scooter is split up into multiple services. Among them are a service for communicating with the engine, a service dealing with the batteries, a service for communicating with the cloud, or the actual dashboard, which is also considered a service in this context. All of these services need to communicate with each other as well. (e.g. the dashboard needs to be able to show the speed of the engine and the battery charge.) In the center of it all is a Redis server, to which each service writes their specific values and other services read them and act accordingly.

The Redis server is a datastore and, to some extent, a message broker. Amongst many, it has support for hashes as well as a Publish/Subscribe mechanism. Both are used extensively by the unu software. The hashes are very similar to Python/C++ hashes, as they are maps with fields/keys associated with values.

This communication is all bidirectional, as the services can both read and write values. As an example, the dashboard routinely reads several values from Redis, but also informs the other services when it is ready by writing a specific value to the dashboard group.

All values are grouped together, depending on which area/service they belong to. The vehicle group contains general vehicle information, such as brake usage and kickstand position. This group is updated by the vehicle service. The battery group contains information on things like battery charge, whether the battery is present and active, and the number of charge cycles. This group is handled by the battery service.

These groups are then treated like hashes on the Redis side. This means, for most values, we use HGET and HSET for reading and writing data.

The following will fetch the charge for the first battery:

127.0.0.1:6379> HGET battery:0 charge # Query
"100"                                 # Response

Dashboard application

Now we need to tie the values in the Redis database to the UI layer, as we need to be able to see the battery charge on the display.

The dashboard application itself consists of multiple layers. At the very bottom, we have the Redis communication layer, which handles actually talking to the Redis server. On top of that sits the classes representing the various Redis groups, described in further detail below. The two top layers are on the UI side, where the bottom of the two handles the UI logic in C++, while the top-most layer is the QML UI.

We have already touched on how the values are grouped by area/service and stored in hashes in Redis. This grouping is also represented in the dashboard code. There is one C++ class for each Redis hash, each of them containing a number of properties. Each property represents one of the fields in the Redis hash, but we only list the ones we are interested in. (e.g. since the dashboard doesn’t care about how many charge cycles a battery has been through, there is no representation of that in the dashboard code.)

class BatteryService : public Service {
    Q_OBJECT

    Q_PROPERTY(bool present READ present WRITE setPresent NOTIFY presentChanged)
    Q_PROPERTY(bool active READ active WRITE setActive NOTIFY activeChanged)
    Q_PROPERTY(int charge READ charge WRITE setCharge NOTIFY chargeChanged)

public:
    explicit BatteryService(int batteryNumber, QObject* parent = nullptr);

    bool present() const;
    void setPresent(bool present);

    bool active() const;
    void setActive(bool active);

    int charge() const;
    void setCharge(int charge);

signals:
    void presentChanged(bool present);
    void chargeChanged(int charge);
    void activeChanged(bool active);

private:
    bool m_present = false;
    bool m_active = false;
    int m_charge = 0;
};

As can be seen, there is nothing special about this class, apart from which baseclass it is using. It has a number of properties, all matching what is in Redis, and the corresponding setters, getters, members, and signals for these properties.

There are a few design decisions involved in this approach:

• Q_PROPERTY allows us to dynamically fetch which Redis values to query for, through QMetaObject/QMetaProperty.
• Read/write accessors are necessary for C++ access, as the values will be read by the dashboard application UI layer and written by the Redis communication layer. The getters/setters are all trivial. So, we could technically also use a plain

  Q_PROPERTY(bool present MEMBER m_present NOTIFY presentChanged)

  approach, but then we would have to use QObject::property()/setProperty() for reading/writing the values. Explicit accessors make more performant C++ code. At the same time, they get compile-time checks with the cost of having a bit more code in each Service subclass.

Let’s also take a look at parts of the baseclass, Service:

class Service : public QObject {
    Q_OBJECT

public:
    explicit Service(const QString& group, QObject* parent = nullptr);

    QString group() const;
    QVector<ServiceProperty> serviceProperties() const;

    // ...

protected:
    void setServiceKey(const char* property, const QString& serviceKey);
    void setFlag(const char* property, ServiceProperty::Flag flag, bool on = true);
    void setUpdateFrequency(const char* property, int updateFrequency);
    // ...

private:
    void initialize();

    // ...

    QString m_group;
    QVector<ServiceProperty> m_serviceProperties;
};

• The “group” passed into the constructor matches the name of the Redis hash we want to query.
• We keep a vector of ServiceProperty elements. This vector is lazily initialized when it’s first needed, through a call to Service::initialize(). The ServiceProperty is a thin wrapper around QMetaProperty. It corresponds to each of the properties in the subclass. At the same time, it also contains details around update frequency, various flags (explained in further detail below), and the Redis field name, should it have to be different from the property name. On initialization, we will iterate over the properties defined above and construct the corresponding ServiceProperty instances:

  void Service::initialize()
  {
      auto mo = metaObject();
      for (int i = mo->propertyOffset(); i < mo->propertyCount(); ++i) {
          const QMetaProperty metaProp = mo->property(i);
          m_serviceProperties.push_back({ metaProp });
      }
  }

  ServiceProperty has sane defaults for the flags and the update frequency. So, when it is first constructed, we only need to specify which QMetaProperty it should wrap.

  Calling metaObject() gives us the QMetaObject for the subclass at hand, as metaObject() is virtual. Additionally, since we are only interested in the properties from that specific subclass, we start the iteration at QMetaObject::propertyOffset(). Had we started from 0, we would see all properties from all baseclasses. This would bring with it QObject::objectName, which we definitely don’t want to ask the Redis server about.

• The Service subclasses use setServiceKey, setFlag and setUpdateFrequency to specify further details for a given ServiceProperty, should it be necessary. By default, the service key (a.k.a. Redis field name) is the property name. Also, the flags specify to update the value with a 1 second interval. For specific properties, we need more frequent updates (e.g. the speed value). For others, we don’t need values every second (e.g. odometer). Those are tweaked individually by setting different flags for these properties.
• The flags control how the value queries from Redis. As an example, not all values should be fetched continuously, but only when there is a specific PUBLISH message being sent from Redis. Looking at the BatteryService constructor, we can see it in action:

  BatteryService::BatteryService(int batteryNumber, QObject* parent)
      : Service(QString::fromLatin1("battery") + QString::number(batteryNumber), parent)
  {
      setFlag("present", ServiceProperty::Flag::UpdateOnlyOnPublish);
      setFlag("active", ServiceProperty::Flag::UpdateOnlyOnPublish);
  }

  Hence, for the dashboard to actually read the “present” or “active” field from Redis, the service handling the battery communication has to invoke two Redis commands:

  HSET battery:0 present true
  PUBLISH battery present

Redis communication

With each and every group represented by a Service subclass, and all relevant fields in those groups represented by Q_PROPERTY’s in those subclasses, we can use this information to query the Redis server. A class called RedisServiceSubscriber does the querying. All Service subclasses register to RedisServiceSubscriber. It uses Service::serviceProperties() to get the list of properties to query for.

Two different mechanisms trigger the querying, depending on whether the property should be updated continuously or only on a PUBLISH message being received.

Continuous updates

The RedisServiceSubscriber contains one timer that controls the querying, but not all properties are updated on every timeout of the timer, as the update interval can be different for each property. The timer interval is rather decided by calculating the greatest common interval between all ServicePropertys, and giving each property a tick number on when to update. One common timer for everything was chosen instead of having one timer per service, or even one timer per property, in order to decrease overall timer usage.

Only on PUBLISH

Redis provides a Publish/Subscribe mechanism which operates on channels. There is one channel per service, and the RedisServiceSubscriber subscribes to each of these channels. When a message is received on a given channel, it contains the property to update, and at that point we trigger the update for that particular property.

As mentioned before, in most cases we use the HGET command to fetch the values from Redis. This is the same no matter if the update was triggered by the timer or through a PUBLISH message. HGET takes two parameters: key and field. The key is what we have been referring to as the groups, and the field would be the property we want to read.

When using HGET, the value we get back from Redis is a string. This includes integer or boolean values as well, e.g. “true” and “50” are all expected results from Redis.

As we have each QMetaProperty wrapped in ServiceProperty, we can use QMetaProperty::write(QObject *object, const QVariant &value) to update the value of the property with what was returned from Redis. This ensures calling the matching setter function for our property. Additionally, since write() takes a QVariant, we can let QVariant handle the type-conversion, passing in our string we got back from Redis unchanged. Then, we can et QVariant convert it to floats, integers or booleans as necessary, to match the type of the property.

If you want to add additional fields to query for in Redis, it’s as easy as adding another Q_PROPERTY to one of the Service subclasses, and vice versa. Should there no longer be a need to know about a specific Redis field, you can remove the corresponding Q_PROPERTY to take care of no longer querying for it.

UI layer

The dashboard application UI is implemented in QML/Qt Quick. QML/Qt Quick heavily relies on properties for getting data from the C++ side to the QML side. Hence, we could simply expose our various Service subclasses to QML, to tie together the UI layer with the data coming from Redis.

However, this has (at least) two downsides to it:

1. The API exposed to QML does not match what the QML code is allowed to do. The QML code should, in a majority of cases, not have write access to the properties. Those are only supposed to be written by the Redis query mechanism. We are, therefore, exposing implementation details that are not relevant to the QML layer.
2. Since the Service classes are raw representations of what is in the Redis database, there are situations where extra logic is needed on top, in order to show correct data on the dashboard. (e.g. the battery display at the bottom of the screen needs information on how many batteries are present in order to draw the correct amount of batteries.) This information is not available directly in Redis, but can be inferred from whether battery:0 and/or battery:1 is present. This logic could go into the QML side, but we’d rather put it in C++, to separate the logic from the UI.

Hence, we wrap the BatteryService instances for the first and second battery in a BatteryInformation class that exposes the necessary data to QML:

class BatteryInformation : public QObject {
    Q_OBJECT

    Q_PROPERTY(int batteryCount READ batteryCount NOTIFY batteryCountChanged)
    Q_PROPERTY(int batteryACharge READ batteryACharge NOTIFY batteryAChargeChanged)
    Q_PROPERTY(int batteryBCharge READ batteryBCharge NOTIFY batteryBChargeChanged)
    // ...

public:
    explicit BatteryInformation(QObject* parent = nullptr);

    void setBatteryA(BatteryService* service);
    void setBatteryB(BatteryService* service);

    int batteryCount() const;
    int batteryACharge() const;
    int batteryBCharge() const;
    // ...

signals:
    void batteryCountChanged(int batteryCount);
    void batteryAChargeChanged(int batteryACharge);
    void batteryBChargeChanged(int batteryBCharge);
    // ...

private:
    BatteryService* m_batteryA = nullptr;
    BatteryService* m_batteryB = nullptr;
};

Then we can infer, for example, the number of batteries from the state of the two battery services by checking each battery’s “present” property.

We do see more code, but as stated above, we now have a cleaner API towards QML (writing to the properties is not allowed) and the logic for the battery count is now in C++, where it belongs.

The BatteryInformation class is registered to QML with a call to qmlRegisterSingletonType under the name “BatteryInformation.” Then, you can display the battery charge for the first battery in the dashboard application UI as easily as by using the QML code below.

Text {
    text: qsTr("Battery charge: %1 %").arg(BatteryInformation.batteryACharge)
}

And to see it in all of its glory:

See our video about the work we did for the Qt-based-UI for unu’s first generation scooters.