Timing and IO in Bela » History » Version 5

Giulio Moro, 2016-05-10 03:16 PM

1 3 Giulio Moro
h1.  Timing and I/O in Bela 
2 1 Andrew McPherson
3 3 Giulio Moro
All I/O in Bela -- audio, analog and digital -- is synchronised to the same master clock. This means that audio and sensor data is always strongly aligned with no latency or jitter. It also means that programming conventions for handling I/O are somewhat different from other platforms.
4 1 Andrew McPherson
5 3 Giulio Moro
h2. Functions in a Bela project
6 1 Andrew McPherson
7 3 Giulio Moro
Every Bela project must declare three functions: @setup()@, @render()@ and @cleanup()@.
8 1 Andrew McPherson
9 1 Andrew McPherson
@setup(BeagleRTContext *context, void *userData)@ runs once at the *beginning* of the program, before any audio or sensor processing has taken place. It is analogous to the @setup()@ function in the Arduino environment. Your code here should allocate any needed memory and initialise program state.
10 1 Andrew McPherson
11 3 Giulio Moro
@render(BeagleRTContext *context, void *userData)@ runs *regularly, in a loop* as long as the program is running. It is called by the Bela system. Your code within @render()@ should process one buffer worth of audio, analog and digital data, using the information stored in the @context@ data structure. For further information, see [[ Tutorial Sketches - Explanations ]].
12 1 Andrew McPherson
13 1 Andrew McPherson
@cleanup(BeagleRTContext *context, void *userData)@ runs once at the *end* of the program, after audio and sensor processing has finished. Use it to clean up resources allocated in @setup()@.
14 1 Andrew McPherson
15 1 Andrew McPherson
h2. Working with I/O
16 1 Andrew McPherson
17 1 Andrew McPherson
All audio processing, as well as all analog and digital I/O, should be handled from @render()@. Every call to @render()@ represents a small slice of time:
18 1 Andrew McPherson
19 1 Andrew McPherson
(image to go here)
20 1 Andrew McPherson
21 4 Giulio Moro
On Bela, analog and digital I/Os are sampled at a constant rate, _regardless of whether you use the samples or not_. All I/O is held within the @context@ data structure. For example, if the buffer size is 8 audio samples and you are using 8 analog channels, then the structure will contain:
22 1 Andrew McPherson
23 1 Andrew McPherson
* @context->audioIn@ is an array of 8 frames * 2 channels = 16 audio input samples. These samples were read by the hardware before @render()@ began.
24 1 Andrew McPherson
* @context->audioOut@ is an array of 8 frames * 2 channels = 16 audio output samples which your program should write. They will be sent to the hardware after @render()@ has finished.
25 1 Andrew McPherson
* @context->analogIn@ is an array of 4 frames * 8 channels = 32 analog input samples. (4 frames because analog I/O runs at half the sample rate of audio I/O.) These samples were read by the hardware before @render()@ began.
26 1 Andrew McPherson
* @context->analogOut@ is an array of 4 frames * 8 channels = 32 analog output samples which your program should write.
27 5 Giulio Moro
* @context->digital@ is an array of 8 frames. Digital frames are encoded as 32bit words where bits 31-16 are the input or output value and bits 15-0 set the direction. While these can be set directly using bitwise operators, it is recommended that you use I/O functions below.
28 1 Andrew McPherson
29 3 Giulio Moro
This is a contrast to Arduino and similar environments. For example, calling @analogRead()@ on Arduino would cause the analog pin to be read at the moment the function runs. The rest of the code will stop until the analog to digital conversion has finished and @analogRead()@ returns. On Bela, the analog input data is _already present in the buffer_. Calling @analogReadFrame()@ will retrieve the sample from the buffer. Your code does not need to wait for the conversion to happen.
30 1 Andrew McPherson
31 1 Andrew McPherson
h3. Understanding the "frame" argument
32 1 Andrew McPherson
33 3 Giulio Moro
All the I/O functions in Bela (@digitalReadFrame()@, @analogWriteFrame()@, etc.) take an argument for which frame to read or write the I/O pin. The frame indicates exactly what time the read/write should take place. The number of frames in any given call to @render()@ depends on the Bela buffer size (which can be changed with the @- p@ command line argument). By default, the buffer size is 8 analog frames or 16 audio frames. Valid frame numbers will range from 0 to @(context->analogFrames - 1)@ for analog, @(context->digitalFrames - 1)@ for digital and @(context->audioFrames - 1)@ for audio.
34 1 Andrew McPherson
35 1 Andrew McPherson
Remember when calling @analogWriteFrame()@ or @digitalWriteFrame()@ that the value will not be updated immediately upon returning from the function. Instead, the output will be buffered and will change when the designated frame arrives.
36 1 Andrew McPherson
37 1 Andrew McPherson
h3. I/O Functions
38 1 Andrew McPherson
39 3 Giulio Moro
Bela provides a number of I/O functions. Your files should contain @#include <Utilities.h>@ in order to use these functions. See the code docs for detailed usage: https://code.soundsoftware.ac.uk/projects/beaglert/embedded/Utilities_8h.html
40 1 Andrew McPherson
41 1 Andrew McPherson
* @digitalReadFrame@ -- read a digital pin
42 1 Andrew McPherson
* @digitalWriteFrame@ -- write a digital pin, and hold the value going forward
43 1 Andrew McPherson
* @digitalWriteFrameOnce@ -- write a digital pin for one frame only
44 1 Andrew McPherson
* @pinModeFrame@ -- change a digital pin to an input or output and maintain this going forward
45 1 Andrew McPherson
* @pinModeFrameOnce@ -- change a digital pin to an input or output for one frame only
46 1 Andrew McPherson
* @analogReadFrame@ -- read an analog pin
47 1 Andrew McPherson
* @analogWriteFrame@ -- write an analog pin, and (depending on system setting) hold the value going forward
48 1 Andrew McPherson
* @analogWriteFrameOnce@ -- write an analog pin for one frame only
49 1 Andrew McPherson
50 1 Andrew McPherson
h3. Example: @int digitalReadFrame(BeagleRTContext *context, int frame, int channel)@
51 1 Andrew McPherson
52 1 Andrew McPherson
This function works like @digitalRead()@ on Arduino, but it takes two extra arguments. The first argument is the @context@ data structure which is passed in to @render()@. This is needed because @context@ holds all the references to the I/O buffers. The second argument is the frame (i.e. the time) at which to read the pin. The third argument, @channel@, is the pin to read, similar to the Arduino function. The value of the pin (@HIGH@ or @LOW@) is returned.
53 2 Giulio Moro
54 2 Giulio Moro
h3. Input/output pins
55 2 Giulio Moro
56 2 Giulio Moro
Analog input and output pins are provided on dedicated headers, labelled "IN" and "OUT" respectively.
57 2 Giulio Moro
The 8 analog inputs are ordered sequentially from 0 to 7 starting from the one closer to P9 and moving towards P8.
58 2 Giulio Moro
The 8 analog outputs are not sequential but their numbers are silkscreened on the PCB.
59 2 Giulio Moro
60 2 Giulio Moro
Digital input/output pins are available on P8 and P9 connectors. The correspondency between physical pins and the digital pin numbers used in the software is outlined below.
61 2 Giulio Moro
62 2 Giulio Moro
Refer to the interactive diagram to find your way around the available pins on the cape: http://www.astridbin.com/bbb_diagram/ .
63 2 Giulio Moro
64 2 Giulio Moro
 Pin     Digital in/out number
65 2 Giulio Moro
 P8_07    0
66 2 Giulio Moro
 P8_08    1
67 2 Giulio Moro
 P8_09    2
68 2 Giulio Moro
 P8_10    3
69 2 Giulio Moro
 P8_11    4
70 2 Giulio Moro
 P8_12    5
71 2 Giulio Moro
 P9_12    6
72 2 Giulio Moro
 P9_14    7
73 2 Giulio Moro
 P8_15    8
74 2 Giulio Moro
 P8_16    9
75 2 Giulio Moro
 P9_16   10
76 2 Giulio Moro
 P8_18   11
77 2 Giulio Moro
 P8_27   12
78 2 Giulio Moro
 P8_28   13
79 2 Giulio Moro
 P8_29   14
80 2 Giulio Moro
 P8_30   15