microflo/microflo

Live dataflow programming for microcontrollers and embedded

MicroFlo: Live dataflow programming for microcontrollers

Unlike most other dataflow runtimes for constrained devices, MicroFlo run standalone on the microcontroller, can be introspected and reconfigured at runtime, and has built-in support for automated testing.

One can program with MicroFlo either:

• Visually, using Flowhub
• Textually, using the declarative .fbp DSL or .json definition
• Programatically, by embedding it and building a graph using the C++ API

MicroFlo is very portable, written in C++03 without exceptions and stdlib. It comes with support for multiple platforms,including Arduino and Embedded Linux. It has been used on many different devices, from Atmel AVR8 to ARM Cortex M0/M1/M3/M4 devices (LPC mbed, TI Tiva/Stellaris), ESP8266 and Raspberry PI.

MicroFlo is designed to integrate with other data-driven programming tools, including msgflo for easy building of distributed systems (IoT).

Using

For visual programming your Arduino, follow the microflo-example-arduino.

Support

MicroFlo is a part of Flowhub, a platform for building robust IoT systems and web services.
We offer an Integrated Development Environment and consulting services.

Status

Minimally useful.

• Works fine for simple programs
• Components exists for standard I/O on Arduino devices
• Live programming supported for most changes
• Basic support for automated testing

MicroFlo in the wild:

• Jon's fridge thermostat has been running uninterrupted since September 2013.
• The Ingress table at c-base station, Berlin uses MicroFlo to control the lights. One major upgrade/bugfix since March 2014.
• The lights on the CNC-milled Christmas tree at Bitraf, Oslo ran for 4 weeks during Christmas 2013.

Contact

When you find issues: file bugs and/or submit pull requests!

Changelog

Past milestones

Extending

For porting MicroFlo to other microcontrollers, see how-microflo-works and target bringup.

License

MicroFlo is released under the MIT license.

Note that the platform MicroFlo runs on (like Arduino), and MicroFlo components may be under other licenses!

microflo's Issues

Internationalized components

Components should be able to have name and description, portnames in a localized language - at least in the UI. Internally we will use the (English) identifiers, of course.

Platform wishlist

Write here if you want to have another platform supported by MicroFlo, or if you are working on adding support.

The targets that are already working: Arduino
AVR8 support is in progress (see issue #5)

Support storing runtime UUID in EEPROM

• When flashing a microcontroller with MicroFlo for first time, generate a runtime UUID and store it is EEPROM
• When connecting to the runtime, it should respond with this UUID
• We should then attempt to register it with Flowhub and then ping it regularly

Flowhub should then notify us that the new runtime is available

Add support for enumerated types

An enumerated type could be represented inside runtime as an integer for the type, and an integer for the value. On JS/human-side each value should have a human-readable definition/descripton.
Usecases:

• Errors, see #6
• For deciding the operators on generic components like comparison (<, >, <=, >=, ==, !=), boolean primitives (NOT, AND,OR,NOR,NAND,XOR).
  Representing operators as data could perhaps also allow to have generic components/subgraphs/patterns for expressions?

Would also be nice if the types could be exposed to NoFlo UI, so it can show an enumerated list as a selector for IIPs.

MicroFlo is too big for Arduino Pro 168

Is there a way to strip out some components to get it to fit in smaller Arduinos?

Binary sketch size: 22,570 bytes (of a 14,336 byte maximum)
processing.app.debug.RunnerException: Sketch too big; see http://www.arduino.cc/en/Guide/Troubleshooting#size for tips on reducing it.
    at processing.app.Sketch.size(Sketch.java:1658)
    at processing.app.Sketch.build(Sketch.java:1591)
    at processing.app.Sketch.build(Sketch.java:1567)
    at processing.app.Editor$DefaultRunHandler.run(Editor.java:1897)
    at java.lang.Thread.run(Thread.java:744)

Python library for communicating with MicroFlo programs

It is important that people can communicate with MicroFlo programs from other things that NoFlo/JS. Adding a Python library would demonstrate that this is possible, and help people implement it for other languages/frameworks.

It is primarily sending/receiving data from exported output/input ports that is important. That way you can use it in similar ways as people now use Firmata.

We should standardize/formalize the protocol a bit, see #23

Allow multiple edges from single outport

The NoFlo UI allows to drag multiple connections from a single outport. This currently just leaves one with the last connection in MicroFlo. Instead data should be sent to all ports connected.
Proposed implementation: insert a Split component transparently to support this.

Support component editing through NoFlo UI

Currently when using NoFlo UI, one cannot add new (or change) MicroFlo components without going on the commandline, editing files and then restarting the microflo (JS) runtime. This makes the process of customizing components very tedious, and excludes it from a lot of users.

Instead, the NoFlo UI should offer an editor for components and MicroFlo should hook into this. This requires being able to send the source code (incl changes due to git/whatnot) across to NoFlo UI and also repond to source changes being done in the UI. When component source code has changed compared to what is on device/simulator, need to rebuild and reupload.

Build fails because of missing component

After the checkout npm install and npm test are passing without errors but when I try to upload graph or just run make I get this error:

In file included from lib/microflo/components-gen-lib.hpp:28:0,
from lib/microflo/components.hpp:57,
from lib/microflo/microflo.hpp:8,
from lib/microflo/main.hpp:94,
from src/firmware.cpp:17:
lib/microflo/components/LedChainNeoPixel.hpp:2:31: fatal error: Adafruit_NeoPixel.h: No such file or directory
#include <Adafruit_NeoPixel.h>
^
compilation terminated.
make[1]: *** [.build/uno/src/firmware.o] Error 1

I get this behaviour on Ubuntu 14.04 and ArchLinux

Allow one runtime adapter to host multiple microcontrollers

One usecase is to have one Linux box with toolchain and plug N microcontrollers into it, one per user in a educational/workshop scenarion. Each person can connect to the web interface of this machine and gets a microcontroller each to program.

Another usecase is to have one embedded Linux box, and multiple microcontrollers (over Ethernet, misc wireless) connected to form a bigger system. For instance factory or home automation. One can then connect to this central device and monitor/reprogramm all the connected devices.

This will require:

• Cleanup of runtime communication code into a class which can have multiple instances
• Dynamic registration of new microcontrollers (using udev for USB, network discovery)
• Having UI in Flowhub for selecting which microcontroller to use

Smarter scheduling

Currently components are naively scheduled. They all run all the time, get even amount of runtime and runtime allocation just iterates over the nodes.
Probably we should instead:

• Only give runtime to nodes which have messages pending (or are "generators" like Timer)
• Give runtime to nodes as they receive messages

Login functionality in Chrome App

Currently the Chrome App requires users to type in their Flowhub user ID. Instead, the app should simply do the OAuth dance with Flowhub using the chrome.identity APIs.

Embedded Linux platform support (RPi/BB etc)

While MicroFlo is primarily target for bare-metal usage on microcontrollers, it would be nice to also support running on full-stack embedded Linux machines. The main usecases are:

• Portability, being able to run something initially intended for Arduino on an RPi
• Improved real-time performance over NoFlo/Node.JS (more deterministic)

The runtime itself is already capable on Linux, but there is no IO backend for common ports/protocols, or good way to build an executable.
Also, there would probably be a need for a FBCS transport between runtime and host which does not require special hardware (sockets?). This could be used also for interactive simulation.

Add AVR8 backend which does not rely on Arduino

To be useful as a MIT-licensed library by proprietary applications, we cannot depend solely on the LGPL-licensed Arduino libs.
In addition, having a separate backend would be a good validation that we can indeed support other devices.

Only unknown here is to come up with a sane port/pin mapping/encoding strategy. Toss-out idea: 0-7 for PORTA:0-7, 8-15 for PORTB:0-7 and so on

Support outports on MicroFloComponent (for NoFlo)

Currently only inports are working. Need to clean up the host parts handling the transport singificantly, not just for this to work but also for live re-programming etc.

Document, create example and automated test for C++ embed API

For good reasons and bad, some programmers may not want to use all of MicroFlo.

Most relevant APIs (reusable and useful):

• IO
• Network + Component

May even highlight that one is not forced to use the message passing functionality of Network, can always resort to shared-state if one really wants...

Support components defined by graph (subgraphs)

It should be possible to define a new component using a FBP graph.

Usecases:

• Compose reusable components easily
• Structure larger programs
• (possibly) To encapsulate an entire program and give it in/out-ports, that a program running on a different microcontroller can send messages to/from

Should be possible to define such a component both using the .json syntax and .fbp syntax.
Should be possible for a component defined by a graph to use a component defined by a graph (recursively).

Implementation ideas:

• Allow to declare component with subgraph in components.json, either as inline JSON or path to a .fbp/.json file
• Create a special Component subclass which has-a Network for the subgraph.
• Add start-subgraph and end-subgraph to the graph commands, indicating that the commands in stream between these belong to a subgraph
• Add commands to configure how exported ports (visible on component from outside) is mapped to child nodes/ports in the subgraph. Could perhaps reuse existing connect command, with a special value indicating connection to/from parent (value 0 perhaps?)

Investigate compiling runtime to JavaScript for clientside

The runtime is very simple C++ and does not need a standard library, so compilig it to JS with for instance Emscripten seems feasible. We already have a JS library which makes accessing from JS nice.
The communication bridge between runtime and lib would need to be redone, but going forward this should be pretty small as it will be entirely based on binary command-stream protocol.

This would allow to do simulators entirely on client-side, which simplifies deployment - both from setup and security perspectives.

Too fat to fit on AtTiny85 devices

Not originally a hardware target, but being able to run on at least the ATtiny85 used by these Olimex boards would be nice: https://www.olimex.com/Products/Duino/AVR/OLIMEXINO-85-KIT/open-source-hardware

Main issue is the large program code size (around 20Kb). I suspect that this can be reduced massively by correctly using uint8_t instead of int where appropriate in the framework code.
Also, it might be necessarily to be able to selectively include components (ref #3)

Other issue here is the hardcoded and fairly large MAX_NODES and MAX_MESSAGES defines in the source code. These should be replaced with defines that:

1. Have the MICROFLO_* prefix
2. Check if there are already defined values passed, and if not, falling back to a sane value (like those it has now).

Related, there should also be error checking against exceeding the maximum message and node size, reported back to host.

One should then be able to specify these values in a sketch, or on commandline when generating, and when values are fairly small (say 20 and 20) SRAM usage should be < 2-300bytes instead of the 700bytes today.

Implement host communication support

Currently the MicroFlo runtime will use the primary serial port of the microcontroller for sending control data, meaning that applications cannot really use the SerialIn / SerialOut components for communicating with the host on that port.

Proposed implementation is to allow programs to define external ports, which are visible to the host (both input and output) and allows to communicate anything which can be represented as a Packet between the two. A JavaScript function / NoFlo component should do the necessary data type conversions, and easily allow to create data adaptors to Open Sound Control, WebSocket and similar.

It may be beneficial to use the same communication paradigm for the MicroFlo host-simulator code.

This is somewhat related to both #6 and #4

Nicer support for component libraries

It should be possible to add components to use in a MicroFlo based program without making changes to MicroFlo itself.

Usecases:

• Application-specific components
• Proprietary components
• Community components, avoids having MicroFlo upstream as a bottleneck

For future, it should also be possible to have JS/NoFlo (UI) components defined in the same library for simulation/debugging/visualization, as well as unit tests and examples.

Should follow conventions established by NoFlo and Arduino where it makes sense. Very advantagous if npm (or similar) could be used as a package manager.

The components provided by MicroFlo itself should use the same mechanism as "external" libraries.

Ship a standalone runner application

Currently one has to run the MicroFlo JS code in a console, and then open the UI in a browser. This is quite inconvenient for end-users, who expect a one-click solution.

The application should mainly be a WebView for showing the UI and some management code for keeping the microflo.js code running.
If the web engine is new enough, on could for instance use Qt and QtWebKit for this.

At the same time it would be practical to also include the dependencies in the bundle: Arduino toolchain, Node.JS.
In future, we might also need to include ino or similar to do FW builds without the Arduino IDE.

Make graph changes to runtime live, do not require "Play"

Right now one has to explicitly do "Play" in NoFlo UI. But really, graph changes should just be uploaded as the user does them. This should make the workflow of prototyping/experimenting much faster/smoother.

At the same time, we should probably fix the useless delays in serial send/upload process (setTimer stuffs).

Support introspecting graph edges (data flowing through connections)

NoFlo (UI) allows to watch data flowing through the connections of a graph. MicroFlo should be provide the same user experience.

Proposed implementation

• Add command stream commands for subscribing/unsubscribing to edges
• Use the MessageSent command to pass the data, incl edge description
• Pass this on to NoFlo UI using same WebSocket API that NoFlo uses (port-to-port FBP API?)

Probably does not matter if edges are identified using src+srcPort or target+targetPort, as we don't allow multiple connections either way.

Longer term it might be wanted to have watch-expression or perf counters on edge connections, to limit the traffic between device and host (typically on serial).

"upload" command broken

Bug split out from #2

When doing "node microflo.js upload examples/monitorPin.fbp" on Windows 8 in Parallels 8 on Mac OSX with Arduino Nano R3, the graph parser enters an invalid state and just outputs

Network stopped
DEBUGLEVEL: Error
ADD: in ( Timer )
ADD: split ( ToggleBoolean )
ADD: outA ( DigitalWrite )
CONNECT: in out -> split in
CONNECT: split out1 -> outA
Network started
DEBUG: ParserInvalidState

Probably a serial port initialization/timing issue, as when using the runtime it works OK.

Support persisting uploaded graph to EEPROM

Right now, you can either bake a graph into the binary and flash it, or upload a graph at runtime. However, when starting up the microcontroller will always load the graph that was baked in.

There should exist a command for persisting the currently running graph to EEPROM, alternatively uploading a new graph should always be persisted.

Ideally, graph persistence should be an atomic operation.

Allow to manipulate graphs visually: integrate with NoFlo UI/IDE

Requires graphs to be loadable over serial.
Probably implement noflo/noflo#107

Examples wishlist

Please comment here if you are lacking an example on how to do a particular thing.

Add minimal support for error handling

Error can come from two sources: the components in use, and the runtime/framework itself. A system for handling these in a standardized way is needed.

Should be possible for applications to have a central error handler component.
Unhandled errors should be caught by framework, and have sane default behavior that makes the easy to catch and gives incentive to handle it. Output it on serial port, and then reset the device?
The JS side should be able to map errors to a textual description of the error.

Ideally the UI would require people to wire up error ports to an error handler, and MicroFlo would ship a set of default error handler components.

Proposed implementation:

• Allow to declare errors in the components.json file, numerical id and a textual description
• Use an "error" port on components for emitting errors (convention)
• Errors are a new message/packet type, which contains "domain" (runtime/componentset) and "errno"

Evaluate and benchmark current performance

On at least a typical Arduino (AVR atmega 32u4/328).

Minimally

• RAM usage scaling with number of nodes
• Message passing/ marshalling overhead

Deliver pre-built applications continiously

Right now we require a C++ compiler for the host to be able to install MicroFlo. This is extremely tedious on prop. platforms like Mac OSX and Windows where people usually do not such a compiler and getting one is a lot of effort.
The reasons are, right now, our own C++ Node.js addon (could be made optional) and the "serialport" module which we depend on.

Ideally this would be done using Travis-CI, but they do not support Windows yet, see travis-ci/travis-ci#216

Short-term fix is maybe to build node-serialport for Win+OSX, and preload the bundle with this library. I guess we might also load in the other Node dependencies, at that point...
We would need to make some logic that automatically picks the right Node.js module depending on platform, or failing that, create different bundles (annoying)

Attempting to upload a smaller graph than baked-in fails

When the serial connection is opened, device resets and the buildup of the baked-in graph is emitted on the serial, and the code tries to resolve node/port references to this graph with the graph its trying to upload (which is likely different).

Part of a bigger problem that we don't have any identifiers for the graph or component libs stored in the runtime, so talking with a running device requires some out-of-band information about this.

Add minimal support for on-device automated testing

Test should be driven from Mocha/JS, and be able to execute things on-device.

An environment variable or command-line switch should be used to select that
on-device tests should be run, and which device it should use.

A minimal test could be one that determines how many nodes we can instantiate on an Arduino, as we've had problems with hitting this out-of-memory condition several times already. Its also hard to debug and is an important measurement of how MicroFlo scales.

Tests should upload new firmware to the device as a setup-step.

Longer term, it should also be possible to run the same tests against the runtime on x86. More details found in https://github.com/jonnor/microflo/blob/master/doc/braindump.md#testing-strategy

Standardize/formalize and document the FBCS protocol

Currently we use a hand-rolled .JSON format to describe the message (types) that can be sent using the MicroFlo FBCS protocol between host and device.
https://github.com/jonnor/microflo/blob/master/microflo/commandformat.json
It also does not describe the contents of messages at all.
It would be nice to move this to something standard like http://code.google.com/p/protobuf/
This should allow less manual serialization/deserialization on at least the JavaScript side, and make it easier for non-NoFlo code to communicate with a MicroFlo device. This is especially interesting for sending/receiving data on exported in/outports, but could also allow reprogramming from other environments.

Show examples in NoFlo UI

Currently the MicroFlo examples are just lying around in git, and it is not easy to make use of them when programming MicroFlo visually using NoFlo UI.
There are some facilities for having examples in the UI, and we should make use of these. It may be neccesary to extend the API to support multiple different runtimes.

The minimum benchmark here is the Arduino IDE, which has its examples in the file menu.

Online/hosted service for building MicroFlo firmware

We'd like people to be able to reprogram their MicroFlo-based devices from desktops/laptop but also mobile devices (primarily tablets, but also mobile phones) . These cannot really build the firmware required when one changes components, even when they do have the API/connectivity to flash them.
We could host a set of compilers as a service, and allow Flowhub to use this over a web API. The guys over at http://mbed.org have their primary workflow oriented around this.
We could perhaps integrate their service for handling the targets they support.

Add minimal device simulation support

It should not be necessary to have a microcontroller/Arduino present to be able to play with, prototype and develop MicroFlo programs for a device.

It needs to be possible to simulate pheripherals connected to the microcontroller. Component libraries should be able to provide elements for that, see issue #3

The MicroFlo project should host a public website where people can use the simulator without downloading it to their computer.

Proposed implementation:

• Base on NoFlo UI, hook in custom simulator components and user interface modules
• Use OpenShift Online for hosting service

IP-based transport for FBCS protocol

To enable connecting microcontrollers in different ways than just serial-over-USB/BT/foo, some IP based transport would be nice, for use over WiFi/Ethernet.
Example microcontroller includes https://mbed.org/platforms/mbed-LPC1768/

At the same time we should probably add some keep-alive type communication to the protocol, to detect presence/availability.
How to handle discovery? Bonjour/zeroconf probably has wayy to much overhead?

Current thinking is to consider untrusted networks (Internet) outside of scope, and that one would use something like NoFlo and the NoFlo protocol as an adapter in that case, or tunnel through something which provides encryption, for instance a VPN solution.

Add Windows support

At least releases should work on Windows, possibly by piggy-backing on the Arduino IDE to build & flash the runtime to the device. The Node/JS can run from cmd.exe in first iteration.

Support power-saving/sleep states

Right now, we always run at full throttle. When the program is idle, the runtime should automatically put the microcontroller into a sleep state.

We need smarter scheduling to enable this, see #39

Integrate directly into Flowhub Chome app

Currently we have a Chrome app which handles the MicroFlo-specific things, and user has to run this in addition to Flowhub. We should get rid of this app and integrate into Flowhub directly.
This also enables use on mobile devices (iOS/Android), where one cannot reasonably multitask between multiple apps.

Use noflo.Graph

Currently we have our own (ugly) code for both runtime communication and graph state handling in JavaScript. When we redo this, adopt the NoFlo classes to reduce the amount of custom code.

Allow to flash (pre-built) image onto microcontroller

Should have API to do this from within the Chrome app.
This is a subset of the functionality needed for general reprogrammability from the UI (#21), tailored for the initial upload of the MicroFlo runtime.

Probably will first support Arduinos, and do something like
http://jeelabs.org/2013/03/27/avrdude-in-coffeescript/

Component wishlist

Please comment here if you are lacking a component for a specific task.

USB/serial automatic discovery

Will have to use some heuristics on serial device metadata, and then try to open each device to check if it responds to the init message of the MicroFlo protocol

Allow to persist graphs directly from UI

Embedding or otherwise persisting a graph to the firmware image is currently a very tedious, manual process. Instead this should just be a button in the UI.
Depending on how well it works, it could perhaps be the default behaviour of "Play/run", and no other button needed.
#7 is an enabler for this.

0.4.0

Allow adding and modifying components directly from UI

Modifying components is currently a very tedious and manual process. Ideally this is integrated in the UI/IDE.

• APIs needed in NoFlo WebSocket protocol. getsource/setsource, update component, progress API for build/upload, and some way of communicating compilation errors etc.
• UI implementation in NoFlo UI
• backend implementation in MicroFlo

For good integration, the backend would have to be able to build the firmware with new components and upload directly to the microcontroller. This would also mean that user does not need to dead with the Arduino IDE anymore.
However, unless we intend to ship our own toolchain, it will still be neccesary to have it installed.

Error: Cannot find module 'commander'

Hi there,

I was trying microflo using the instructions in wiki and I got:

C:\microflo-master>node .\microflo.js runti
me

module.js:340
    throw err;
          ^
Error: Cannot find module 'commander'
    at Function.Module._resolveFilename (module.js:338:15)
    at Function.Module._load (module.js:280:25)
    at Module.require (module.js:364:17)
    at require (module.js:380:17)
    at Object.<anonymous> (C:\microflo-master\microflo.js:934:21)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Function.Module.runMain (module.js:497:10)

So you should add node dependencies somewhere in the docs:

• commander
• pkginfo
• fbp
• noflo
• serialport

And that you have to install

• python

Bye
Piero

Update NoFlo UI to lastest on the-graph branch

Lots of things have happened in NoFlo UI, we should update before next release.

• Update JSON protocol. Subgraph ids + from/to -> src/tgt
• Bundle the new UI
• Test to see that everything still works

Our patch for adding MicroFlo to the list should also now not be needed anymore.