A Basic “Hello World” Example.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
#include <a40PinModule.reflex>
#define ON 1
#define OFF 0

a40PinModule stem;

reflex mapEnable()
{
    stem.system.setLED(ON);
}

reflex mapDisable()
{
    stem.system.setLED(OFF);
}

Wait Where’s the “Hello World?”

We don’t actually print “hello world” in this example. Since we’re working with a BrainStem, the equivalent action is to turn on and off the User LED This is exactly what the reflex above accomplishes. Next we will break this example down line by line to illuminate some of the interesting bits. Finally we will look at a slightly more complex example which outlines one of the ways the BrainStem architecture is different (and better) than other embedded languages you may be familiar with.

Includes

Line one includes the BrainStem module definition file we will be using in the example. There is generally one of these for each type of BrainStem module you may encounter. See addendum III to have a look at one of these files. The BrainStem module definition file tells the reflex compiler what the BrainStem is capable of doing.

Defines

We follow a C-like convention for the majority of our language constructs, and the #define preprocessor directive is one of the preprocessor directives we support. Lines 2 and 3 define some human readable names for the UserLED states.

The Module declaration

a40PinModule stem;

The module declaration creates a named “instance” of a BrainStem. Instance is in quotes because there is no real concept of an object in the reflex language, but in essence the declaration provides us with a way to refer to a particular BrainStem. Each module in a BrainStem network has a unique module address, by default a40PinModule stem; without an argument refers to the module on which the reflex file is loaded, while a module declaration with a module address, like a40PinModule stem2(8); refers to the module with address 8 and is not necessarily the module on which the reflex is loaded.

Keywords and builtins

We try to minimize the number of keywords, and builtin bits that you as a user have to learn, but there are a couple of keywords in the reflex language that are used all the time. reflex defines a top level routine that is attached to an event or entity in the BrainStem system. There are 4 built in reflexes that can be defined by the user to perform behaviors on certain system events. The first two are represented in this example mapEnable and mapDisable are startup and teardown reflexes that are called whenever a reflex file is enabled and disabled. The second set of built in routines is linkUp and linkDown, and are called when a connection to a host is established or disconnected.

A reflex declaration looks like the following snippet. It starts with the keyword reflex, then declares the entity for which the reflex is executed, is enclosed with { and }. We will see an example of an entity reflex declaration in the second code example.

reflex 'entity'()
{
    ...
}

There is no main routine in the reflex world. When you enable a map, you are essentially attaching behaviors to certain entities or events which occur in the system. Enable does not necessarily execute code, code execution is a side effect of defining a behavior to the mapEnable reflex. In the case of the example, this is what we want.

There is no main only Zule!

It is worth reiterating this point because it is one of the main issues new users encounter with the Reflex system. Most programming languages have a single entry point, typically called “main”. There is no such concept when writing reflexes. Reflexes are meant to respond to changing conditions within the BrainStem system. As such, relying on mapEnable as a main-like routine is a discouraged practice, and can have negative consequences for the speed and performance of your reflex. So, no main … got it. Moving on.

The Rest

The rest of the example is relatively straight forward. The mapEnable routine as defined on lines 7-10 turns on the user LED when the mapfile is enabled, and the mapDisable routine on lines 12-15 turns the LED off when the mapfile is disabled. The final interesting bit is the command sent to the BrainStem to enable or disable the user LED.

stem.system.setLED(ON);

This command is fairly typical of many BrainStem commands. It consists of three parts, the module where we will send the command, in this case the current module, the BrainStem entity system to which the setLED command belongs, and the argument ON which sets the state of the user LED.

Next we’ll take a look at a more complex example, where we blink the LED multiple times, which highlights one of the main strengths of the BrainStem Virtual Machine: a BrainStem is a multiprocess machine, designed to do more that one thing at a time.

Note

A note about includes. We follow the convention that an include file in <> brackets comes from the aInclude directory, and is usually an acroname supplied file, like the Module definitions. An include that is surrounded by quotes "" is searched by path from the aUser directory. So, "mylib/myReflex.reflex" would look in the mylib folder within the aUser directory.