C++ Client API Tutorial

Table of Contents

• Overview
• Building
• Streaming Client Sender
• Callback Client Sender
• DMX Receiver

Overview

This page introduces the OLA Client API, and provides sample programs to send and receive DMX512 data from olad.

Building

Once OLA is installed on your system, the examples can be built with:

g++ example.cpp $(pkg-config --cflags --libs libola)

Streaming Client Sender

The quickest way to get started is by using ola::StreamingClient. The program below sends 100 frames of DMX data to the olad server on universe 1. The frames are sent 25ms apart which gives a frame rate of 40 fps.

Each frame consists of 512 DMX data slots. The first slot is incremented by one each frame, the other slots are always 0. This produces the following DMX frames:

  Time (ms)  DMX Data
       0     0,0,0,0,.....
      25     1,0,0,0,.....
      50     2,0,0,0,.....
      75     3,0,0,0,.....
    ....
    2475     100,0,0,0,.....

#include <stdlib.h>
#include <unistd.h>
#include <ola/DmxBuffer.h>
#include <ola/Logging.h>
#include <ola/StreamingClient.h>

#include <iostream>

using std::cout;
using std::endl;

int main(int, char *[]) {
  unsigned int universe = 1;  // universe to use for sending data

  // turn on OLA logging
  ola::InitLogging(ola::OLA_LOG_WARN, ola::OLA_LOG_STDERR);

  ola::DmxBuffer buffer;  // A DmxBuffer to hold the data.
  buffer.Blackout();  // Set all channels to 0

  // Create a new client.
  ola::StreamingClient ola_client((ola::StreamingClient::Options()));

  // Setup the client, this connects to the server
  if (!ola_client.Setup()) {
    std::cerr << "Setup failed" << endl;
    exit(1);
  }

  // Send 100 frames to the server. Increment slot (channel) 0 each time a
  // frame is sent.
  for (unsigned int i = 0; i < 100; i++) {
    buffer.SetChannel(0, i);
    if (!ola_client.SendDmx(universe, buffer)) {
      cout << "Send DMX failed" << endl;
      exit(1);
    }
    usleep(20000);   // sleep for 25ms between frames.
  }
  return 0;
}

While ola::StreamingClient is easy to use it has the drawback that it can only send DMX512 data. It's not possible to retrieve information (like the active universes etc.) from olad using the StreamingClient.

Callback Client Sender

The ola::OlaCallbackClient provides a much richer interface for interacting with the server. However, because of this it's slightly harder to use.

The following code behaves thes same as the Streaming Client Sender example.

#include <ola/DmxBuffer.h>
#include <ola/io/SelectServer.h>
#include <ola/Logging.h>
#include <ola/OlaClientWrapper.h>
#include <ola/Callback.h>

using std::cout;
using std::endl;

bool SendData(ola::OlaCallbackClientWrapper *wrapper) {
  static unsigned int universe = 1;
  static unsigned int i = 0;
  ola::DmxBuffer buffer;
  buffer.Blackout();
  buffer.SetChannel(0, i);
  wrapper->GetClient()->SendDmx(universe, buffer);

  if (++i == 100) {
    wrapper->GetSelectServer()->Terminate();
  }
  return true;
}

int main(int, char *[]) {
  ola::InitLogging(ola::OLA_LOG_WARN, ola::OLA_LOG_STDERR);
  ola::OlaCallbackClientWrapper wrapper;

  if (!wrapper.Setup()) {
    std::cerr << "Setup failed" << endl;
    exit(1);
  }

  // Create a timeout and register it with the SelectServer
  ola::io::SelectServer *ss = wrapper.GetSelectServer();
  ss->RegisterRepeatingTimeout(25, ola::NewCallback(&SendData, &wrapper));

  // Start the main loop
  ss->Run();
}

DMX Receiver

#include <ola/DmxBuffer.h>
#include <ola/Logging.h>
#include <ola/OlaClientWrapper.h>
#include <string>

static const unsigned int UNIVERSE = 1;

// Called when universe registration completes.
void RegisterComplete(const std::string& error) {
  if (!error.empty()) {
    OLA_WARN << "Failed to register universe";
  }
}

// Called when new DMX data arrives.
void NewDmx(unsigned int universe,
            uint8_t priority,
            const ola::DmxBuffer &data,
            const std::string &error) {
  if (error.empty()) {
    OLA_INFO << "Received " << data.Size()
             << " channels for universe " << universe
             << ", priority " << static_cast<int>(priority);
  } else {
    OLA_WARN << "Receive failed: " << error;
  }
}

int main() {
  ola::InitLogging(ola::OLA_LOG_INFO, ola::OLA_LOG_STDERR);

  ola::OlaCallbackClientWrapper wrapper;
  if (!wrapper.Setup())
    exit(1);

  ola::OlaCallbackClient *client = wrapper.GetClient();
  // Set the callback and register our interest in this universe
  client->SetDmxCallback(ola::NewCallback(&NewDmx));
  client->RegisterUniverse(
      UNIVERSE, ola::REGISTER, ola::NewSingleCallback(&RegisterComplete));

  wrapper.GetSelectServer()->Run();
}