the Reflex, what a game...

Getting started with a BrainStem using Reflexes

Introduction

This guide describes the basic steps to compile, load and run a Reflex program along with providing a basic example for flashing the User LED.

Required Items

This guide was designed using the following items:

  • BrainStem Module
  • BrainStem Development Board
  • Link transport cable
  • aConsole
  • Acroname Reflex Compiler (arc)

BrainStem Module and optionally a BrainStem Development board can be purchased from the Acroname Store.  aConsole and the Acroname Reflex Compiler can be found in the BrainStem Support Package which is available from the Acroname Download page. Extract the package to the location of your choice once the download is acquired.

About Reflexes

Reflexes are simply reactions to other actions.  The Reflex language is an event driven programming language built around this concept.  A reflex is written to fire when an event occurs providing tight-loop, rapid response without host interaction or other processing.  The host can initiate reflexes and change the state of reflex loops but typically isn't involved with the reflex actions.

The following are some applications that are well suited for reflex loops:

  • Responding to a button press
  • Turning off motors when the host link goes down
  • Initializing hardware after a reset

Compiling a Reflex

Reflexes are compiled using the Acroname Reflex Compiler also known as Arc.  Arc is included in the aBinary folder of the BrainStem Support Package.  Compiling a Reflex (typically with a .reflex extension) creates a .map file which gets interpreted by the Reflex Virtual Machine.

Example Code

The following Reflex shows how to toggle the User LED.  A copy of this example code can be found in flashmyled.reflex located in the aUser directory of the BrainStem Support Package.  Please visit the Flashing My User LED using Reflex page for a detailed explanation of the code. When creating your own reflex make sure you save it in the aUser directory.

/* file: flashmyled.reflex */

#include <a40PinModule.reflex>

a40PinModule stem;

// 1 second delay
#define DELAY 1000000

reflex mapEnable()
{
  char i = 0;

  for (i = 0; i < 10; i++) {
    stem.system.setLED(true);
    stem.system.setSleep(DELAY);

    stem.system.setLED(false);
    stem.system.setSleep(DELAY);
  } // end of for loop

} // end of mapEnable

To compile the reflex execute the following code using a terminal while inside the aBinary folder of the BrainStem Support Package:

$ ./arc flashmyled.reflex

A successful reflex compilation should give the following output:

Acroname Reflex Compiler (arc)
version X.X, build 000000
Copyright 1994-2XXX, Acroname Inc.

compiled to 74 bytes in flashmyled.map

Determining Link Settings

aStemTool provides an easy interface for discovering the parameters that are necessary for creating a link to a BrainStem using any Acroname command line tool.  Open aStemTool and choose the appropriate link type.  The link settings will be shown at the top of the window once a BrainStem has been found.

link settings for a brainstem module

BrainStem Link Settings

The link settings shown above describe the necessary components for connecting to a TCP/IP based BrainStem.  The following code snippets show how to take the link settings from aStemTool and use them as command line arguments for aConsole.

If the BrainStem linktype is TCP/IP then the following arguments must be specified:

$ ./aConsole -linktype ip -ip_address XXX.XXX.XXX.XXX -ip_port XXXX

If the BrainStem linktype is USB then the following arguments must be specified:

$ ./aConsole -linktype usb -usb_id 0xXXXXXXXX

Load a Reflex File

Once a Map file is created it must be loaded into a file slot on a BrainStem module.  aConsole must be used to load and enable a Map.  aConsole comes with a 'load' command which takes a map file and loads it into a specified slot.  Load syntax is as follows:

load <map file> <module> <store> <slot>

Where module is the module address of the BrainStem where the code will be stored and executed; store is the index of the store on the target module; slot is a slot index within the store. These stores can be thought of as a file system. On 40-pin modules, store index 0 is the internal persistent flash memory. See the reference for information regarding stores. The following code demonstrates how to load the example reflex into a slot on a BrainStem module using aConsole:

brainstem> load flashmyled.map 6 0 0
loaded 78 bytes into store 0, slot 0 on module 6
0 brainstem>

Map a Reflex

A Reflex is enabled by mapping the slot that the .map file has been loaded into.  A reflex stored in a slot may be executed or "enabled" using the slot command.

The following command maps a Reflex on BrainStem module 6 loaded into store 0, slot 0:

brainstem> enable 6 0 0
elabled store 0, slot 0 on module 6
0 brainstem>