HouseMon Circuits Tutorial-1.01

This post will cover the most basic concepts of circuit construction, using core gadgets that are included in the vanilla HouseMon build 0.9.0. I covered the initial overview of HouseMon circuits/gadgets etc in this post. I covered installation of a small circuit management tool I call ‘cirget’ that I will use in these tutorials in this post.

Change to your housemon folder:

cd ~/housemon

HouseMon 0.9.0 – embedded circuit

Vanilla HouseMon 0.9.0 has an inbuilt embedded circuit that is 'hard-wired'. This circuit starts the HouseMon database (leveldb), clears out old config data, supplies the 'current' binary version & runtime config data to the database, starts a http server (on port 5561) and only then starts any custom 'user defined' circuits that you provide. It does this by looking for a circuit called 'init' that you MUST provide.

'init' – the bootstrap circuit

As stated above HM 0.9.0 looks for a 'user defined' circuit called 'init'. This circuit is normally provided by a configuration file loaded by housemon upon startup. By default, this configuration file is called setup.json (but this name can be overridden).

So – if we want to have our new circuits utilized, we must have; at a minimum, a single circuit called 'init'.

Init

Init should be considered as the entry & exit point of our 'user defined' circuits. 'init' is just like any other circuit with the following constraints:

  • It must provide two externally labelled pins called In and Out.

As we can only have externally labelled pins if we have a gadget (or sub-circuit) to attach them to, this implies that we have at least one gadget with a pin that can receive messages (.In pin) and a gadget that can send messages (.Out pin).

The simplest circuit we can provide that meets this constraint, is one that we can map the .In and .Out pins to a gadget, and that passes data in and out transparently.

We can use the in built 'Pipe' gadget to do just this. It passes whatever it receives on its .In pin to its .Out pin. So we use this gadget and map those pins to the circuits externally labelled points called .In and .Out.

The first circuit in our tutorial is called 'minimal.yaml' and does just this.

For this next step, I am assuming you have followed the previous 'cirget' introduction post. We left that post by selecting the tutorial circuits library and selecting the default housemon circuit 'setup-master.yaml'.

We are now going to select the 'minimal.yaml' circuit.

issue a cirget 'status' command to remind yourself:

$ ./cirget status

In the list of circuits you will see the 'setup-master.yaml' is the active/selected circuit, and 'minimal.yaml' is listed as circuit 1.

Library Circuits: (* - denotes selected circuit)
------------------------------------------------
 0* setup-master.yaml
 1  minimal.yaml
 2  clock1.yaml
...

Lets select and load minimal.yaml by issuing the following:

$ ./cirget circuit 1
$ ./cirget -y

This will display the minimal circuit on screen as follows:

#A minimal HouseMon 0.9.0 Circuit - does 'almost' nothing.
---
  init:
    gadgets:
      -
        name: "dummy"
        type: "Pipe"
    labels:
      -
        external: "In"
        internal: "dummy.In"
      -
        external: "Out"
        internal: "dummy.Out"
  • We see at line 3, that the circuit is given the name 'init'. This name is important as stated above
  • At line 4 we start the list of gadgets this circuit will contain.
  • At line 7 we incorporate the in-built gadget 'Pipe' and at line 6 we give it a name 'dummy'; its an alias for the gadget within THIS circuit.
  • At 8 we start the labels of the circuit, an external name that we provide to an internal connection. As we have only one gadget called 'dummy' which is of type 'Pipe' we are mapping the Pipes .In pin to the circuits .In pin, and the Pipes .Out pin the the circuits .Out pin. Effectively wrapping a Pipe gadget and treating it as a circuit on its own.

This circuit does not do much, we are NOT providing any input, so no output will be provided. Running this circuit will make it look like housemon has hung. Try it by starting housemon (leave it running for a while whilst you read on):

$ ./housemon

You should see something like this:

Starting webserver for http://0.0.0.0:5561/
Lost flow.Tag: { init}

When you see the text:

Lost flow.Tag: 

it means that a message has arrived at a ‘send’ pin that has not been handled by any provided circuitry, effectively the end of the line. If our messages were trains on a train track, then our train has just crashed into the bumpers.

Still, our circuit is still running and trains are still able to travel from their stations around our track. To see that this is the case, we can open a web browser from another terminal and point it at our housemon instance on http://yourhousemonIP:5561/.

If I do that, my browser will probably not display anything (unless its cached some page data from a prior visit), but I will get output on my housemon console similar to:

Lost *url.URL: /style.css
Lost *url.URL: /base/circedit.css
Lost *url.URL: /base/vendor/angular-ui-router.min.js
Lost *url.URL: /base/vendor/angular/angular.js
Lost *url.URL: /base/vendor/bower-foundation-css/foundation.min.css
Lost *url.URL: /base/logo.png
Lost *url.URL: /base/vendor/angular-animate/angular-animate.min.js
Lost *url.URL: /base/vendor/angular-foundation/mm-foundation-tpls.min.js
Lost *url.URL: /base/nav.js
Lost *url.URL: /base/circedit.js
Lost *url.URL: /startup.js
Lost *url.URL: /base/vendor/d3/d3.min.js
Lost *url.URL: /base/vendor/ee3.js
Lost *url.URL: /base/jeebus.js
Lost *url.URL: /demo/demo.js
Lost *url.URL: /data/data.js
Lost *url.URL: /status/status.js
Lost *url.URL: /demo/demo.html
Lost *url.URL: /ws

These are messages from the inbuilt circuit that provided the default http server. The web server is providing these messages for us to use, but because we are not picking them up, they are hitting the bumpers.

Summary

Our ‘user defined’ circuit(s) are provided in a config file, normally called setup.json, this is a json formatted file, but we have been using a file format called YAML, and using the ‘cirget’ tool to provide the conversion. Its simpler to read than json imo.
We MUST have a circuit called ‘init’ in our ‘user defined’ circuit config file. The init circuit must have an .In and .Out label and these MUST be mapped to gadget(s) within our circuit.

We used the in built ‘Pipe’ gadget to supply the connections.

We also demonstrated that the circuit was alive even though we had no input to drive it. We also demonstrated that the inbuilt web server was alive and that if we visited its URL it would generate its own messages, and because our circuit did nothing with the messages it produced, the messages were discarded.

We will expand upon this circuit in the next post.

Until then, if you want to get the original setup file installed again, stop housemon (with a ctrl+c) and issue the following cirget command:

$ ./cirget circuit 0

Now restart housemon:

$ ./housemon

See you soon.

Tagged with: ,
Posted in cirget, housemon, housemon tutorials, soft-circuits

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: