\begin{DoxyAuthor}{Author} Dr Terry Barnaby \end{DoxyAuthor} \begin{DoxyVersion}{Version} 0.\+2.\+8 \end{DoxyVersion} \begin{DoxyDate}{Date} 2019-\/10-\/14 \end{DoxyDate} \hypertarget{index_Introduction}{}\section{Introduction}\label{index_Introduction} The Beam B\+Measure-\/125i unit is a flexible and powerful IoT system for data capture, data logging and control in the laboratory, industrial and remote sensing arenas. It is based around an 8 channel, fully differential, synchronous sampling, 24 bit A\+DC that can sample at speeds up to 128 ksps. Multiple units can be connected together to provide more synchronously sampled channels. This reference information describes the data types and functions provided by the host A\+PI library allowing programs to be written to control the operation of a B\+Measure unit and acquire the data from it. The A\+PI operates over a number of different physical interfaces including\+: U\+SB 2.\+0, Ethernet, Wifi and R\+S485. In addition there is a software manual providing an overview of using this A\+PI which should be read first. This document is available at\+:\+: \href{https://portal.beam.ltd.uk/files/products/bmeasure-125i/doc/BMeasure-lib.pdf}{\texttt{ https\+://portal.\+beam.\+ltd.\+uk/files/products/bmeasure-\/125i/doc/\+B\+Measure-\/lib.\+pdf}}\hypertarget{index_Overview}{}\section{Overview}\label{index_Overview} The B\+Measure A\+PI library, bmeasure-\/lib, is implemented in the C++ computer language. It has bindings layered on top of this for Python, with Matlab due to be supported soon. The A\+PI has an object orientated architecture. It has been designed as a general purpose A\+PI library for the Beam B\+Measure-\/125i and future B\+Measure products. Currently it has ports to Linux (Redhat7, Fedora29, Debian) and Microsoft Windows 7, 8 and 10. The A\+PI provides the following functionality\+: \begin{DoxyItemize} \item Find B\+Measure units on the U\+SB bus or local Ethernet and Wifi networks. \item Connect to one or more B\+Measure units. \item Fetch information and configure the B\+Measure units. \item Start the B\+Measure unit capturing and processing the sensor inputs. \item Capture the data from all of the analogue and digital channels from one or a combined set of B\+Measure units running in sync. \item Access the data log files on the unit and download them to the host. \item Configure the A\+WG to produce waveforms or set voltages on the analogue output channels. \item Operate relays, read switches and other auxiliary operations. \end{DoxyItemize} The B\+Measure A\+PI is implemented using the Beam B\+O\+AP (Beam Object Access protocol) communications system. It offers an B\+Measure\+Unit A\+PI class to access an individual B\+Measure unit in a relatively low level manner and an B\+Measure\+Units A\+PI class to access a set of B\+Measure units synchronised together to operate as a single unit and with a queued data reception system.. The A\+PI supports threaded and non-\/threaded operation. The referenve information provided describes the A\+PI from a C++ programming perspective. The Python and other language bindings are very similar the differences being noted under the particular language bindings section in the software manual..\hypertarget{index_BMeassure}{}\section{A\+P\+I Usage}\label{index_BMeassure} To use the A\+PI the core procedure is\+: \begin{DoxyEnumerate} \item Either find the available B\+Measure units using\+: \mbox{\hyperlink{classBMeasureApi_1_1BMeasureUnit_a8f8d1aae1a29c1050bf87f42617a7dab}{B\+Measure\+Api\+::\+B\+Measure\+Unit\+::find\+Devices()}} or use a B\+Measure U\+RL string.. \item Choose to use the simple single unit interface \mbox{\hyperlink{classBMeasureApi_1_1BMeasureUnit}{B\+Measure\+Api\+::\+B\+Measure\+Unit}} or the \mbox{\hyperlink{classBMeasureApi_1_1BMeasureUnits}{B\+Measure\+Api\+::\+B\+Measure\+Units}} classes. \item If using the simple single unit interface, connect to the unit using the \mbox{\hyperlink{classBMeasureApi_1_1BMeasureUnit_a77e62ccdaf6210f4ad3972b04c5060bc}{B\+Measure\+Api\+::\+B\+Measure\+Unit\+::connect()}} function. \item If using the multiple unit interface, add the units using the \mbox{\hyperlink{classBMeasureApi_1_1BMeasureUnits_ae483d680c576fe5144d7adf40f75d4c0}{B\+Measure\+Api\+::\+B\+Measure\+Units\+::unit\+Add()}} function and connect using the \mbox{\hyperlink{classBMeasureApi_1_1BMeasureUnits_a19bc5da07f6fe00301afebb48b61f84e}{B\+Measure\+Api\+::\+B\+Measure\+Units\+::units\+Connect()}} function. \item Use the interface to communicate to the unit. \end{DoxyEnumerate}See the examples below and the software manual for more details.\hypertarget{index_BMeassure}{}\section{A\+P\+I Usage}\label{index_BMeassure} There are some examples of client applications using the B\+Measure A\+PI in the {\bfseries{examples}} directory of the source code. Some simple client examples are listed below\+: {\bfseries{ Simple example to access and read single sets of data samples in C++}} \begin{DoxyCodeInclude}{0} \DoxyCodeLine{\textcolor{comment}{/*******************************************************************************}} \DoxyCodeLine{\textcolor{comment}{ * Example005-dataClient-single.cpp}} \DoxyCodeLine{\textcolor{comment}{ * T.Barnaby, BEAM Ltd, 2019-10-09}} \DoxyCodeLine{\textcolor{comment}{ *******************************************************************************}} \DoxyCodeLine{\textcolor{comment}{ */}} \DoxyCodeLine{\textcolor{preprocessor}{\#include <\mbox{\hyperlink{BMeasureUnit_8h}{BMeasureUnit.h}}>}} \DoxyCodeLine{\textcolor{preprocessor}{\#include }} \DoxyCodeLine{} \DoxyCodeLine{\textcolor{keyword}{using namespace }\mbox{\hyperlink{namespaceBMeasureApi}{BMeasureApi}};} \DoxyCodeLine{} \DoxyCodeLine{\textcolor{comment}{// Function to read some data}} \DoxyCodeLine{BError test1()\{} \DoxyCodeLine{ BError err;} \DoxyCodeLine{ BList devices;} \DoxyCodeLine{ BString device;} \DoxyCodeLine{ \mbox{\hyperlink{classBMeasureApi_1_1BMeasureUnit}{BMeasureUnit}} bmeasure;} \DoxyCodeLine{ \mbox{\hyperlink{classBMeasureApi_1_1Information}{Information}} info;} \DoxyCodeLine{ \mbox{\hyperlink{classBMeasureApi_1_1Configuration}{Configuration}} config;} \DoxyCodeLine{ \mbox{\hyperlink{classBMeasureApi_1_1MeasurementConfig}{MeasurementConfig}} mc;} \DoxyCodeLine{ \mbox{\hyperlink{classBMeasureApi_1_1DataBlock}{DataBlock}} data;} \DoxyCodeLine{ BUInt c;} \DoxyCodeLine{ } \DoxyCodeLine{ printf(\textcolor{stringliteral}{"Start Processing Task\(\backslash\)n"});} \DoxyCodeLine{ bmeasure.start();} \DoxyCodeLine{ } \DoxyCodeLine{ printf(\textcolor{stringliteral}{"Find BMeasure units\(\backslash\)n"});} \DoxyCodeLine{ \textcolor{keywordflow}{if}(err = \mbox{\hyperlink{classBMeasureApi_1_1BMeasureUnit_ad6c8e0fd065eec67cb7721b98071ee41}{BMeasureUnit::findDevicesUsb}}(devices))\{} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{ \}} \DoxyCodeLine{ \textcolor{keywordflow}{if}(devices.number() == 0)\{} \DoxyCodeLine{ \textcolor{keywordflow}{return} err.set(1, \textcolor{stringliteral}{"No USB BMeasure units found\(\backslash\)n"});} \DoxyCodeLine{ \}} \DoxyCodeLine{ device = devices[0].device;} \DoxyCodeLine{ } \DoxyCodeLine{ printf(\textcolor{stringliteral}{"Connect\(\backslash\)n"});} \DoxyCodeLine{ \textcolor{keywordflow}{if}(err = bmeasure.\mbox{\hyperlink{classBMeasureApi_1_1BMeasureUnit_a77e62ccdaf6210f4ad3972b04c5060bc}{connect}}(device))} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{ } \DoxyCodeLine{ \textcolor{comment}{//printf("Exit\(\backslash\)n"); return err;}} \DoxyCodeLine{} \DoxyCodeLine{ printf(\textcolor{stringliteral}{"Get Info\(\backslash\)n"});} \DoxyCodeLine{ \textcolor{keywordflow}{if}(err = bmeasure.\mbox{\hyperlink{classBMeasureApi_1_1BMeasure_ae7c06111edcbfad84bde76434615eb25}{getInformation}}(info))} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{ } \DoxyCodeLine{ printf(\textcolor{stringliteral}{"NumChannels: \%d\(\backslash\)n"}, info.\mbox{\hyperlink{classBMeasureApi_1_1Information_a4a55509ceb6e1e1805e86b5ed49bc598}{numChannels}});} \DoxyCodeLine{} \DoxyCodeLine{ \textcolor{comment}{//printf("Exit\(\backslash\)n"); return err;}} \DoxyCodeLine{} \DoxyCodeLine{ printf(\textcolor{stringliteral}{"Configure measurement\(\backslash\)n"});} \DoxyCodeLine{ mc.\mbox{\hyperlink{classBMeasureApi_1_1MeasurementConfig_a1e5558a111a2979602979646507bb79f}{measureMode}} = \mbox{\hyperlink{namespaceBMeasureApi_a477b0df257215ae382507811552315e8a0359f246f59855e3faf21350b29beedd}{MeasureModeOneShot}};} \DoxyCodeLine{ mc.\mbox{\hyperlink{classBMeasureApi_1_1MeasurementConfig_a72f2aa69ac691e94ffbf5487cf634b75}{triggerMode}} = \mbox{\hyperlink{namespaceBMeasureApi_a5d4c1f3c29afebe5194dcba4942e676da5af874fdd6344a7f492f5a0a432a46ca}{TriggerModeOff}};} \DoxyCodeLine{ mc.\mbox{\hyperlink{classBMeasureApi_1_1MeasurementConfig_a1ecda819459d60b7b2b950665b6d7f28}{triggerConfig}} = \mbox{\hyperlink{namespaceBMeasureApi_a9febb2755e7e87c78f59054f8124530aac65b8a0dfb72b2d514ddf691512f9004}{TriggerConfigNone}};} \DoxyCodeLine{ mc.\mbox{\hyperlink{classBMeasureApi_1_1MeasurementConfig_a874fe2453faa25bda6d415b7617111cd}{triggerChannel}} = 0;} \DoxyCodeLine{ mc.\mbox{\hyperlink{classBMeasureApi_1_1MeasurementConfig_ae5d87e5fc5910543cb72046e3e00d5ee}{triggerLevel}} = 0;} \DoxyCodeLine{ mc.\mbox{\hyperlink{classBMeasureApi_1_1MeasurementConfig_a6023183e098f21f6ffee7318607293a0}{triggerDelay}} = 0;} \DoxyCodeLine{ mc.\mbox{\hyperlink{classBMeasureApi_1_1MeasurementConfig_a868193954be9a3b9c76a99d63938031b}{sampleRate}} = 8000.0;} \DoxyCodeLine{ mc.\mbox{\hyperlink{classBMeasureApi_1_1MeasurementConfig_af72b45d4c56d10f8214c0f6ef63aa75a}{measurePeriod}} = 0;} \DoxyCodeLine{ mc.\mbox{\hyperlink{classBMeasureApi_1_1MeasurementConfig_a2a33cd55aa2fa9bb0350d480fea24cde}{numSamples0}} = 1;} \DoxyCodeLine{ mc.\mbox{\hyperlink{classBMeasureApi_1_1MeasurementConfig_ab5203d8b1102743854018691b5ab0617}{numSamples1}} = 0;} \DoxyCodeLine{ \textcolor{keywordflow}{if}(err = bmeasure.\mbox{\hyperlink{classBMeasureApi_1_1BMeasureUnit_ae0e08f8bb8e1c7bae50909bfcc4a0a22}{setMeasurement}}(mc))} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{ } \DoxyCodeLine{ printf(\textcolor{stringliteral}{"Run single measurement\(\backslash\)n"});} \DoxyCodeLine{ \textcolor{keywordflow}{if}(err = bmeasure.\mbox{\hyperlink{classBMeasureApi_1_1BMeasure_ab6b8c344cc41c46745259e6cb002e277}{measure}}(data))} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{ } \DoxyCodeLine{ printf(\textcolor{stringliteral}{"DataBlock: from: \%d numChannels: \%d numSamples: \%d\(\backslash\)n"}, data.source, data.numChannels, data.numSamples);} \DoxyCodeLine{ \textcolor{keywordflow}{for}(c = 0; c < data.numChannels; c++)\{} \DoxyCodeLine{ printf(\textcolor{stringliteral}{"\%f "}, data.data[c]);} \DoxyCodeLine{ \}} \DoxyCodeLine{ printf(\textcolor{stringliteral}{"\(\backslash\)n"});} \DoxyCodeLine{} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{\}} \DoxyCodeLine{} \DoxyCodeLine{\textcolor{keywordtype}{int} main()\{} \DoxyCodeLine{ BError err;} \DoxyCodeLine{} \DoxyCodeLine{ \textcolor{keywordflow}{if}(err = test1())\{} \DoxyCodeLine{ printf(\textcolor{stringliteral}{"Error: \%d \%s\(\backslash\)n"}, err.getErrorNo(), err.str());} \DoxyCodeLine{ \textcolor{keywordflow}{return} 1;} \DoxyCodeLine{ \}} \DoxyCodeLine{} \DoxyCodeLine{ printf(\textcolor{stringliteral}{"Complete\(\backslash\)n"});} \DoxyCodeLine{} \DoxyCodeLine{ \textcolor{keywordflow}{return} 0;} \DoxyCodeLine{\}} \end{DoxyCodeInclude} {\bfseries{ Simple example to access and read single sets of data samples in Python}} \begin{DoxyCodeInclude}{0} \DoxyCodeLine{\textcolor{comment}{\#!/usr/bin/python3}} \DoxyCodeLine{} \DoxyCodeLine{\textcolor{keyword}{import} sys} \DoxyCodeLine{\textcolor{keyword}{import} time} \DoxyCodeLine{\textcolor{keyword}{import} getopt} \DoxyCodeLine{\textcolor{keyword}{from} threading \textcolor{keyword}{import} Thread} \DoxyCodeLine{\textcolor{keyword}{from} bmeasure \textcolor{keyword}{import} *} \DoxyCodeLine{} \DoxyCodeLine{\textcolor{comment}{\# Function to read some data}} \DoxyCodeLine{\textcolor{keyword}{def }test1():} \DoxyCodeLine{ bmeasure = BMeasureUnit(\textcolor{keyword}{True});} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Find BMeasure units"});} \DoxyCodeLine{ (err, devices) = BMeasureUnit.findDevicesUsb();} \DoxyCodeLine{ if(err):} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{} \DoxyCodeLine{ if(devices.number() == 0):} \DoxyCodeLine{ \textcolor{keywordflow}{return} err.set(1, \textcolor{stringliteral}{"No USB BMeasure units found\(\backslash\)n"});} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Found"}, len(devices));} \DoxyCodeLine{ device = devices[0].device;} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Start Processing Task"});} \DoxyCodeLine{ bmeasure.start();} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Connect to BMeasure"});} \DoxyCodeLine{ err = bmeasure.connect(device);} \DoxyCodeLine{ if(err):} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Get Info"});} \DoxyCodeLine{ (err, info) = bmeasure.getInformation();} \DoxyCodeLine{ if(err):} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{ } \DoxyCodeLine{ print(\textcolor{stringliteral}{"NumChannels: "}, info.numChannels);} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Configure measurement"});} \DoxyCodeLine{ mc = MeasurementConfig();} \DoxyCodeLine{ mc.measureMode = MeasureModeOneShot;} \DoxyCodeLine{ mc.triggerMode = TriggerModeOff;} \DoxyCodeLine{ mc.triggerConfig = TriggerConfigNone;} \DoxyCodeLine{ mc.triggerChannel = 0;} \DoxyCodeLine{ mc.triggerLevel = 0;} \DoxyCodeLine{ mc.triggerDelay = 0;} \DoxyCodeLine{ mc.sampleRate = 4000;} \DoxyCodeLine{ mc.numSamples0 = 1;} \DoxyCodeLine{ mc.numSamples1 = 0;} \DoxyCodeLine{ mc.measurePeriod = 0;} \DoxyCodeLine{ err = bmeasure.setMeasurement(mc);} \DoxyCodeLine{ if(err):} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{ } \DoxyCodeLine{ print(\textcolor{stringliteral}{"Run single measurement"});} \DoxyCodeLine{ (err, data) = bmeasure.measure();} \DoxyCodeLine{ if(err):} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"DataBlock: from: \%d numChannels: \%d numSamples: \%d"} \% (data.source, data.numChannels, data.numSamples));} \DoxyCodeLine{ \textcolor{keywordflow}{for} c \textcolor{keywordflow}{in} range(0, data.numChannels):} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Chan:"}, c, data.data[c]);} \DoxyCodeLine{} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{} \DoxyCodeLine{} \DoxyCodeLine{\textcolor{keyword}{def }main():} \DoxyCodeLine{ err = test1();} \DoxyCodeLine{ if(err):} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Error:"}, err.getErrorNo(), err.getString());} \DoxyCodeLine{ \textcolor{keywordflow}{return} 1;} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Complete"});} \DoxyCodeLine{ } \DoxyCodeLine{ \textcolor{keywordflow}{return} 0;} \DoxyCodeLine{} \DoxyCodeLine{\textcolor{keywordflow}{if} \_\_name\_\_ == \textcolor{stringliteral}{"\_\_main\_\_"}:} \DoxyCodeLine{ main();} \end{DoxyCodeInclude} {\bfseries{ Simple example to show operating the relays in Python}} \begin{DoxyCodeInclude}{0} \DoxyCodeLine{\textcolor{comment}{\#!/usr/bin/python3}} \DoxyCodeLine{} \DoxyCodeLine{\textcolor{keyword}{import} sys} \DoxyCodeLine{\textcolor{keyword}{import} time} \DoxyCodeLine{\textcolor{keyword}{import} getopt} \DoxyCodeLine{\textcolor{keyword}{from} threading \textcolor{keyword}{import} Thread} \DoxyCodeLine{\textcolor{keyword}{from} bmeasure \textcolor{keyword}{import} *} \DoxyCodeLine{} \DoxyCodeLine{\textcolor{comment}{\# Function to set the relays on/off}} \DoxyCodeLine{\textcolor{keyword}{def }test1():} \DoxyCodeLine{ bmeasure = BMeasureUnit(\textcolor{keyword}{True});} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Find BMeasure units"});} \DoxyCodeLine{ (err, devices) = BMeasureUnit.findDevicesUsb();} \DoxyCodeLine{ if(err):} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{} \DoxyCodeLine{ if(devices.number() == 0):} \DoxyCodeLine{ \textcolor{keywordflow}{return} err.set(1, \textcolor{stringliteral}{"No USB BMeasure units found\(\backslash\)n"});} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Found"}, len(devices));} \DoxyCodeLine{ device = devices[0].device;} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Start Communications Task"});} \DoxyCodeLine{ bmeasure.start();} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Connect"});} \DoxyCodeLine{ err = bmeasure.connect(device);} \DoxyCodeLine{ if(err):} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Get Info"});} \DoxyCodeLine{ (err, info) = bmeasure.getInformation();} \DoxyCodeLine{ if(err):} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{ } \DoxyCodeLine{ print(\textcolor{stringliteral}{"NumChannels: "}, info.numChannels);} \DoxyCodeLine{} \DoxyCodeLine{ \textcolor{comment}{\# Toggle relay1}} \DoxyCodeLine{ state = 0;} \DoxyCodeLine{ \textcolor{keywordflow}{for} i \textcolor{keywordflow}{in} range(0, 6):} \DoxyCodeLine{ if(state):} \DoxyCodeLine{ state = 0;} \DoxyCodeLine{ \textcolor{keywordflow}{else}:} \DoxyCodeLine{ state = 1;} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Set relay 0: \%d"} \% (state));} \DoxyCodeLine{ err = bmeasure.setRelay(0, state);} \DoxyCodeLine{ if(err):} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{ } \DoxyCodeLine{ time.sleep(1);} \DoxyCodeLine{} \DoxyCodeLine{ \textcolor{keywordflow}{return} err;} \DoxyCodeLine{} \DoxyCodeLine{} \DoxyCodeLine{\textcolor{keyword}{def }main():} \DoxyCodeLine{ if(0):} \DoxyCodeLine{ err = find();} \DoxyCodeLine{ if(err):} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Error:"}, err.getErrorNo(), err.getString());} \DoxyCodeLine{ \textcolor{keywordflow}{return} 1;} \DoxyCodeLine{} \DoxyCodeLine{ err = test1();} \DoxyCodeLine{ if(err):} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Error:"}, err.getErrorNo(), err.getString());} \DoxyCodeLine{ \textcolor{keywordflow}{return} 1;} \DoxyCodeLine{} \DoxyCodeLine{ print(\textcolor{stringliteral}{"Complete"});} \DoxyCodeLine{ } \DoxyCodeLine{ \textcolor{keywordflow}{return} 0;} \DoxyCodeLine{} \DoxyCodeLine{\textcolor{keywordflow}{if} \_\_name\_\_ == \textcolor{stringliteral}{"\_\_main\_\_"}:} \DoxyCodeLine{ main();} \end{DoxyCodeInclude}