Openframe Development Environment
If you’re planning to hack on Openframe, you’ll want to set up a dev environment which makes it easy to update code and see the results right away. Openframe uses familiar tools like GitHub, Node, and NPM, and we’ll use some of the standard development practices of these tools to get setup.
This guide is for people developing on the Raspberry Pi. Here we’ll describe setting up an environment suitable for working on the Openframe frame controller and modifying or developing new extensions. This setup will still use the public Openframe server, so you can use your account at openframe.io to add and push artwork to your modified frame.
- Create an Openframe-ready SD Card following the Frame Setup Guide. Enable SSH and, optionally, setup Samba.
- Fork the Openframe repo, and any extension repos you plan to work on / mess around with.
- On the Pi, clone each forked repo, and
npm installtheir dependencies.
- In each of the extension repos, use
npm linkto create a global symbolic link for this npm package
- In the Openframe repo, use
npm link [extension-a-package-name] [extension-b-package-name], passing each linked extension package name.
- In the Openframe repo, run
npm start. Now Openframe is running from the source code, using the source code of the extensions.
- Get to work. You can SSH into the Pi and edit files directly there, or use Samba to mount the files on your computer and work on them with your favorite editor.
The Long Version
Create an Openframe SD Card
In order to make sure the Pi has all of the necessary dependencies installed, the simplest thing to do is to set up an SD Card following the Frame Setup Guide. Make sure you’ve got an Openframe account and that you can log in and push artwork to your frame. You probably don’t want to enable ‘autoboot to Openframe’, since you’ll be launching Openframe yourself.
It’s helpful to enable SSH on the Pi so that you can edit files remotely. If you’re comfortable setting up and using vim (or whatever editor) on the Pi and doing your development work there, that’s fine. If you’d prefer to use your usual editor, you can use Samba to mount the Pi’s file system on your computer and edit the files directly.
There’s a good tutorial on setting up Samba on the openFrameworks site.
Fork the Openframe Repo
You’ll want to fork the Openframe repo to your own GitHub account. This way you’ll be able to keep track of your work and contribute bug fixes or enhancements 😄.
More info on forks and the GitHub collaborative workflow is available on the GitHub site.
Clone and Install the Repos to the Pi
On the Pi, clone your forks of the repos you want to work on, and install their deps:
$ git clone email@example.com:mygithubusername/Openframe.git $ git clone firstname.lastname@example.org:mygithubusername/Openframe-Image.git $ git clone email@example.com:mygithubusername/Openframe-MyNewExtension.git $ cd ~/Openframe && npm install $ cd ~/Openframe-Image && npm install $ cd ~/Openframe-MyNewExtension && npm install
As a quick test, after all deps have installed, run Openframe from source:
$ cd ~/Openframe $ npm start
Log into the Pi terminal, via SSH or directly, and
git clone your repos. You’ll clone your forked Openframe repo, and whatever extension repos you’re working on. These might be forks of existing extensions, or a repo for a new extension.
Once you’ve got the source code for each project on the Pi,
npm install in each repo directory to install all of the dependencies. Some extensions take quite a while to install!
As a quick test, you can run the Openframe from the source code and make sure it works. Just go to the Openframe project dir and type
npm start. If you’ve already logged in when you initially installed
openframe, the frame should start using the same credentials. It may ask if you want to autoboot, which you should decline.
NPM Link the Extensions
E.g., assuming you’re working on the Openframe-Image extension, and you’ve cloned all of the repos into the pi user’s home folder:
$ cd ~/Openframe-Image $ npm link $ cd ~/Openframe-MyNewExtension $ npm link $ cd ~/Openframe $ npm link openframe-image openframe-mynewextension
Extensions are just Node packages, following standard NPM package practices. They are specified by their NPM package name, as defined in the
package.json file. The package name must be all lowercase, and as a convention should follow the pattern 'openframe-[extension-name]’. For example, the Openframe-glslViewer extension has a package name of 'openframe-glslviewer’.
If you are indeed working on extensions, you need to make sure that the local version of Openframe you’re running is pulling in the local versions of the extensions. As this is a common need when developing inter-dependent projects, NPM provides a handy way of managing this. You’ll use NPM’s link command to create a global symlink for the dependencies, then use it again to tell the dependent project to use the symlinked version.
In each of the extension project directories, run
npm link. This will create the global symlink.
Then in the Openframe project directory, run
npm link [extension-name] [another-extension-name], passing each package name (from
package.json) for the extension repos you’ll be working on.
Get to Work
That’s it! Now the Openframe project will point to the linked extensions, so changes to the extension’s files will take effect immediately within the Openframe project. Great!
Whenever you make changes to files, you’ll need to restart Openframe on the Pi by running
npm start in the Openframe project directory.
Openframe uses (and encourages you to use!) the debug package. You can see the debug output by specifying the
DEBUG env var when starting Openframe. E.g. to see all debug output:
$ DEBUG=* npm start