Bela
Real-time, ultra-low-latency audio and sensor processing system for BeagleBone Black
 All Classes Files Functions Variables Typedefs Macros Groups
Bela.h
Go to the documentation of this file.
1 
28 #ifndef BELA_H_
29 #define BELA_H_
30 #define BELA_MAJOR_VERSION 1
31 #define BELA_MINOR_VERSION 4
32 #define BELA_BUGFIX_VERSION 0
33 
34 // Version history / changelog:
35 // 1.4.0
36 // - added allocator/de-allocator for BelaInitSettings
37 // - added char board field to BelaInitSettings
38 // 1.3.0
39 // - removed define for I2C codec address
40 // - removed user option in settings for I2C address
41 // 1.2.0
42 // - renames and re-ordered BelaHw enum
43 // 1.1.0
44 // - adds BelaHw, Bela_detectHw()
45 // - removes digital_gpio_mapping.h
46 
47 #ifdef __cplusplus
48 extern "C"
49 {
50 #endif
51 
52 #include <stdint.h>
53 #include <unistd.h>
54 #include <stdbool.h>
55 #include <stdio.h>
56 // these functions are currently provided by xenomai.
57 // We put these declarations here so we do not have to include
58 // Xenomai specific files
59 int rt_printf(const char *format, ...);
60 int rt_fprintf(FILE *stream, const char *format, ...);
61 int rt_vprintf(const char *format, va_list ap);
62 int rt_vfprintf(FILE *stream, const char *format, va_list ap);
63 
64 typedef enum
65 {
66  BelaHw_NoHw = -1,
67  BelaHw_Bela,
68  BelaHw_BelaMini,
69  BelaHw_Salt,
70  BelaHw_CtagFace,
71  BelaHw_CtagBeast,
72  BelaHw_CtagFaceBela,
73  BelaHw_CtagBeastBela,
74 } BelaHw;
75 
76 #include <GPIOcontrol.h>
77 
78 // Useful constants
79 
81 #define MAX_PRU_FILENAME_LENGTH 256
82 #define MAX_SERVERNAME_LENGTH 256
83 #define MAX_BOARDNAME_LENGTH 256
84 
93 #define BELA_AUDIO_PRIORITY 95
94 
95 // Default volume levels
96 
106 #define DEFAULT_DAC_LEVEL 0.0
107 
111 #define DEFAULT_ADC_LEVEL -6.0
112 
113 
117 #define DEFAULT_PGA_GAIN 16
118 
122 #define DEFAULT_HP_LEVEL -6.0
123 
128 #define BELA_FLAG_INTERLEAVED (1 << 0) // Set if buffers are interleaved
129 
132 #define BELA_FLAG_ANALOG_OUTPUTS_PERSIST (1 << 1) // Set if analog/digital outputs persist for future buffers
133 
136 #define BELA_FLAG_DETECT_UNDERRUNS (1 << 2) // Set if the user will be displayed a message when an underrun occurs
137 
138 struct option;
139 
148 typedef struct {
166  const float * const audioIn;
167 
181  float * const audioOut;
182 
200  const float * const analogIn;
201 
215  float * const analogOut;
216 
225  uint32_t * const digital;
226 
239  const uint32_t audioFrames;
241  const uint32_t audioInChannels;
243  const uint32_t audioOutChannels;
245  const float audioSampleRate;
246 
258  const uint32_t analogFrames;
259 
263  const uint32_t analogInChannels;
264 
268  const uint32_t analogOutChannels;
269 
279  const float analogSampleRate;
280 
282  const uint32_t digitalFrames;
286  const uint32_t digitalChannels;
288  const float digitalSampleRate;
289 
296  const uint64_t audioFramesElapsed;
297 
302  const uint32_t multiplexerChannels;
303 
309 
315  const float * const multiplexerAnalogIn;
316 
321  const uint32_t audioExpanderEnabled;
322 
331  const uint32_t flags;
332 } BelaContext;
333 
343 typedef struct {
344  // These items might be adjusted by the user:
345 
365 
369  float dacLevel;
371  float adcLevel;
373  float pgaGain[2];
379  unsigned int audioExpanderInputs;
381  unsigned int audioExpanderOutputs;
382 
386  char pruFilename[MAX_PRU_FILENAME_LENGTH];
390  int verbose;
400 
401  // These items are application-dependent but should probably be
402  // determined by the programmer rather than the user
403 
414  // to 128KiB
415  unsigned int audioThreadStackSize;
417  // to 128KiB
418  unsigned int auxiliaryTaskStackSize;
419 
420  // Pointers to the user-defined functions
421  bool (*setup)(BelaContext*, void*);
422  void (*render)(BelaContext*, void*);
423  void (*cleanup)(BelaContext*, void*);
424  // These items are hardware-dependent and should only be changed
425  // to run on different hardware
426 
433  char serverName[MAX_SERVERNAME_LENGTH];
434 
436  char board[MAX_BOARDNAME_LENGTH];
437 
439 
445 typedef void* AuxiliaryTask; // Opaque data type to keep track of aux tasks
446 
454 extern int volatile gShouldStop;
455 
456 // *** User-defined render functions ***
457 
484 bool setup(BelaContext *context, void *userData);
485 
500 void render(BelaContext *context, void *userData);
501 
517 void cleanup(BelaContext *context, void *userData);
518 
530 // *** Command-line settings ***
531 
532 
541 
551 
561 void Bela_defaultSettings(BelaInitSettings *settings);
562 
563 #pragma weak Bela_userSettings
564 
575 void Bela_userSettings(BelaInitSettings *settings);
576 
598 int Bela_getopt_long(int argc, char *argv[], const char *customShortOptions,
599  const struct option *customLongOptions, BelaInitSettings *settings);
600 
608 void Bela_usage();
609 
613 void Bela_getVersion(int* major, int* minor, int* bugfix);
614 
621 void Bela_setVerboseLevel(int level);
622 
623 
627 BelaHw Bela_detectHw(void);
628 
629 // *** Audio control functions ***
630 
646 int Bela_initAudio(BelaInitSettings *settings, void *userData);
647 
656 int Bela_startAudio();
657 
667 
674 void Bela_stopAudio();
675 
683 void Bela_cleanupAudio();
684 
696 // *** Volume and level controls ***
697 
712 int Bela_setDACLevel(float decibels);
713 
728 int Bela_setADCLevel(float decibels);
729 
730 
747 int Bela_setPgaGain(float decibels, int channel);
748 
764 int Bela_setHeadphoneLevel(float decibels);
765 
779 int Bela_muteSpeakers(int mute);
780 
797 // *** Functions for creating auxiliary tasks ***
798 
815 AuxiliaryTask Bela_createAuxiliaryTask(void (*callback)(void*), int priority, const char *name, void* arg
816 #ifdef __cplusplus
817 = NULL
818 #endif /* __cplusplus */
819 );
820 
836 int Bela_scheduleAuxiliaryTask(AuxiliaryTask task);
837 
856 int Bela_startAuxiliaryTask(AuxiliaryTask task);
857 int Bela_startAllAuxiliaryTasks();
858 void Bela_stopAllAuxiliaryTasks();
859 void Bela_deleteAllAuxiliaryTasks();
860 
862 #include <Utilities.h>
863 
864 #ifdef __cplusplus
865 }
866 #endif
867 
868 #endif /* BELA_H_ */
int detectUnderruns
Whether to detect and log underruns.
Definition: Bela.h:388
int Bela_getopt_long(int argc, char *argv[], const char *customShortOptions, const struct option *customLongOptions, BelaInitSettings *settings)
Get long options from command line argument list, including Bela standard options.
const uint32_t multiplexerChannels
Number of multiplexer channels for each analog input.
Definition: Bela.h:302
const float *const analogIn
Buffer holding analog input samples.
Definition: Bela.h:200
float adcLevel
Level for the audio ADC input.
Definition: Bela.h:371
int ampMutePin
Pin where amplifier mute can be found.
Definition: Bela.h:428
const uint32_t audioInChannels
The number of audio input channels.
Definition: Bela.h:241
const float digitalSampleRate
Digital sample rate in Hz (currently always 44100.0)
Definition: Bela.h:288
int volatile gShouldStop
const uint32_t analogInChannels
The number of analog input channels.
Definition: Bela.h:263
int Bela_scheduleAuxiliaryTask(AuxiliaryTask task)
Run an auxiliary task which has previously been created.
void Bela_usage()
Print usage information for Bela standard options.
int receivePort
Port where the UDP server will listen.
Definition: Bela.h:430
float headphoneLevel
Level for the headphone output.
Definition: Bela.h:375
const uint32_t analogOutChannels
The number of analog output channels.
Definition: Bela.h:268
void Bela_setVerboseLevel(int level)
Set level of verbose (debugging) printing.
const uint32_t multiplexerStartingChannel
Multiplexer channel corresponding to the first analog frame.
Definition: Bela.h:308
const uint32_t flags
Other audio/sensor settings.
Definition: Bela.h:331
int Bela_setDACLevel(float decibels)
Set the level of the audio DAC.
int transmitPort
Port where the UDP client will transmit.
Definition: Bela.h:432
int verbose
Whether to use verbose logging.
Definition: Bela.h:390
const uint32_t digitalChannels
Number of digital channels.
Definition: Bela.h:286
const uint32_t digitalFrames
Number of digital frames per period.
Definition: Bela.h:282
void Bela_getVersion(int *major, int *minor, int *bugfix)
Get the version of Bela you are running.
int numAudioInChannels
How many audio input channels.
Definition: Bela.h:356
unsigned int audioExpanderOutputs
Which audio expander settings to use on the input.
Definition: Bela.h:381
int Bela_setHeadphoneLevel(float decibels)
Set the level of the onboard headphone amplifier.
AuxiliaryTask Bela_createAuxiliaryTask(void(*callback)(void *), int priority, const char *name, void *arg)
Create a new auxiliary task.
int pruNumber
Which PRU (0 or 1) the code should run on.
Definition: Bela.h:384
void cleanup(BelaContext *context, void *userData)
User-defined cleanup function which runs when the program finishes.
Definition: render.cpp:47
BelaInitSettings * Bela_InitSettings_alloc()
Allocate the data structure containing settings for Bela.
void Bela_userSettings(BelaInitSettings *settings)
Initialise the data structure containing settings for Bela.
Definition: render.cpp:62
Structure containing initialisation parameters for the real-time audio control system.
Definition: Bela.h:343
float *const audioOut
Buffer holding audio output samples.
Definition: Bela.h:181
int numAudioOutChannels
How many audio out channels.
Definition: Bela.h:358
int interleave
Whether audio/analog data should be interleaved.
Definition: Bela.h:405
const uint32_t audioFrames
The number of audio frames per block.
Definition: Bela.h:239
void Bela_stopAudio()
Stop processing audio and sensor data.
int Bela_muteSpeakers(int mute)
Mute or unmute the onboard speaker amplifiers.
const float analogSampleRate
Analog sample rate in Hz.
Definition: Bela.h:279
Structure holding audio and sensor settings and pointers to I/O data buffers.
Definition: Bela.h:148
int enableCapeButtonMonitoring
Whether to monitor the Bela cape button on P9.27 / GPIO3[19].
Definition: Bela.h:394
BelaHw Bela_detectHw(void)
Detect what hardware we are running on.
const uint32_t audioExpanderEnabled
Flags for whether audio expander is enabled on given analog channels.
Definition: Bela.h:321
bool setup(BelaContext *context, void *userData)
User-defined initialisation function which runs before audio rendering begins.
Definition: render.cpp:32
int uniformSampleRate
Whether the analog channels should be resampled to audio sampling rate.
Definition: Bela.h:412
int numMuxChannels
How many channels to use on the multiplexer capelet, if enabled.
Definition: Bela.h:377
int Bela_initAudio(BelaInitSettings *settings, void *userData)
Initialise audio and sensor rendering environment.
int numAnalogOutChannels
How many analog output channels.
Definition: Bela.h:362
float *const analogOut
Buffer holding analog output samples.
Definition: Bela.h:215
const uint32_t audioOutChannels
The number of audio output channels.
Definition: Bela.h:243
int Bela_setPgaGain(float decibels, int channel)
Set the gain of the audio preamplifier.
int beginMuted
Whether to begin with the speakers muted.
Definition: Bela.h:367
int numAnalogInChannels
How many analog input channels.
Definition: Bela.h:360
Wiring-inspired utility functions and macros.
void render(BelaContext *context, void *userData)
User-defined callback function to process audio and sensor data.
Definition: render.cpp:40
uint32_t *const digital
Buffer holding digital input/output samples.
Definition: Bela.h:225
const uint64_t audioFramesElapsed
Number of elapsed audio frames since the start of rendering.
Definition: Bela.h:296
unsigned int audioExpanderInputs
Which audio expander settings to use on the input.
Definition: Bela.h:379
float dacLevel
Level for the audio DAC output.
Definition: Bela.h:369
int Bela_setADCLevel(float decibels)
Set the level of the audio ADC.
void Bela_InitSettings_free(BelaInitSettings *settings)
De-allocate the data structure containing settings for Bela.
const uint32_t analogFrames
The number of analog frames per block.
Definition: Bela.h:258
int highPerformanceMode
Definition: Bela.h:399
int numDigitalChannels
How many channels for the GPIOs.
Definition: Bela.h:364
void * AuxiliaryTask
Definition: Bela.h:445
const float *const multiplexerAnalogIn
Buffer which holds multiplexed analog inputs, when multiplexer capelet is enabled.
Definition: Bela.h:315
int Bela_runInSameThread()
Begin processing audio and sensor data in the same thread as the caller.
int enableLED
Whether to use the blinking LED to indicate Bela is running.
Definition: Bela.h:392
int useAnalog
Whether to use the analog input and output.
Definition: Bela.h:352
const float audioSampleRate
The audio sample rate in Hz (currently always 44100.0)
Definition: Bela.h:245
int Bela_startAudio()
Begin processing audio and sensor data.
int periodSize
Number of (analog) frames per period.
Definition: Bela.h:350
int analogOutputsPersist
Whether analog outputs should persist to future frames.
Definition: Bela.h:409
const float *const audioIn
Buffer holding audio input samples.
Definition: Bela.h:166
int useDigital
Whether to use the 16 programmable GPIOs.
Definition: Bela.h:354
void Bela_defaultSettings(BelaInitSettings *settings)
Initialise the data structure containing settings for Bela.
int Bela_startAuxiliaryTask(AuxiliaryTask task)
Initialize an auxiliary task so that it can be scheduled.
void Bela_cleanupAudio()
Clean up resources from audio and sensor processing.