BlocksMonitor

Introduction

BlocksMonitor is a simple JUCE application that shows currently connected Lightpad and Control Block devices and visualises touches and button presses. It also displays some basic information about the Blocks.

Generate a Projucer project from the file located in the examples/ folder, then navigate to the BlocksMonitorDemo/Builds/ directory and open the code project in your IDE of choice. Run the application and connect your Blocks (if you do not know how to do this, see Connecting BLOCKS). Any devices that you have connected should now show up in the application window and this display will be updated as you add and remove Blocks. Lightpads are represented as a black square and will display the current touches as coloured circles, the size of which depend on the touch pressure, and Control Blocks are shown as rectangles containing the LED row and clickable buttons on the hardware. If you hover the mouse cursor over a Block, a tooltip will appear displaying the name, UID, serial number and current battery level.

The BlocksMonitor application with a Lightpad and 3 Control Blocks connected

Topology

One of the fundamental concepts of the BLOCKS API is topology - a topology is a set of physically connected Blocks and the connections between them. Knowing when the topology has changed and accessing a data structure containing the current topology is the basis of any Blocks application.

To access the current topology, BlocksMonitorDemo inherits from the TopologySource::Listener base class [1] and implements the TopologySource::Listener::topologyChanged() method [2], a callback which is used to inform listeners when any physical devices have been added or removed.

class BlocksMonitorDemo   : public Component,
                            public TopologySource::Listener, // [1]
                            private Timer
{
public:
//...
    void topologyChanged() override                          // [2]
    {
    //...

In order to receive these callbacks, BlocksMonitorDemo contains an instance of the PhysicalTopologySource class [3] and registers itself as a listener to this object in its constructor [4].

    BlocksMonitorDemo()
    {
        //...
        topologySource.addListener (this);          // [4]
        //...
    }
 
private:
    //...
    PhysicalTopologySource topologySource;          // [3]
    OwnedArray<BlockComponent> blockComponents;
    BlockComponent* masterBlockComponent = nullptr;
//...

When the topologyChanged() method is called, this object can be used to access the updated topology through the PhysicalTopologySource::getCurrentTopology() method [5] which returns a BlockTopology struct containing an array of currently connected Block objects and an array of BlockDeviceConnection structs representing the connections between them.

void topologyChanged() override
{
    //...
    auto topology = topologySource.getCurrentTopology(); // [5]
    //...
}

The Block Object

The array of Block objects contained in the BlockTopology struct can be used to access individual Block objects [1] and determine their type using the Block::getType() method [2].

for (auto& block : topology.blocks) // [1]
{
    if (auto* blockComponent = createBlockComponent (block))
    {
        //...
    }
}

The application uses this information to construct an on-screen representation of the currently connected Blocks by creating either a LightpadComponent object [3] or a ControlBlockComponent object [4] for each Block in the current topology.

BlockComponent* createBlockComponent (Block::Ptr newBlock)
{
    auto type = newBlock->getType();                 // [2]
 
    if (type == Block::lightPadBlock)
        return new LightpadComponent (newBlock);     // [3]
 
    if (type == Block::loopBlock || type == Block::liveBlock
        || type == Block::touchBlock || type == Block::developerControlBlock)
        return new ControlBlockComponent (newBlock); // [4]
 
    jassertfalse;
    return nullptr;
}

Both of these classes derive from BlockComponent, a relatively simple base class that contains some virtual functions for painting the Block on screen and handling callbacks from the touch surface and/or buttons on the Block.

class BlockComponent : public Component,
                       //...
{
public:
    //...
    virtual void paint (Graphics&) override = 0;
    virtual void handleButtonPressed  (ControlButton::ButtonFunction, uint32) {}
    virtual void handleButtonReleased (ControlButton::ButtonFunction, uint32) {}
    virtual void handleTouchChange (TouchSurface::Touch) {}
    virtual void handleBatteryLevelUpdate (float) {}
    //...

In its constructor, BlockComponent takes a pointer to the Block object that it represents and adds itself as a listener to the touch surface (if it is a Lightpad) and buttons using the Block::getTouchSurface() and Block::getButtons() methods, respectively.

BlockComponent (Block::Ptr blockToUse)
    : block (blockToUse)
{
    //...
    if (auto touchSurface = block->getTouchSurface())
        touchSurface->addListener (this);
 
    for (auto button : block->getButtons())
        button->addListener (this);
    //...
}

It inherits from the TouchSurface::Listener and ControlButton::Listener classes and overrides the TouchSurface::Listener::touchChanged(), ControlButton::Listener::buttonPressed() and ControlButton::Listener::buttonReleased() methods to call its own virtual methods, which are implemented by the LightpadComponent and ControlBlockComponent classes to update the on-screen components.

class BlockComponent : public Component,
                       public SettableTooltipClient,
                       private TouchSurface::Listener,
                       private ControlButton::Listener,
                       private Timer
{
private:
    //...
    void touchChanged (TouchSurface&, const TouchSurface::Touch& t) override { handleTouchChange (t); }
    void buttonPressed  (ControlButton& b, Block::Timestamp t) override      { handleButtonPressed  (b.getType(), t); }
    void buttonReleased (ControlButton& b, Block::Timestamp t) override      { handleButtonReleased (b.getType(), t); }
    //...

To visualise touches on the Lightpad, LightpadComponent contains an instance of the TouchList class called touches and calls the TouchList::updateTouch() method whenever it receives a touch surface listener callback in the LightpadComponent::handleTouchChange() method.

class LightpadComponent   : public BlockComponent
{
public:
    //...
    void handleTouchChange (TouchSurface::Touch touch) override { touches.updateTouch (touch); }
 
private:
    //...
    TouchList<TouchSurface::Touch> touches;
    //...

The LightpadBlock::paint() method then iterates over the current TouchSurface::Touch objects in the TouchList and visualises them on the component at 25Hz.

void paint (Graphics& g) override
{
    //...
    for (auto touch : touches)
    {
        //...
    }
}

The ControlBlockComponent class represents a generic Control Block with 15 LEDs, 8 circular buttons and 1 rounded rectangular button. When a button is pressed on the physical Control Block, the BlockComponent::handleButtonPressed() function is called and this class uses the ControlButton::ButtonFunction variable to determine which button was pressed and should be activated on the on-screen component.

void handleButtonPressed  (ControlButton::ButtonFunction function, uint32) override
{
    displayButtonInteraction (controlButtonFunctionToIndex (function), true);
}

The same process is repeated for when the button is released.

void handleButtonReleased (ControlButton::ButtonFunction function, uint32) override
{
    displayButtonInteraction (controlButtonFunctionToIndex (function), false);
}

This class also overrides the BlockComponent::handleBatteryLevelUpdate() method to update which LEDs should be on based on the battery level, which is accessed in the BlockComponent base class using the Block::getBatteryLevel() and Block::isBatteryCharging() methods.

void handleBatteryLevelUpdate (float batteryLevel) override
{
    auto numLedsOn = static_cast<int> (numLeds * batteryLevel);
 
    if (numLedsOn != previousNumLedsOn)
        for (auto i = 0; i < numLeds; ++i)
            leds.getUnchecked (i)->setOnState (i < numLedsOn);
 
    previousNumLedsOn = numLedsOn;
    repaint();
}

These callback methods are a simple and powerful way to get user input from the Blocks and use this data to drive some process in your application. In this example, the input is simply mirrored on the screen but it could be used to control any number of things such as audio synthesis (see the BlocksSynth example) and graphics (see the BlocksDrawing example).

Blocks Connections

The BlockTopology struct returned by the PhysicalTopologySource::getCurrentTopology() method also contains an array of BlockDeviceConnection objects representing all the current DNA port connections between Blocks in the topology. A single BlockDeviceConnection struct describes a physical connection between two ports on two Blocks and contains a Block::UID and Block::ConnectionPort object for each of the two devices.

This information is used to calculate the position and rotation of each connected Block and update the corresponding topLeft and rotation member variables of its BlockComponent so that the correct topology is displayed on the screen. The topLeft variable is a Point that describes the position of the top left of the BlockComponent in terms of logical device units relative to the top left of the master Block at Point (0, 0).

int rotation = 0;
Point<float> topLeft = { 0.0f, 0.0f };

Initially, all BlockComponent instances have the topLeft position (0, 0) and the BlocksMonitorDemo::positionBlocks() method iterates first over all of the Blocks connected to the master Block and then any remaining Blocks and calculates the correct topLeft Point and rotation for each using the array of BlockDeviceConnection objects.

void positionBlocks (BlockTopology topology)
{
    //...
    Array<BlockDeviceConnection> masterBlockConnections;
    for (auto connection : topology.connections)
        if (connection.device1 == masterBlockComponent->block->uid || connection.device2 == masterBlockComponent->block->uid)
            masterBlockConnections.add (connection);
 
    while (maxDelta > 0.001f && --maxLoops)
    {
        //...
        for (auto connection : masterBlockConnections)
        {
            //...
            for (auto otherBlockComponent : blockComponents)
            {
                //...
            }
        }
    }
 
    Array<BlockComponent*> unpositionedBlocks;
    for (auto blockComponent : blockComponents)
        if (blockComponent != masterBlockComponent && ! blocksConnectedToMaster.contains (blockComponent))
            unpositionedBlocks.add (blockComponent);
 
    if (unpositionedBlocks.size() > 0)
    {
        //...
        while (maxDelta > 0.001f && --maxLoops)
        {
            //...
            for (auto blockComponent : unpositionedBlocks)
            {
                Array<BlockDeviceConnection> blockConnections;
                for (auto connection : topology.connections)
                    if (connection.device1 == blockComponent->block->uid || connection.device2 == blockComponent->block->uid)
                        blockConnections.add (connection);
 
                for (auto connection : blockConnections)
                {
                    //...
                    for (auto otherBlockComponent : blockComponents)
                    {
                        //...
                    }
                }
            }
        }
    }
}

Then, in the BlocksMonitorDemo::resized() method these attributes are used to correctly position the components.

void resized() override
{
    //...
    if (numBlockComponents == 0)
    {
        //...
        return;
    }
 
    //...
    if (isInitialResized)
    {
        //...
        for (auto blockComponent : blockComponents)
        {
            auto topLeft = blockComponent->topLeft;
            auto rotation = blockComponent->rotation;
            //...
        }
 
        //...
        masterBlockComponent->centreWithSize (...);
        //...
    }
    else
    {
        masterBlockComponent->setSize (...);
    }
 
    for (auto blockComponent : blockComponents)
    {
        if (blockComponent == masterBlockComponent)
            continue;
 
        blockComponent->setBounds (...);
 
        if (blockComponent->rotation != 0)
            blockComponent->setTransform (AffineTransform::rotation (...));
    }
}

Summary

This tutorial and the accompanying code has introduced the BlockTopology and Block objects, and demonstrated how to receive callbacks from connected Blocks when the touch surface or buttons are pressed, allowing you to use this input in your own applications.

See also

• BlocksDrawing
• BlocksSynth