Package: pybela
pybelapybela allows interfacing withBela, the embedded audio platform, using Python. pybela provides a convenient way to stream, log, and monitor sensor data from your Bela device to your laptop.This library is currently under development and has been tested with Bela atdevbranch commit69cdf75aand watcher atmaincommit903573a.Installation and set up1. Installing the python packageOption A:You can install this library usingpip(replacepipwithpipenvif you are using a pipenv environment):pipinstallpybelaOption B:You can also download the built package from the releases section and run (replacepipwithpipenvif you are using a pipenv environment):pipinstallpybela-<version>.tar.gzOption C:You can also install this library usingpipenvby cloning this repository and running:gitclone--recurse-submoduleshttps://github.com/BelaPlatform/pybelacdpybela
pipenvinstall2. Set the Bela branch todevIn order to use pybela, you will need to use thedevbranch of the Bela code.Option A:If your Bela is connected to internet, you can ssh into your Bela (ssh root@bela.local) and change the branch:# in BelacdBela
gitcheckoutdev
gitpullOption B:If your Bela is not connected to internet, you can change the branch by cloning the Bela repository into your laptop and then pushing thedevbranch to your Bela.
To do that, first clone the Bela repository into your laptop:# in laptopgitclone--recurse-submoduleshttps://github.com/belaPlatform/belacdBelaThen add your Bela as a remote and push thedevbranch to your Bela:# in laptopgitremoteaddboardroot@bela.local:Bela/
gitcheckoutdev
gitpush-fboarddev:tmpThen ssh into your Bela (ssh root@bela.local) and change the branch:# in BelacdBela
gitcheckouttmpYou can check the commit hash by runninggit rev-parse --short HEADeither on Bela or your laptop.3. Add the watcher library to your projectFor pybela to be able to communicate with your Bela device, you will need to add the watcher library to your Bela project. To do so, you will need to add the filesWatcher.handWatcher.cppto your Bela project. You can do this by copying the files from thewatcherrepository into your Bela project. To do so, you can run:scpwatcher/Watcher.hwatcher/Watcher.cpproot@bela.local:Bela/projects/your-project/Getting startedModes of operationpybela has three different modes of operation:Streaming: continuously send data from your Bela device to your laptop.Logging: log data in your Bela device and then retrieve it from your laptop.Monitoring: monitor the state of variables in the Bela code from your laptop.You can check thetutorialsattutorials/for more detailed information and usage of each of the modes.Running the examplesThe quickest way to get started is to start a jupyter notebook server and run the examples. If you haven't done it yet, install the python package as explained in theinstallation section. If you don't have thejupyter notebookpackage installed, you can installed by running (replacepipwithpipenvif you are using a pipenv environment):pipinstallnotebookOnce installed, start a jupyter notebook server by running:jupyternotebook# or `pipenv run jupyter notebook` if you are using a pipenv environmentThis should open a window in your browser from which you can look for thetutorials/notebooksfolder and open the examples.Basic usagepybela allows you to access variables defined in your Bela code from python. To do so, you need to define the variables you want to access in your Bela code using theWatcherlibrary.Bela sideFor example, if you want to access the variablemyvarfrom python, you need to define the variable in your Bela code as follows:#include<Watcher.h>Watcher<float>myvar("myvar");You will also need to add the following lines to yoursetuploop:boolsetup(BelaContext*context,void*userData){Bela_getDefaultWatcherManager()->getGui().setup(context->projectName);Bela_getDefaultWatcherManager()->setup(context->audioSampleRate);// your code here...}You will also need to add the following lines to your render loop:voidrender(BelaContext*context,void*userData){for(unsignedintn=0;n<context->audioFrames;n++){uint64_tframes=context->audioFramesElapsed+n;Bela_getDefaultWatcherManager()->tick(frames);// your code here...}}you can see an examplehere.Python sideOnce the variable is defined "in the watcher", you can stream, log and monitor its value from python. For example, to stream the value ofmyvarfrom python, you can do:frompybelaimportStreamerstreamer=Streamer()streamer.connect()streamer.start_streaming("myvar")to terminate the streaming, you can run:streamer.stop_streaming()TestingTo run pybela's tests first copy thebela-testcode into your Bela, compile and run it:rsync-rvLtest/bela-testroot@bela.local:Bela/projects/
sshroot@bela.local"make -C Bela stop Bela PROJECT=bela-test run"you can run the python tests by running:pythontest/test.py# or `pipenv run python test/test.py` if you are using a pipenv environmentBuildingYou can build pybela using pipenv:pipenvinstall-d# installs all dependencies including dev dependenciespipenvlock&&pipenvsync# updates packages hashespipenvrunpython-mbuild--sdist# builds the .tar.gz fileTo do and known issuesTo do:Upload to pyPI (so that the package can be installed usingpip)To do:Upload built package toreleases(so that the package can be installed usingpip install pybela-<version>.tar.gz)Issue:Monitor and streamer can't be used simultaneously –  This is due to both monitor and streamer both using the same websocket connection and message format. This could be fixed by having a different message format for the monitor and the streamer (e.g., adding a header to the message)Issue:The plotting routine does not work when variables are updated at different rates.Issue: The plotting routine does not work for the monitor (it only works for the streamer)Code refactor:There's two routines for generating filenames (for Streamer and for Logger). This should be unified.Possible feature:Flexible backend buffer size for streaming: if the assign rate of variables is too slow, the buffers might not be filled and hence not sent (since the data flushed is not collected in the frontend), and there will be long delays between the variable assign and the data being sent to the frontend.Issue:Flushed buffers are not collected afterstop_streamingin the frontend.Bug:OSError: [Errno 12] Cannot allocate memoryLicenseThis library is distributed under LGPL, the GNU Lesser General Public License (LGPL 3.0), availablehere.