Monday, December 28, 2015

Getting started with visual programming using Evothings Studio


Last post I described how this crazy idea came about, but I realized that I really needed to write a short introduction, for two reasons;

1. The Evothings node-red front-end parser works a little differently than the usual node-red run-time.
2. It's not really clear where to go next when you've downloaded and started the node-red version of Evothings Studio.

But why?

Yes, why would you anyway? My hope is that many people would welcome an even easier route to getting started doing IoT  apps. Evothings studio is the quickest route that I know of at the moment, given that you don't mind doing cross-platform JavaScript development and baking your app with cordova at the end.

Still, Evothings Studio is all about JavaScript, and if it's not your first programming language, there can be a lot of sharp corners to cut yourself on. 

By packaging access to some of the Cordova and JavaScript BLE APIs as visually composable modules (in the node-red editor), I hope that it becomes even easier to create and experiment with apps the communicate with sensors or other Bluetooth devices.


1. Download the Node-red branch build of Evothings Studio here;

2. Unpack it in your home directory (*NOT* under C:\program files or the like, if you're running Windows)

3. Make sure it runs, and looks reasonably like this:

What you're running now is essentially the latest beta of Evothings Studio 2.0, but with a couple of modifications, so everything you'd like to do with the original studio (and it's quite a lot), you can do here as well. The modifications cooks down to a new button for each of the projects under 'My Apps' (any front-end project, really, that can be anywhere on your machine) that let you launch a node-red editor and create+edit a flows.json file in the directory where the index.html of your project resides.

4. Go to the Examples tab, and note the two projects 'Hello Node-Red World' and 'Node-Red Front-End TI Sensortag'.

The two examples are the only ones that you can actually use directly, if you want to see how the node-red editor works together with the studio to push out incremental changes to your mobile.

5. Speaking of which, it's time to install the viewer on your phone. Here's the link for iOS and Android, and make sure it runs and looks like the image below;

6. To connect your phone and the studio, you generate a one-time key in the studio and enter it on the phone.

7. Now, you should have one client connected at the lower right status field of the studio. You re now ready to rock! If you want to avoid entering a new code every time you have crappy connectivity, you can log in (using github, google or plain email) to the proxy to make it preserve the session.

8. Now copy the example project 'Hello Node-Red World' from the examples tab and by clicking the 'COPY' button next to it. When you are done, you're taken to the 'My Apps' tab where the new project will show up.

By clicking 'CODE' the studio open a system file browser that shows the root of the directory, to let you edit the files using your favorite editor. These files are a bit doctored to load and parse node-red flows.json files and to populate the mobile web page with the widgets that are defined there. You can of course edit the index.html and everything as you wish, and do both classical and node-red development at the same time (as long as you don't bork the node-red front-end stuff).

9. Click the 'RUN' button to push out your project to your mobile phone. It will (hopefully) like a bit like below when it lands;

Not a beauty, by any means, but does contain a bare-bones examples of what a simple node-red front-end app could look like.

If you have any Bluetooth devices around, you can click 'SCAN' which lists all found (until you press the button (now saying 'STOP SCAN') again). Clicking on one of the found devices will list its services in a separate list.

OK, not very impressive.- Seen it before - yawn, right? But what I want to highlight here is not actually the functionality of the app but how it was made. 

10. If you go back to the 'My Apps' tab on the studio, now click the 'NODE-RED' button, which should bring up the visual node-red flows editor for the current project.

All node-red front-end apps must begin with a 'Page' module, which has connections to all other visible widgets under it, normally organized by 'Section' modules. Visible stuff like sections, buttons and so on are connected to each another sort of like a DOM tree, but after that, the connections between modules actually defines message-passing.

For example, the 'Scan' module is actually a Button module, which has been renamed to Scan. it will implement a Material Design Lite Button and when it is clicked, a message will be passed to whatever other module(s) it is connected to.

This button connect to two other modules - a function and a module called 'blescan'. Let's look at the function;

All modules (including functions) gets passed one argument object called 'msg'. The convention is to have a property of msg called 'payload' which contain the important parts. 

The payload passed by a button is the DOM event object of the click, which is then used to determine which new text caption the button should be set to. So buttons also can receive messages, and will change caption to that of the payload.

But the interesting thing with functions is that you can add them anywhere and use them to debug messages being passed. And now we come to a very nice thing with Evothings Studio itself - that you gets logs back from the running app on the phone, continually.

11. Click on the blue button named 'Tools' in the main Studio app window. you now get a new window with two parts - a small editor at the top (already populated with examples to try out) and at the bottom an area which display the logs from your app.

So if we add a log statement to the function, like this;

It will result it some logs in the Tools window when the button is pressed.

And, it turns out, quite a lot of my own silly happy-go-lucky developer logging while I'm making the nrfe-widgets. I should probably clean those up a bit. :) But what I wanted to show here is ..

1. You can develop apps visually in the node-red editor and still get quite a lot of functionality.
2. The widgets will look sort of OK without *any* efforts at styling.
3. The program that scan for BLE devices and then list the services of a selected one contained only three lines of code, over two functions (the other picked a property of the incoming message and sent it as output).
4. Three lines of code that you write yourself, for a bespoke app, is a sweet small number to maintain.

The modules have documentation included in themselves, so when you select a module in the node-red editor, the documentation comes up in a sidebar to the right. This is a very nice way of doing things from the creators of node-red, and helps a lot when just getting started. I haven't documented very well, but I hope that it is enough to get started.

Again, please let me know what you'd like to see next and if you've managed to make anything yourselves using the editor!

Over and out, for now.

Friday, December 25, 2015

All tomorrows lines of code

(That you don't have to write)


I've extended the open-source IoT web-app development tool Evothings Studio by slapping on the open-source node-red flow-based editor and a number of custom modules to let you generate mobile web-apps with little or no coding, that let you connect to and communicate with Bluetooth devices.

Downloads per platform;


OK, so the short version goes like this; I work as a lead developer at a small startup called Evothings.
We mainly do two things; a number of cordova plugins for BLE access to weird things and sensors, and an open-source developer tool for IoT mobile web-apps called Evothings Studio.

The idea is to provide a workflow where you as a developer can iterate quickly using the Evothings Viewer app (from either app-store) that connects to the Evothings Studio desktop application (both are open-source and on Github) so that the studio pushes any changed files in your projects out to the viewer, which reloads and send logs continually back to the studio.

OK, so far? Good. About now you'll wonder how we make money :). Currently we're just providing open-source projects and a free service (we have a proxy that let you connect your viewer(s) and your studio avoiding any client-isolation issues with local WiFi).

The basic service will always be free for small usage, but we're busy creating cool stuff on top of it that we hope people will find valuable early next year, or thereabouts.

Notice that the studio comes packed with a lot of IoT app examples, some geared towards specific hardware like Arduino, Eddystone beacons or the TI Sensor-tags. That's all open-source too and easy to copy to your own project to get a head start.

So, about these visual boxes and stuff.

Right, right! OK. We got invited to IBM in Winchester a while back and while we talked about a lot of stuff, where one of the presentations got stuck in my head. It was a walk-through of another open-source project that IBM had created, called node-red.

Node-red is a flow-based editor that let you compose node.js programs visually, that then runs on the back-end when deployed. It's easy to install and try out and comes with quite a lot of cool components, like postgreSQL access, XMPP, MQTT, regular sockets, lots of other stuff - and at the end of the day you can deploy everything as a npm package.

What I was thinking was how cool it would be if one took node-red and added on top of it stuff that made it possible to create web apps, mobile, bluetooth enabled web-apps, specifically, and run them on a phone, incrementally while you're building it.

So I did that.

Or, more correctly, I started doing it. node-red has come quite a along way and it would have been a tall order to just implement all modules to work on the front-end, so I started creating custom modules instead. Modules are those boxes that show up in the visual editor that you string together to create flows.

I needed a hierarchy of modules both to organize visual widgets and to define how messages are passed between modules (widgets or non-visible modules, like the bluetooth scanner), so I used the flow graph in node-red for both.

The output of node-red is a single file called 'flows.json' which defines which modules are in the flow and any settings they have, in addition to how the modules are wired. I configured node-red to save the flows.json file in the home directory of the project being edited, and created a couple of open-source Github projects to make everything work together:

nrmodules (Which are mostly just filler plugins for node-red that makes new modules show up in the visual editor, published also as a npm module):

nrfe (node-red front-end. Yes, I suck at naming things. Welcome to the club. This is the web-app side parser for the flows files)

nrfe-widgets (where the actual functionality of the modules happens. These widgets is what the parser wires together according to the flows file)

The 'widgets' depend on the cordova-ble plugin to be present in the mobile app running the web-app (in addition to cordova itself), so the following example app can't run by itself in a mobile browser - you either have to load it from the Evothings studio into the Evothings viewer app, or build it as a proper cordova/phonegap app:

The hello-world project also includes the nrfe and nrfe-widget projects as bower installs, so rmember to run 'bower install' at first and then 'bower update' to get any new widgets being authored.

Some of the widgets are visual and are copied wholesale from the Material Design Lite library, and some (like the BLE scan) are not visual at all. Visual widgets need to be connected to a page or a section widget to be visible on the page, so for those kind of relations, the wires means something like a DOM hierarchy.

For non-visual widgets and for visual widget outputs, the wires mean something else - they define how messages are passed between widgets/modules. So the Button widget 'OK' is wired to the BLE scan widget, which will toggle scanning for bluetooth devices, and in turn send a small JavaScript object defining the found device as output message, and so on.

Please take this baby for a spin and let me know how hard you don't like it :) Or maybe what you'd like to see next. I'm planning to finish building modules for all bluetooth stuff like descriptors and next up is a module for MQTT.

And if I don't find time to write a mode detailed follow-up article before new year's eve, here's some festive inspiration:

EDIT: I *did* find some time. So here is that 'how to get started' kind of article: