The BLOCKS SDK
The standalone BLOCKS SDK

The easiest way to get started developing BLOCKS applications is to use the JUCE framework, but if you would prefer not to use JUCE directly the standalone BLOCKS SDK can be obtained from the BLOCKS-SDK repository.

The most straightforward way to use the SDK is to compile the SDK source code into a static library. Then, in your BLOCKS application code, you can use the header files in the SDK to give you access to the BLOCKS classes and functions. Finally, when you want to compile your application, you must link against the static library to get all the BLOCKS functionality.

Building the SDK library

The source code for the BLOCKS SDK library is contained within the SDK directory of the BLOCKS-SDK repository. Here you will find header files that you can include in your own projects and the Build subdirectory contains an XCode project, a Visual Studio project and a Linux Makefile for compiling the SDK source code into a static library. Use the appropriate choice for your platform, select either the "Debug" or "Release" configuration, and build the project.

For MacOS this will produce libBLOCKS-SDK.a in either the SDK/Build/MacOS/Debug/ or SDK/Build/MacOS/Release/ directory, for Linux this will produce libBLOCKS-SDK.a in either the SDK/Build/Linux/Debug/ or SDK/Build/Linux/Release/ directory, and for Windows this will produce BLOCKS-SDK.lib in either the SDK\Build\Windows\x64\Debug or SDK\Build\Windows\x64\Release folder.

Using the SDK header file

To use BLOCKS classes and functions in your application you must include the BlocksHeader.h file in your source code. You also need to tell the compiler to look in the SDK directory for additional header files, which you can configure inside your XCode or Visual Studio project. If you are using the command line to compile your application then you can see an example of how to do this in examples/BLOCKS-SDK/BlockFinder/Linux/Makefile (which is also configured for MacOS, despite being located inside the Linux directory).

Linking against the SDK library

You must also tell your compiler where to find the SDK static library before your BLOCKS application will compile, and include all of the dependencies for your platform, which are listed in the Standalone SDK dependencies section. Again, this is configured in your XCode or Visual Studio project, but if you are using the command line you can see an example of how to do this in examples/BLOCKS-SDK/BlockFinder/Linux/Makefile (which, again, is also configured for MacOS).

An example application

The source code for this example can be found in the BLOCKS-SDK repository at examples/BlockFinder/, with the parts that are specific to different operating systems in the corresonding subdirectories.

The main functionality of the application is contained within the following class:

BlockFinder/BlockFinder.h:

/*
==============================================================================
This file is part of the JUCE library.
Copyright (c) 2017 - ROLI Ltd.
JUCE is an open source library subject to commercial or open-source
licensing.
The code included in this file is provided under the terms of the ISC license
http://www.isc.org/downloads/software-support-policy/isc-license. Permission
To use, copy, modify, and/or distribute this software for any purpose with or
without fee is hereby granted provided that the above copyright notice and
this permission notice appear in all copies.
JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
DISCLAIMED.
==============================================================================
*/
#pragma once
#include <BlocksHeader.h>
// Monitors a PhysicalTopologySource for changes to the connected BLOCKS and
// prints some information about the BLOCKS that are available.
class BlockFinder : private juce::TopologySource::Listener
{
public:
// Register as a listener to the PhysicalTopologySource, so that we receive
// callbacks in topologyChanged().
BlockFinder();
private:
// Called by the PhysicalTopologySource when the BLOCKS topology changes.
void topologyChanged() override;
// The PhysicalTopologySource member variable which reports BLOCKS changes.
juce::PhysicalTopologySource pts;
};

BlockFinder/BlockFinder.cpp:

/*
==============================================================================
This file is part of the JUCE library.
Copyright (c) 2017 - ROLI Ltd.
JUCE is an open source library subject to commercial or open-source
licensing.
The code included in this file is provided under the terms of the ISC license
http://www.isc.org/downloads/software-support-policy/isc-license. Permission
To use, copy, modify, and/or distribute this software for any purpose with or
without fee is hereby granted provided that the above copyright notice and
this permission notice appear in all copies.
JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
DISCLAIMED.
==============================================================================
*/
#include "BlockFinder.h"
using namespace juce;
BlockFinder::BlockFinder()
{
// Register to receive topologyChanged() callbacks from pts.
pts.addListener (this);
}
void BlockFinder::topologyChanged()
{
// We have a new topology, so find out what it isand store it in a local
// variable.
BlockTopology currentTopology = pts.getCurrentTopology();
Logger::writeToLog ("\nNew BLOCKS topology.");
// The blocks member of a BlockTopology contains an array of blocks. Here we
// loop over them and print some information.
Logger::writeToLog (String ("Detected ") + String (currentTopology.blocks.size()) + " blocks:");
for (auto& block : currentTopology.blocks)
{
Logger::writeToLog (String(" Description: ") + block->getDeviceDescription());
Logger::writeToLog (String(" Battery level: ") + String (block->getBatteryLevel()));
Logger::writeToLog (String(" UID: ") + String (block->uid));
Logger::writeToLog (String(" Serial number: ") + block->serialNumber);
}
}

All this class does is create a PhysicalTopologySource and register for TopologySource::Listener::topologyChanged() callbacks—for more information about how this works you should see the Discovering BLOCKS section. When the topology changes we print some information about the available BLOCKS.

The main function of the MacOS application is the easiest to understand.

BlockFinder/MacOS/main.mm:

/*
==============================================================================
This file is part of the JUCE library.
Copyright (c) 2017 - ROLI Ltd.
JUCE is an open source library subject to commercial or open-source
licensing.
The code included in this file is provided under the terms of the ISC license
http://www.isc.org/downloads/software-support-policy/isc-license. Permission
To use, copy, modify, and/or distribute this software for any purpose with or
without fee is hereby granted provided that the above copyright notice and
this permission notice appear in all copies.
JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
DISCLAIMED.
==============================================================================
*/
#include "../BlockFinder.h"
#import <Cocoa/Cocoa.h>
int main (int argc, const char * argv[])
{
// Initialise the JUCE code.
juce::ScopedJuceInitialiser_GUI platform;
// Create our JUCE object.
BlockFinder finder;
// Run an event loop.
while ([[NSRunLoop currentRunLoop] runMode:NSDefaultRunLoopMode beforeDate:[NSDate distantFuture]]);
return 0;
}

Here we simply perform some JUCE initialisation, instantiate a BlockFinder class, then run the event loop. Whilst in the event loop, the finder object receives TopologySource::Listener::topologyChanged() callbacks and we see output printed to stdout when BLOCKS are connected or disconnected.

Standalone SDK dependencies

  • A C++11 compatible compiler

MacOS frameworks

  • Accelerate
  • AudioToolbox
  • CoreAudio
  • CoreMIDI

Linux packages

  • x11
  • alsa
  • libcurl