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
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.
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
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.
Example | Description | Source |
---|---|---|
Message Echo | Build an IoT application that demonstrates how to echo received messages back to the sender and control Raspberry Pi hardware. | Source |
Auto Answer | Build an IoT application that demonstrates how to automatically answer media call requests to build a remote audio and video monitoring camera. | Source |
Endpoint Manager | Build an IoT application that demonstrates the endpoint management APIs. | Source |
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/BlackBerry-Communication-Services-Examples/tree/master/linux.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)
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.
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
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.
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.