Developing Apps
Debugging apps
This section gives some guidance on how to develop and debug bridge-apps. Everyone will have their own preference, so this is mainly guidance from a personal perspective. The guidance is given from someone who tends not to use IDEs, but for those who do like IDEs, we have had some good experience using JetBrain's PyCharm IDE.
Getting started: copying an existing app.
To deploy an app, it needs to be in GitHub, so GitHub is a good place to start. In your GitHub account, click on "New Repository". Give your new repository a name and a description and initialize it with a Readme. After you've created it, click the "HTTPS clone URL" on the right-hand side of the GitHub repository page and copy it to the clipboard. You can then cd to ~/apps_dev (create the directory first if it doesn't exist) and git clone your new repository. Eg:
git clone https://github.com/ContinuumBridge/my_app.gitYou can then git clone an existing app repository. Eg:
git clone https://github.com/ContinuumBridge/demo_switch_app.git
And copy the files from this into your new repository.
Once you've written the first version of your app, you'll need to register it so that it will appear in the portal and you can add it to your bridge (as described in The ContinuumBridge Portal section). Do this as described in the “deploying apps” section. Once you've done this, if you refresh your browser tab, the app will appear in the “app market” and you will be able to add it to your bridge and connect devices to it.
We tend to do most debugging using logging. ContinuumBridge has a logging methodology built on top of Python logging that puts logging messages from all apps and adaptors, along with the cbridge core modules, in the same log file (from v0.7.8 of cbridge onwards, these are /var/log/cbridge.log and /var/log/cbshell.log). To write a log message, use the cbLog method in your app:
self.cbLog(LOGLEVEL, "a string")
where LOGLEVEL is one of:
debug
info
warning
error
critical
For example, you can write things like:
self.cbLog("debug", "switchID:" + self.switchID)
This writes the value of self.switchID to the file /var/log/cbridge.log (/opt/cbridge/thisbridge/bridge.log prior to v0.7.8 of cbridge). This file contains logging from all apps and adaptors on the bridge, as well as from cbridge itself. Each line has a timestamp, which makes it easier to see what is happening in your app relative to other things that are happening on the bridge.
The level of logging is controlled using the CB_LOG_ENVIRONMENT variable, which is set by editing the file /opt/cbridge/thisbridge/thisbridge.sh, and including the line:
export CB_LOG_ENVIRONMENT='debug'
replacing “debug” with the required level. There are five levels of logging: debug, info, warning, error and critical. The example above uses debug. The debug level displays all messages that are labels as debug, info, warning, error and critical; the info level just displays messages labelled as info, warning and error, as so on.
There are examples of the use of logging in the ContinuummBridge example apps. For example, you can include lines such as:
self.cbLog("debug", "Trying to turn on/off before switch connected")
self.cbLog("debug", "received message: " + str(message))
Remember that the second parameter of self.cbLog must be a string, so you need to cast other types (eg: integers, floats, dictionaries, lists) to strings, as in the above example.
It's common to want to log a message that may have been received from an adaptor. This can be made more readable in the log file using json.dumps() with an indent, as in this example:
self.cbLog("debug", "onadaptorData, message: " + str(json.dumps(message, indent=4)))
Now that this is all in place, you can run your app. Having added it in the portal, remember to press “Update” to download the configuration to the bridge (this requirement will go in a future version). Then press “Restart” to restart cbridge with your app. We tend to debug by tailing the log file and also the shell.log file in a separate shell:
cd /var/log
tail -f cbridge.log cbshell.log
All logging messages appear in cbridge.log. If your app crashes then the traceback information that Python would normally write to the screen is written to cbshell.log. Cbridge uses rotational log files. The maximum size of cbridge.log is limtied to 1 MB, after which it will be renamed to cbridge.log.1. In all, five log files of this form are kept before the oldest one is deleted.
Various environment variables can be set in /opt/cbridge/thisbridge/thisbridge.sh. We've already looked at CB_LOG_ENVIRONMENT. Here are the others that you can set. The file also contains various other variables (such as the key for accessing the bridge controller), which you must not change.
| Variable | Allowed Values | Description |
|---|---|---|
| CB_DEV_BRIDGE | True, False | f true, this is a development bridge. Apps and adaptors can be located in the apps_dev and adaptors_dev directories in the user's home directory. |
| CB_DEV_APPS | String | A list of app names separated by commas. Eg: 'app1, app2'. These are the apps that the bridge will look for in apps_dev. |
| CB_DEV_ADAPTORS | String | A list of adaptor names separated by commas. Eg: 'adaptor 1, adaptor2'. Behaves as CB_DEV_APPS. |
| CB_USERNAME | String | The name of the user where apps_dev and adaptors_dev is located. If you are thce default “pi” user, you should set this to pi. |
| CB_ZWAVE_BRIDGE | True, False | This is set to True if a Razberry Z-wave board and associated software are included on the bridge. |
Set each of these as an environment variable using an export statement, as in the debug example, above.
Deploying apps
You can copy an app to the apps_dev directories on as many Raspberry Pies as you like and use them in development mode, but if you want to distribute it widely you will probably want to put it in the ContinuumBridge App Market. It can then be found by anyone with a bridge by clicking on the “Download Apps” button on their user portal. Currently, all bridge-apps are deployed via Github and the process is as follows. A basic familiarity with git and GitHub is assumed.
Firstly, ensure that the code you want to deploy is in Github and tagged as a release. Eg: v1.0.0. If you're new to GitHub and writing a simple app, push your code to GitHub using the following commands (for an app called "mylovelyapp"):
cd ~/apps_dev/mylovelyapp
git add .
git commit -m "A helpful comment"
git push
Once you've pushed your code to GitHub, you can tag it as follows:
git tag -a v1.0.0. -m "The first version of my lovely app"
git push --tags
Navigate to the release in Github and copy the link address of the tar.gz file for the release. This will be of the form:
https://github.com/ContinuumBridge/mylovelyapp/archive/v1.0.0.tar.gz
Next, you need to create a JSON configuration file in the home directory of your app. For the example we used, the following text would be put in the file: ~/apps_dev/demo_switch_app/config.json
{
"name": "Demo Switch App",
"url": "https://github.com/ContinuumBridge/demo_switch_app/archive/v1.0.0.tar.gz",
"exe": "demo_switch_app.py",
"description": "Controls a switch using binary sensors",
"provider": "ContinuumBridge",
"version": "1.0.0"
}
The keys have the following meanings:
| "name" | The name of your app. This appears on the user portal and should be a human-friendly name. |
| "url" | This is the link to the GitHub release, as described above. |
| "exe" | The app executable that the bridge manager should run when it starts your app. |
| "description" | This can be as long as you like and tells a user what your app does. |
| "provider" | Your name or the name or your organisation. |
| "version" | This should correspond to the release tag. |
Next, for this example, you would go into the app's home directory and initialzse the app, as follows:
cd ~/apps_dev/demo_switch_app
cb --app post config.json --user <user name> --password <password>
If you leave out the user name or password you will be prompted for them (and you can type the password without it being visible).
If you get any error or warning messages, then make any corrections necessary, otherwise you should find your app on the portal. The cb --app command alters the config.json file. It's a good idea to add, commit and push this to GitHib, so that everything is up to date.
You can check that your app has been successfully deployed by typing:
cb --app get config.json --user <user name> --password <password>
You will also see your bridge-app in the portal, but you'll need to refresh the tab of your browser first.
The cb command
A full list of cb commands can be found here: The cb Command
To check that the deployed app works on your development bridge, you can switch your Raspberry Pi back from being a development bridge to a standard bridge by removing the line that says export CB_DEV_BRIDGE='True' from /opt/cbridge/thisbridge/thisbridge.sh or by setting the value to 'False'. You'll then need to restart cbridge by typing:
sudo service cbridge restart
You can also use the commands "start" and "stop" instead of "restart" with the above.
Then go to the portal and press Update (note: not Upgrade), followed by Restart. When you press Update, you should see a message saying that your app has been updated. Congratulations!
A simple development process
With a simple app, as you make releases, you'll probably find it easiest to adopt a process like this:
cd ~/apps/mylovelyapp
# To make sure you have the latest code:
git pull
Edit and debug your code
Edit config.json and change the url and version values. Eg: from v1.0.0 to v1.1.0
# Note you use patch rather than post after the first time:
cb --app patch config.json
git add .
git commit -m "Added some wonderful new features"
git push
git tag -a v1.1.0 -m "Added some wonderful new features"
git push --tags
Updated less than a minute ago