Porting your code from the old BeagleRT API

This material has been superseded. Visit learn.bela.io for the maintained version.

If you are one of the early adopters of Bela, then you probably wrote some programs whose API looked like

bool 	setup (BeagleRTContext *context, void *userData)
void 	render (BeagleRTContext *context, void *userData)
void 	cleanup (BeagleRTContext *context, void *userData)

If this is the case, then, first of all, thank you.

If you are willing to port your code to the latest stable API, you will need a few minor changes. Note that apart from the changes detailed below, you will also have to updated the core code from the repo.

• BeagleRTContext has been renamed to BelaContext. These can probably be fixed with the following one-liner. Run this from a terminal:

grep -RIl BeagleRT /path/to/your/project/s | xargs sed -i '.bak' s/BeagleRTContext/BelaContext/g

• Most of the members of BelaContext have now the const attribute. This may require you to redefine some of your own functions/methods to use the const attribute accordingly in case the compiler complains.

• Methods and variables that had a BeagleRT prefix, now have a Bela prefix.

• Instead of including BeagleRT.h you now include the file Bela.h.

• audioSampleCount is now audioFramesElapsed.

• The BeagleRTContext member

uint32_t  analogChannels

has been replaced by

const uint32_t  analogInChannels
const uint32_t  analogOutChannels

while

uint32_t  audioChannels

has been replaced by

const uint32_t  audioInChannels
const uint32_t  audioOutChannels

This is to ensure forward compatibility for audio capelet support or future developments of the PRU code, in case it will be possible to have a different number of channels for input and output.

An easy fix for this to add in your setup() a check that the number of inputs and outputs match up and return otherwise and then use either audioInChannels or audioOutChannels in your render().

These two lines, run on the terminal, should be capable to bring your code up-to-date:

grep -RIl audioChannels /path/to/your/project/s | xargs sed -i '.bak' s/audioChannels/audioInChannels/g ;
grep -RIl analogChannels /path/to/your/project/s | xargs sed -i '.bak' s/analogChannels/analogInChannels/g ;

but this should be used with care, as it does not add the mentioned check in setup, so you may have troubles if later down the line you try to run your code using different channel counts for inputs and outputs.

• The functions to read and write digital and analog pins have been renamed dropping the Frame affix, so that

analogReadFrame
analogWriteFrame
analogWriteFrameOnce
digitalReadFrame
digitalWriteFrame
digitalWriteFrameOnce

have become, respectively

analogRead
analogWrite
analogWriteOnce
digitalRead
digitalWrite
digitalWriteOnce

These two lines, run on the terminal, should be capable to bring your code up-to-date:

grep -RIl analogReadFrame /path/to/your/project/s | xargs sed -i '.bak' s/analogReadFrame/analogRead/g ;
grep -RIl analogWriteFrame /path/to/your/project/s | xargs sed -i '.bak' s/analogWriteFrame/analogWrite/g ;
grep -RIl digitalReadFrame /path/to/your/project/s | xargs sed -i '.bak' s/digitalReadFrame/analogRead/g ;
grep -RIl digitalWriteFrame /path/to/your/project/s | xargs sed -i '.bak' s/digitalWriteFrame/analogWrite/g ;