Getting Started with Linux

This overview will guide you through the steps required to integrate the BlackBerry Spark Communications Services SDK for Linux with your application.

The SDK for Linux differs from the SDKs for Android and iOS in some ways. On Linux, there are no UI bindings or UI helper classes, nor is there a Support library. Instead, your application speaks directly to the bbmcore component using the BBMDS message-passing protocol and directly controls the media and data call layer with a C++ API.

The SDK for Linux allows you to send and receive custom commands, additional metadata, and other content between your Linux applications and other endpoints. For example, you can control hardware by responding to messages you receive via the SDK. Or, you can report monitoring data that you collect from connected sensors.

Prerequisites

First, follow the steps on the Download & Configure page to download the SDK and then configure your application within your BlackBerry Online Account.

Before adding the SDK to your application, ensure that your project meets the minimum requirements for the operating system, toolchain, and required packages.

Operating System and Toolchain

The SDK for Linux supports desktop or server machines running Debian 9 ("stretch") or Ubuntu 18, and it supports Raspberry Pi 3 devices running Raspbian "stretch". You can develop and test your application on an x86_64 machine and then either deploy your application for that architecture, or cross-compile to armv8-rpi3-linux-gnueabihf for deployment on Raspberry Pi.

The included libraries and example applications were tested on the configurations mentioned above, but they should be compatible with most modern Linux systems that support armv8-rpi3-linux-gnueabihf. See examples/common/common.mk in the SDK package for more details.

You will need a C++ compiler at least as capable as gcc-6.3. The SDK is built to be compatible with the default GNU C++ compiler in Debian and Raspbian version 9 ("stretch") using the system's standard libstdc++. The SDK uses C++14.

Required Packages

You will need some of the operating system's development headers and libraries installed. The SDK itself depends on you installing the following packages.

sudo apt-get install \
  g++ \
  libasound2 \
  libc6 \
  libpulse0 \
  libxcomposite1 \
  libxdamage1 \
  libxfixes3 \
  libxi6 \
  libxtst6 \
  make \
  zlib1g

The SDK example applications add some additional dependencies. The SDK itself does not depend on these, but you will need them to build and run the examples. Install these additional dependencies with the following command.

sudo apt-get install libjsoncpp-dev

When cross-compiling for Raspberry Pi, you will need a "sysroot" that contains the necessary headers and libraries for whatever packages the SDK and your application uses. Setting up a sysroot is beyond the scope of this guide. If you compile natively on the actual Raspberry Pi device, you do not need a sysroot, but compilation will be significantly slower. See examples/common/common.mk in the SDK package for more details.

Extract the SDK

The SDK is packaged as a compressed tar archive. After downloading the package, you can install it by decompressing and expanding the archive in any directory you choose.

tar -zxf blackberry-spark-communications-services-sdk-linux-*.tar.gz

The SDK will be extracted into a directory named after the archive. Within that, you will find two main directories.

Directory	Description
`sdk`	This contains the SDK headers and libraries themselves.
`documents`	This contains a local copy of the BBMDS documentation, as standalone HTML.

Explore the Examples

The easiest way to become familiar with the SDK for Linux is to build and run the example applications.

The examples come with a miniature build system using make. Your application does not need to use this build system. You can configure your project to use the SDK's sdk/include and per-architecture sdk/lib directories with whatever build tools you use.

Clone

The Linux examples are on GitHub. The easiest way to get them and start using them is to clone the Linux examples repository to an examples directory that is beside the sdk directory that was extracted from the SDK package.

cd blackberry-spark-communications-services-sdk-linux-*
git clone https://github.com/blackberry/bb-spark-linux-samples.git examples

Build

To get started, build the Message Echo examples. This is a small example application that registers a new SDK identity (if necessary) and then connects as an SDK endpoint. It then will echo back any messages sent in any chat.

To build it, change to its directory, and type make. The following commands will build Message Echo using all available CPUs.

cd examples/messageEcho
make -j$(nproc)

By default, the examples' build system will find the SDK headers and libraries using relative paths from their known location within the extracted SDK archive. If you cloned the examples to a different location or use the examples' build system for your own programs, you might need to set the SPARK_SDK environment variable to the absolute or relative path of the sdk directory that came in the SDK package.

Configure

The SDK for Linux needs a directory within which it can store persistent files and databases. The Message Echo example uses the ~/.messageEcho directory for its persistent storage. You must create this directory and then create files within it to configure the domain and identity of the endpoint.

The examples select a directory for you, but when you instantiate the SDK in your application, you provide the path to use. You do not have to configure the SDK's domain and identity with files like in the examples.

Create the directory and then create a domain file within it containing the ID of your application's sandbox domain.

mkdir ~/.messageEcho
echo 'YOUR_DOMAIN_ID' > ~/.messageEcho/domain

By default, the examples expect a sandbox domain with user authentication disabled. So, you can assign any user identity at all to this endpoint. To get started, let's assign the identity user1 to this example.

echo user1 > ~/.messageEcho/identity

Each example comes with its own README.md file that explains in detail how to configure its domain, identity, and more, along with an explanation of what the example demonstrates.

Run

The executable binary is placed in the app/x86_64 directory (or the app/rpi directory for Raspberry Pi builds). You can run it directly.

./app/x86_64.g/messageEcho

If it's been configured correctly, then when you run Message Echo, you should see output similar to this:

Configured for user domain 00000000-0000-0000-0000-000000000000.
Follow bbmcore's logs with this command in another terminal:
tail --follow=name /home/user/.messageEcho/logs/bbmcore.txt
Loaded identity for "no authentication" mode from /home/user/.messageEcho/identity
Asking bbmcore to start.
EndpointId is lUGlxLfPaJakEbeJxwrEUgHSlKRMsqmDkmWbKxjBYLaCYGWXMfTwjgYOqsIqdMUz
SyncPasscodeState is None
SetupState is NotRequested
SetupState is Ongoing
Profile regId: 700000000000000000 PIN: 10000000
SyncPasscodeState is New
SetupState is SyncRequired
SetupState is SyncStarted
SyncPasscodeState is None
SetupState is Ongoing
SetupState is Success

The above output is emitted as the example application makes progress initializing the SDK, registering an SDK identity and endpoint, and then connecting as an SDK endpoint. All of that output is from the example application itself. The SDK does not write to the standard output streams, but it does log to a set of self-rotating log files within its persistent storage directory. As indicated by the above output, you can follow those logs with the following command.

tail --follow=name ~/.messageEcho/logs/bbmcore.txt

BlackBerry recommends monitoring the log file like this when developing and testing your application. Errors such as malformed BBMDS messages or other problems are often easy to spot and diagnose simply by reading the log file as you send messages to the SDK. This is most easily done by viewing the logs in color. In most terminals, the following command with colorize the log output as it is displayed.

tail --follow=name ~/.messageEcho/logs/bbmcore.txt \
  |perl -ne '
    BEGIN {
      $c = -1;
      @t = ([97,45],[97,45],[97,41],[30,43],[37,44],[97,40],[37,40],[94,40],[39,49])
    }
    chomp;
    if(/^\d{4}-\d\d-\d\d \d\d:\d\d:\d\d\.\d+ \d+ \d+ \[([0-7])\]: /){ $c = $1; }
    print "\033[".$t[$c][0].";".$t[$c][1]."m$_\033[39;49m\n"'

With this color scheme, important warning messages will be yellow, errors will be red, and critical messages will be magenta. Serious milestones in the application lifecycle or especially noteworthy events will have a blue background. This makes it easy to spot issues during development.

On x86_64, the absolute path to the SDK shared libraries is hard-coded into the executable at build time. This lets you run them without setting LD_LIBRARY_PATH or otherwise installing them libraries system-wide. Raspberry Pi binaries are built with a relative RPATH of . for similar reasons, under the assumption that you will typically copy the cross-compiled binaries and their shared libraries to the same directory during development. Your application does not have to follow this pattern.

By default, the examples' build system will build an optimized release artifact. To build an debuggable binary instead, set the DEBUG variable in the environment or on the make command line. Debug binaries are placed in a slightly different directory.

make DEBUG=1
./app/x86_64.g/messageEcho

Communicate

If you have access to phone or tablet, you can use the RichChat examples for Android or iOS as an interactive endpoint when experimenting with the SDK for Linux. Or, you can use the web version of RichChat from a desktop computer or mobile device. RichChat's full UI will make it easy for you to create chats and send messages to your Linux application endpoints. Configure both RichChat and your Linux applications to use the same domain, but different identities. See the RichChat documentation for details on performing this step and getting it set up.

Once you have RichChat running, use it to start a chat with the identity you configured for your Linux application. Add a contact using the user ID of your Linux application. Then, start a chat with the new contact and send a message to your Linux application.

When we configured the Message Echo example above, we gave it a user ID of user1. When you send it a message, it will echo the text back to you.

This simple Message Echo example will respond only to messages whose tag field is Text. It will also respond only to messages that were sent to the chat after it has joined the chat. If you invite it to a chat and immediately send messages, you create a race condition where those messages could arrive at Message Echo before or after the join. So, wait until you see the Join message from the example's endpoint before posting messages that you want echoed back to you. Of course, in your own application, you can chose to react to messages with any tag or pre-existing messages. Those messages are available to your application, but this simple example has chosen to ignore them.

If you're running Message Echo on a Raspberry Pi, you can also send it a message to control its on-board LEDs. See the README included with that example for more information.

By modifying RichChat to send and receive custom commands, additional metadata, and other content to your Linux applications, you can use it as an interactive testing tool during development.

BlackBerry Spark Communications Services Guide