Working with Reflex files

Writing reflexes requires a few tools. You’ll need access to your favorite text editor, and the programs provided in the BrainStem support download. These tools include:

  • arc - The reflex language compiler

  • Python - The BrainStem python library can now load and unload reflex files.

The BrainStem support download can be obtained from the download page on the acroname website.

A Note about Directories

Acroname prefers to distribute a set of directories you can place anywhere on your system rather than rely on platform specific installation routines, and default program locations.

The BrainStem Support download includes the following directories:

  • acroname - Top level folder

    • bin - Executable apps and libraries

    • development - Examples and API libraries (Python and C++)

    • aInclude - Header files for reflexes

Arc, the Acroname Reflex Compiler

Arc can be run from the command line. It will compile reflex source files from within the bin folder or from a relative file path (absolute paths will not work). The reflex files will be compiled into map files and placed into the local directory. Map files, which are binary byte code files are executed by the Reflex Virtual Machine on BrainStem modules.

$>./arc -h

This will print information about using the arc compiler. Arc has a couple of useful flags useful for working with reflex file output, but first let us look at the basic command line for compiling reflex files.

$>./arc ../development/reflex_examples/Blink_LED.reflex

This will read in the Blink_LED.reflex source file located in the development/reflex_examples folder, and produce the compiled result at bin/Blink_LED.map.

$>./arc -p ../development/reflex_examples/Blink_LED.reflex

This will read in the Blink_LED.reflex source file in the development/reflex_examples directory, and output the resulting tokenized output of the lexer portion of the compilation process.

$>./arc -a ../development/reflex_examples/Blink_LED.reflex

This will read in the Blink_LED.reflex source file located in the development/reflex_examples folder, and will output the AST for the reflex.

$>./arc -d Blink_LED.map

This will read in the compiled Blink_LED.map binary located in the bin folder, and will generate a .dsm human readable disassembly file in the bin directory. See Appendix II: Reflex map file Disassembly for more information about understanding the format of the disassembly.

Loading reflex .map files with ReflexLoader

ReflexLoader is our new Command Line Interface (CLI) tool for loading .map files into any BrainStem device. It can be found in the BrainStem development kit under the bin folder.

$>./ReflexLoader -H

This will print the usage information for ReflexLoader. If you are having trouble getting something to work this is one of the best places to look for more information. One thing that is important to make note of is that specifying a device ‘-d’ is required. Additionally, that means that you must also have a device (SN), store and slot specified. Failure to do so will cause the program to return an error. With that said a command is also required if you were wanting the program to actually do something; however, failure to include one will not cause an error.

$>./ReflexLoader -L -i /location/of/file.map -d 0x40F5849A INTERNAL 0

This command will load ‘-L’ the input file ‘-i’ /location/of/file.map to the device ‘-d’ into the INTERNAL store at slot 0.

Unloading a slot is just as easy but instead of using the ‘-L’ and ‘-i’ you would use ‘-U’ and ‘-o’ to specify where you would like the file to go. ReflexLoader will not create any file paths that do not exist so you must give a valid path.

$>./ReflexLoader -E -d 0x40F5849A RAM 0

This command will enable ‘-E’ the reflex that is loaded into the RAM store at slot 0 in the specified device 0x40F5849A. Keep in mind that although you can load a reflex into RAM it will not survive a power cycle as it is volatile memory.

To disable this slot just swap the ‘-E’ for ‘-D’

$>./ReflexLoader -B -d 0x40F5849A INTERNAL 0

This last command will make a slot bootable. Once this has been set and a power cycle occurs the BrainStem device will automatically enable the reflex at the designated slot. In order to disable a boot slot you will need to replace the slot parameter ‘0’ in this case with 255.

Loading reflex .map files with Python

The BrainStem python library can be used to load compiled map files onto BrainStem modules. To load .map files with python you will need to follow the installation instructions of the getting started guide in the Python section of this reference.

To load a reflex map file into a slot on your brainstem module. First compile the reflex with arc. The resulting map file can be found in your aObject directory. Then start the python interpreter, and import the brainstem package. Instantiate your module and connect. Once you’re connected, the following code block will show you how to load, enable and disable the .map file.

>>> fh = open('path/to/map/mymap.map', 'rb')
>>> mapfile = fh.read()
>>> fh.close()
>>> stem.store[0].loadSlot(0, mapfile, len(mapfile)) #loads map into store 0 slot 0
0
>>> stem.store[0].slotEnable(0)
0
>>> stem.store[0].slotDisable(0)

The above code simply opens the map file for reading in binary mode, reads the contents of the file into the mapfile variable, loads that data into store 0 slot 0 and enables and disables the slot.

Boot Reflexes

You can also set your stem to enable the map file on boot. To do this you will need to load the map file into a slot on the internal store of your module (the internal store is index 0). Then set the boot slot on the module by accessing the setBootSlot procedure of the system module

>>> stem.system.setBootSlot(0)
0
>>> stem.system.setBootSlot(255) # will disable the slot from being enabled on boot.

If you do not have python installed on your system, you can also use the aConsole utility to load .map files.