Microbric Edison/Hybrid Token Design

Date: 2014-10-06
Version: 3.9
Author: Brian Danilko, Likeable Software
Copyright: 2006,2014 Microbric Pty Ltd
License:GNU GPL version 2

Contents

Document History

Ver. Date released Notes
3.9 2014-10-06

Edison download formats:

Documented download format for tokens and firmware

Documented audio download technique
3.8 2014-05-18

More changes for the new Edison robot:

Motor has a new event: distance covered

IR rx obstacle events have been re-worked

Update to the Event Handling documentation
3.7 2014-04-26

Changes for the new Edison robot:

Changes to version number for download of Edison code

Documented implicit configuration for Edison

Changes to motor, beeper, LED, IR modules for Edison

Made all of the status registers read AND write so that manually cleared statuses can be cleared.
3.6 2006-10-05

Changed the NOP to 'stop' to help reduce the size of the interpreter.

Added a new field 'Button' to the end of devices. It holds the current button press.

Added timer action bits for the backlight and backlight timer. Removed a disused timer disable action bit.

Updated flashing rectangle communications parameters.
3.5 2006-09-28 Added an action field to digital outputs for generating a pulse.
3.4 2006-09-27

Updated the Beeper entry with Tune and Tone information.

Updated the copy to LCD to use seperate row and col values.

Time base is now 10mS. Updated all references to times.

Put an allowable range for motor speeds (0-10).

Removed done todo items.
3.3 2006-09-26

Updates from conversation with Bill. Changed flashing rectangle comms, seperated row/col pointers on the LCD, added light level to the line-tracker, updated size of analog inputs, analog input constraints.

All units defined except for tune/tones in Beeper.
3.2 2006-09-23 Added the new module types - LED, Bumper and defined the Basic Configuration of the Hybrid.
3.1 2006-09-23 Changed the move to allow for move of both 8bit and 16bit mod/regs. The move source now uses the LS bit for size info in most cases. Also move of small constants also encodes the size.
3.0 2006-09-08 Added a statement about the USB comms.
2.2 2006-08-22 In implementing the new downloading saw and corrected some mistakes: storage offsets in the module table are now 8bits, table length is variable and uses a marker to signal the end, made a larger ENTER DOWNLOAD MODE string.
2.1 2006-08-21

Modified the downloading to make it more straightforward for Bill. Last section is now Downloading and Communication Settings.

Upped the USB baud rate to 38400 and ACK/NACKs are now every 256 bytes.

Removed most of the special tokens since the download protocol takes care of what those tokens did. Instead added set and clear bit (just for mod/regs) into specials and removed setbit from the bottom of the math tokens.

Moved NOP to a more satisfying all 1s token (see end of branch table).

Recorded how the mod/reg split could be moved to MMMMM/RRR instead of 4/4 for better future proofing. I expect that in a future version.
2.0 2006-08-17

LCD pixel addressing is moved to row and column for simplicity. Updates in the 00110000 token and in the Devices module.

Updated the Index module for action bit use. This was the last module to be moved to the action bit method.

Added information on the module locations and how to specify the location for a motor module.

Added information on how to deal with the module status bits. Updated the event source information.

Added a status bit for digital in to make it a better event source (capture finished, level changed). Added a status bit to the line tracker (changed) for the same reason. Added status bits to the beeper for the same reason.
1.4 2006-08-16

Changes to the fixed modules to use the action bit method and clean-up associated with it. Added a sleep enable/disable to the timers, cleaned up the LCD stuff.

Changes to the motor modules (for A and B) and renumbered them.
1.3 2006-08-15

Changes to connectable modules: IR split into two, 'action bit' registers to make the interpreter easier, Line Tracker split from Analog In, Motor simplified, Beeper volume removed, Digitals revamped.

Added a bit-set token (just for mod/regs) at the end of the math tokens.

Tightened up when serial comms pauses happen to reflect that not storing the configuration token with the other tokens.
1.2 2006-08-07

Added a short version of push/pop the accumulator and communication settings. Removed special comms token, instead communication settings say when to ack/nack.

Major changes to the mod/reg tables to reflect move some things to the connectable modules (i.e. beeper module can have the tone and tune functions, etc.) and to refactor others.

Removed the pdf version since it has major problems with long lines.
1.1 2006-07-25

Corrections of pixel data download and missing '1' in math. Added more things to sacrifice for space.

Defined the firmware download format and revamped the special tokens so that we can more easily pause at sector boundaries for erasing.
1.0 2006-06-15

Corrections after meeting with Bill (tone freq, version mismatch error, lcd pixel addressing, nop). Also added implementation notes of what to cut if we run out of time or space.

Bumped to version 1.0 because I will start implementing to this version.
0.75 2006-06-15 Added LCD writes of numbers, mod/reg push/pops, separated tones and tunes
0.7 2006-06-14 Added Memory map, modules/registers, error strategy, decrement and branch token. Draft of connectable module registers.
0.6 2006-06-09 Removed incrementing moves
0.5 2006-05-26 Initial version but enough to assess the work it would require of Bill so that we can remove stuff if needed.

Todo

  1. In a future version of the firmware (and this spec) could shift the mod/reg from 4 bits each to 5 for mod and 3 for reg. Currently only three module types use more then 8 bytes so they could be refactored and then we could handle motherboards with 24 connection points.

Introduction

This document is for the design of tokens which are sent down to the Hybrid interpreter from the PC based GUI. The tokens are of variable length but are always a multiple of 8 bits.The tokens are quite low level which implies that the GUI would turn most Microbric instructions (a single GUI block) into multiple tokens. Though, for simple blocks and programs, the tokens have been designed so that very few would be needed.

There are 4 token types: Special tokens, Move data tokens, Math tokens and Branch tokens. These tokens, with module register definitions will be able to accomplish everything that the Hybrid is supposed to do.

A module is any of the 12 locations where it can be fastened plus it's type (digital, etc.), or it is an internal device (tone/timers, LCD, math accumulator, etc.). Each of the types will have a set of registers defined for them. These modules/registers together with the move_data tokens allows for real programs to be written (since data can come from variables instead of just constants)!

Finally, it gives an easy model that can be changed or added to late in development if we need to, since the token structure doesn't change, only the meaning of the modules/registers need to.

Implementation Notes

Some elements of this specification could be implemented in a later version if we have a time crunch or will be in a full downloadable firmware that doesn't include other builtin programs. They are:

Special Tokens

Special tokens deal with setting and clearing bits in mod/regs, and sending bulk data down to the hybrid.

Special Tokens
00  
  Bit clear/set in the mod/regs. (Used for triggering actions and clearing status)
  00 0bbb mod/reg(8) Clear bit bbb in mod/reg.
  00 1bbb mod/reg(8) Set bit bbb in mod/reg.
  Copy data into 8 bit, 16 bit or LCD spaces (at most 15 data elements at a time)
  01 nnnn dest(8) Copy nnnn bytes of 8 bit data starting at dest in 8 bit space. nnnn bytes of data follows.
  10 nnnn dest(8) Copy nnnn words of 16 bit data starting at dest in 16 bit space. nnnn*2 words of data follows.
  11 nnnn row(8) column(8) Copy nnnn bytes of 8 bit ascii data starting at row, column in LCD space using font bitmaps. nnnn bytes of data follows.
  11 0000 pixel_bytes(8) pixel start - row(8), col(8) Raw copy pixel_bytes of pixel data to LCD starting at pixel_start (this is pixel not font based), pixel_bytes of data follows so there will always be a multiple of 8 pixels affected.

Module Types

Type Module Notes
0000 Not Used  
0001 Digital In Used for generic 1-bit digital outputs.
0010 Digital Out Used for generic 1-bit digital inputs.
0011 Analog In Used for light sensor, temp sensor, etc.
0100 Line Tracker Used for tracking lines. MUST BE IN LOCATION 0 IF USED.
0101 IR Transmit Used for transmitting characters via IR, or transmitting IR for obstacle detection.
0110 IR Receive Used for receiving characters and remote control bursts via IR, and for obstacle detection.
0111 Beeper Used for beeping, tones and tunes.
1000 Motor A

Variable speed motor control - type A.

Uses two consecutive locations, use the lowest one of the two in the module table (see Download format).
1001 Motor B

Variable speed motor control - type B.

Uses two consecutive locations, use the lowest one of the two in the module table (see Download format).
1010 Bumper Used for reading the status of a Bumper (a special digital input).
1011 LED Used for controlling switching a LED on/orr, and to monitor light levels

Module Locations

There are twelve locations where modules can be connected to the motherboard. With the motherboard oriented so that the writing is visible and the right way up, we have:

  • location 0 is in the top middle
  • location 1 is to the right of 0
  • the rest of the locations continue around the motherboard in a clockwise fashion
  • location 11 is to the left of 0

Special Token Notes

  1. The copy data tokens move at most 15 pieces of data at a time. For the amount of data that we are looking at in the Hybrid, this isn't much of a restriction.
  2. A copy data token with all zeros for nnnn means to zero the total space (8, 16 or LCD)
  3. For the last copy (pixel based) I suggest that we define pixel_start (0,0) to be the upper left corner, and increment by one across the rows, wrapping over to the next line at the right edge.

Move Data Tokens

These take care of most module control and queries since the source or destination of these moves can be registers mapped to the different locations and types of modules.

Move data tokens.
01 The e flag (in CPU module) is affected on every move. It is set if the source value is 0, else it is cleared.
  0nns dd Move a small constant (nn so 0-3) to destination type dd. s is 0 for 8 bit moves, 1 for 16 bit moves.
  1sss dd Move from source type sss to destination type dd. Details follow, split into sources then destinations.
      Source details:
  1000 dd mod(4) reg(4) Source is the module mod, register reg. See Module Locations and Module Registers for definitions of these values. The source has an 8 bit value.
  1001 dd mod(4) reg(4) Source is the module mod, register reg which has a 16 bit value.
  1010 dd const(8) Source is the 8 bit constant following the token.
  1011 dd const(16) Source is the 16 bit constant following the token.
  1100 dd 8bit_var(8) Source is the contents of the variable in 8 bit space.
  1101 dd 16bit_var(8) Source is the contents of the variable in 16 bit space.
  1110 dd 16bit_var(8) Source is the system time (see Timers (location e)) with the contents of the 16 bit variable added to it. The destination must be a variable in 8 bit space else it is a Size Mismatch error.
  1111 dd const(16) Source is the system time (see Timers (location e)) with the constant added to it. The destination must be a variable in 8 bit space else it is a Size Mismatch error.
      Destination details (the 8 bits of data here, follow any needed by the source bits):
  1sss 00 mod(4) reg(4) Destination is the module mod, register reg.
  1sss 01 8bit_var(8) Destination is this variable in 8 bit space.
  1sss 10 16bit_var(8) Destination is this variable in 16 bit space.
  1sss 11 8bit_var(8) Destination is this variable in the LCD space.

Move Data Notes

  1. Small constants are encoded in the token so that writing 0 or 1 to a module only takes a token of 2 bytes - the same as now.

  2. The smallest token is 2 bytes, the largest is 4.

  3. Moves can also be done through the INDEX module which uses an incrementing cursor for the reads or writes for LCD, 8bit and 16bit spaces.

  4. The System time add_and_moves seem complicated but aren't. And they allow for easy timed operations so that a Microbric instruction of motor forward for 10 seconds becomes 4 tokens: 1) motor on, 2) move time data +10 seconds, 3) compare times (see below), 4) loop back 1 if less then.

    The point of all of this is so that no (or very few) tokens take long to execute. Then it is an easy for the interpreter to execute a token, then check for events, then repeat. Polling can work for most things then.

Math Tokens

Math Tokens
10 The e flag (in CPU module) is affected by all operations. When the operation is not compare then it is set when the result is zero, cleared otherwise. On compare e is set if the values are the same, cleared otherwise. On compare g&l are affected as well.
  00 Unary Operators
    s Size. 0 means 8 bit, 1 means 16 bit.
    s 0 Value to modify is in the accumulator, result goes into the accumulator
    s 0 00 NOT the accumulator (size determined by s).
    s 0 01 INCrement the accumulator (size determined by s).
    s 0 10 DECrement the accumulator (size determined by s).
    s 0 11 CONVERT the value in the accumulator to the other data type (if accumulator has 8bit value then convert to 16 bit value, else: if s=0, use the lsb for the 8bit value, if s=1, use the msb).
    s 1 Value to modify is in a variable - result goes back to the variable (and accumulator).
    s 1 00 var(8) NOT the variable var (size determined by s) .
    s 1 01 var(8) INCrement the variable var (size determined by s).
    s 1 10 var(8) DECrement the variable var (size determined by s).
    s 1 11 var(8) Compare the system time (see Timers (location e)) and the bytes starting at this variable in 8bit space. Set the flags for equal, greater or less. Size in this token is ignored and the accumulator and variable are unchanged.
  01 Basic Arithmetic (left hand side - lhs, is in the acc. and the result goes back into the acc.)
    s Size. 0 means 8 bit, 1 means 16 bit.
    s 0 Variable (right hand side - rhs, is in the variable (space determined by s))
    s 0 00 var(8) ADD the acc and value in var.
    s 0 01 var(8) SUBTRACT the value in var from the acc.
    s 0 10 var(8) MULTIPLY the acc and value in var.
    s 0 11 var(8) COMPARE the acc and the value in var. Flags are set for equal, rhs>lhs, rhs<lhs.
    s 1 Constant (value following token is a constant--rhs, if s=0, 8bit value follows, else a 16bit value follows.)
    s 1 00 const (8/16) ADD the acc and constant.
    s 1 01 const (8/16) SUBTRACT the constant from the acc.
    s 1 10 const (8/16) MULTIPLY the acc and the constant.
    s 1 11 const (8/16) COMPARE the acc and the constant. Flags are set for equal, rhs>lhs, rhs<lhs.
  10 Shifts and Divides. LHS is the acc and the result goes back into the acc. 16bit values are handled in a signed way (so easy mult/div by powers of 2) which means that the leftmost bit is replicated on a right shift.
    s Size of data in acc. 0 means 8 bit, 1 means 16 bit.
    s 0 Variable (rhs value is in the variable number in 8bit space)
    s 0 00 var(8) SHIFT LEFT the acc by the value in var.
    s 0 01 var(8) SHIFT RIGHT the acc by the value in var.
    s 0 10 var(8) DIVIDE the acc by the value in var and put the integer part of the result into the acc.
    s 0 11 var(8) MODULUS the acc by the value in var and put the result in acc (returns the remainder of a division).
    s 1 Constant (rhs value is the 8bit constant following the token)
    s 1 00 const (8) SHIFT LEFT the acc by the constant.
    s 1 01 const (8) SHIFT RIGHT the acc by the constant.
    s 1 10 const (8) DIVIDE the acc by the constant and put the integer part of the result into the acc.
    s 1 11 const (8) MODULUS the acc by the constant and put the result in acc.
  11 BITWISE Arithmetic. LHS in in the acc and the result goes back into the acc.
    0 Size. These operations are only defined on 8bit values.
    0 0 Variable (rhs value is in the variable number in 8bit space)
    0 0 00 var(8) OR the acc by the value in var.
    0 0 01 var(8) AND the acc by the value in var.
    0 0 10 var(8) XOR the acc by the value in var.
    0 1 Constant (rhs value is the 8bit constant following the token)
    0 1 00 const (8) OR the acc by the constant.
    0 1 01 const (8) AND the acc by the constant.
    0 1 10 const (8) XOR the acc by the constant.
  11 Specials - enable or disable event processing between tokens and set a bit in a mod/reg.
  11 0 0 11 Disable event processing
  11 0 1 11 Enable event processing (default on start)

Math Token Notes

  1. I have only defined division by positive 8bit values. I think that this will simplify Bill's life and should be adequate.
  2. Handling multiplication and division will be non-trivial in the interpreter.
  3. Catching overflow is a pretty hard problem too!

Branching Tokens

Branching Tokens
11  
  0 Branch
    f Far: 0 means short (8bit signed offset), 1 means long (16bit signed offset).
      p Push return frame: 0 means no, 1 means yes. The frame layout is documented in module CPU - it is the first 3 words of that module.
        000 offset(8/16) branch to the new location (pc + offset bytes).
        001 offset(8/16) branch to the new location if the last compare was ==
        010 offset(8/16) branch to the new location if the last compare was !=
        011 offset(8/16) branch to the new location if the last compare was >
        100 offset(8/16) branch to the new location if the last compare was >=
        101 offset(8/16) branch to the new location if the last compare was <
        110 offset(8/16) branch to the new location if the last compare was <=
        111 offset(8/16) Decrement the CPU register counter and branch to the new location if non-zero
  1 Push/Pop
    s Size. 0 means 8bit, 1 means 16bit.
      0000 const(8/16) Push the constant value (8 or 16bits) on the stack.
      0001 var(8) Push the contents of the variable (from 8bit or 16bit space depending on s) on the stack.
      0010 mod(4)reg(4) Push the contents of the module register on to the stack.
      0011   Push the accumulator (this is a short version of the token 111s0010 above).
      0100   Pop the accumulator (this is a short version of the token 111s0010 above).
      0101 var(8) Pop the top of the stack into the variable (into 8bit or 16bit space depending on s).
      0110 mod(4)reg(4) Pop the top of the stack into the module register.
      1000 Return from a subroutine by popping the return frame off of the stack.
  Special very laid back token
11 1 1 1111 Stop - tells the interpreter where the end of code is

Branching Tokens Notes

  1. I suggest that the stack be limited to say 64 words and that recursion isn't supported. Pushing onto a full stack is bad which should stop the program and put something on the LCD or allow the GUI to get the info on the next download.
  2. I would make the stack 2 bytes wide (a word) and pushing 8-bit values has zeros in the top half.
  3. It is the responsibility of the token writer to use the stack correctly.
  4. A branch only (short) only takes 2 bytes. A very complicated test may require 3 bytes to load the accumulator, 3 bytes for the comparison and 2 or 3 bytes for the branch, though usually the value will already be in the accumulator after math operations.

Error Strategy

On an error (as listed below) we can either bumble forward or stop the program and (hopefully) tell the programmer what went wrong. In this project we are taking the first choice for errors, and either the first or second choice on warnings, selectable by the programmer.

On an error, the LED will flash and an error message will be displayed on the LCD. The message will contain a token number which the gui will be able to interpret to say which Microbric had the problem.

Type Name Description
Error Stack Overflow Did a push or branch without sufficent room on the stack
Error Divide by zero Doing division or modulus with a zero denominator
Error Size Mismatch Attempting to move 8bit to 16 or vica versa
Error Out of Range Accessing a space or register outside of valid range
Error Version Mismatch When the downloaded program isn't a version that the firmware can handle.
Warning Read Only Tried to write to a readonly location
Warning Overflow A calculation which overflowed the destination

I would suggest that on a write to the LCD with a value out-of-range of the defined glyphs, that we use a special glyph to show that instead of raising and out-of-range error.

Memory Map

The memory in the interpreter is not contiguous, but is a number of seperate spaces. Which space is accessed is defined by bits in each token.

Name Size (in bytes) Description
8-bit 256 8 bit unsigned values.
16-bit up to 128*2 (256) 16 bit signed values (may restrict size to less then this number)
LCD 16*4 (64 in device) Virtual space - writing an 8 bit value here selects a bitmap to be written on the LCD
stack up to 64*2 (128) All elements on the stack are 16 bits wide.
IR table up to 24*6(?) (144) Contains the IR signatures used to trigger actions (assuming 8 bits for size and action (say 2 bits and 6 bits), 32 bits for IR data, and 8 bits for type)

Event Handling

Each token should be handled in it's entirety before jumping to an event handler. The interpreter my handle its own interrupts in the middle of a token but it will have to store the results until finished processing the current token.

Note that most of these tokens are finished very quickly with the exception of causing an IR transmission.

Between tokens:

Event sources:

Module Registers

Locations 0-b

See the Connectable Module Registers section following.

INDEX (location c)

This module provides for indexed access to memory spaces with incrementing after the read or write.

 
  1. action bits (w-8)
 Format: ?rwclgpm. R is read 8bit1, W is write 8bit1, C is copy from 8bit1 to 8bit2, L is copy from 8bit1 to LCD Ascii and trigger LCD output, G is read 16bit, P is write 16bit, M is a copy from 16bit1 to 16bit2. Note that all of these operations update the relevant cursors using the step registers.
  1. 8bit1 cursor (r/w-8). Cursor into 8bit space
  2. 8bit1 step (r/w-8). Amount to add to 8bit1 cursor after use triggered by R, W, C or L in action bits. Defaults to 1
  3. 8bit1 window (r/w-8) Window to write to before triggering W, C or L in action bits, or read from after R.
  4. 8bit2 cursor (r/w-8) Cursor in 8bit space only used as copy destination
  5. 8bit2 step (r/w-8). Amount to add to 8bit2 cursor after use triggered by C in action bits. Defaults to 1
  6. 16bit1 cursor (r/w-8) Cursor into 16bit space
  7. 16bit1 step (r/w-8) Amount to add to 16bit1 cursor after use triggered by G, P or M in action bits.
  8. 16bit window (r/w-16) Window to write to before triggering P or M in action bits, or read from after G.
  a. 16bit2 cursor (r/w-8) Cursor in 16bit space only used as copy destination
  b. 16bit2 step (r/w-8). Amount to add to 16bit2 cursor after use triggered by M in action bits. Defaults to 1.

Devices (location d)

 
  1. Status bits (r/w-8)
 Format:???r1234, R-byte received. 1, 2, 3, 4 represent the motherboard buttons being held down (after debounce).
 
  1. Action bits (w-8)
 Format:?xtraehs. X means update serial settings, T transmit a byte, R need new random byte, A write ascii to LCD, E write 8-bit to LCD, H write 8-bit to LCD in hex, S write 16-bit to LCD. After an LCD write the row/col pointers are adjusted.
  2. LCD cmd action bits (w-8) Format: ???rnspc. R to reset LCD (clear LCD, wp=0), N next line, S output a space, P-pixel set, C-pixel clear. All operations affect the row/col pointers.
  3. serial settings 1 (r/w-8) Baud and such -- *Not used*
  4. serial settings 2 (r/w-8) *Not used*
  5. serial rcv char (r-8) Last serial byte received
  6. serial transmit char (w-8) Byte to transmit
  7. LCD ascii or 8-bit number to write to LCD (r/w-8) An 8-bit number or ascii value to write to the LCD (depending on A, E or H action bits).
  8. LCD row pointer/ pixel row pointer (r/w-8) The row on the LCD (with 0 being the top) to next write to, or the pixel row number (for P or C in LCD action bits). Note that most LCD commands or actions update this register.
  9. LCD col pointer/ pixel column pointer pointer (r/w-8) The column on the LCD (with 0 being left) to next write to, or the pixel column number (for P or C in the LCD cmd action bits). Note that most LCD commands or actions update this register.
  a. LCD long number (r/w-16) A 16-bit number to write to the LCD when the S action bit is set.
 
  1. Random (r/w-8)
 Reading this returns a pseudo-random 8bit quantity. It returns the same value until R is set in the action bits.
 
  1. Button (r-8)
 Reading this the gives the current button that is being held down (after debounce).

Timers (location e)

 
  1. Status bits (r/w-8)
 Format: ??????re. R one shot timer running, E - one shot timer expired.
 
  1. Action bits (w-8)
 Format: ???btepo. B enables backlight, T enables backlight timer, E enables sleep timer, P triggers pause timer, O triggers one-shot timer.
  2. Pause timer (r/w-16) Wait until this time expires before executing next token (though event handling still happens). 10mS units (max 327.67 secs)
  4. One shot timer (r/w-16) Set a timer which when expired, sets the E flag in status bits. Doesn't pause token execution. 10mS units (max 327.67 secs)
  6. System Time (r/w-32) Four byte (32 bit) unsigned time that the system has been powered up in 100ths of a second (so range is > 5900 hours)

CPU (location f)

Virtualisation of the CPU. Note that a stack frame is the first 6 bytes of this structure (ACC, Flags, Counter & PC).

 
  1. ACC (r/w-16)
 Can hold either 8bit or 16bit values (token bits say which one, flag s records it).
 
  1. Flags (r-8)
 Flags are: seglh??c. S reflects the size the data in ACC (0-8, 1-16), E for the last compare being equal or the last operation =0, G&L for the last compare being greater (or less respectively). H means in handler, C is a carry flag used in adds and subtracts
 
  1. Counter (r/w-8)
 Used to control tight loops
 
  1. PC (r/w-16)
 Unsigned - for the interpreter to keep track of the token being executed
  6. Stack Pointer (r/w-8) Points to the current top of stack
  7. Cont on Warning (r/w-8) If 1 then execution continues if there is a warning condition.

Module Register Notes

  1. Serial settings should just be ones that are easy to do on our hardware
  2. A different set of CPU registers (first 6 bytes) are used in event handling which is transparent to the user. This means that we don't have to save a stack frame on event handling since event handlers don't nest. This is a nicety -- we can just use the stack to make everything easier!
  3. The pixel based LCD is clumsy, but the special token (00110000) allows for large sets of pixels to be affected, so this method is just for setting small numbers of pixels.
  4. Bits called '?' are reserved and are read as 0 and should be written as 0.

Connectable Module Registers

I expect that these will change as the project progresses. That is fine though as this approach was adopted to allow that.

Basically through download (see Download format) the interpretor is told which device is connect at which point (0-11). So the modules are numbered 0-11 but the registers are configured as the device that is connected. So for each different type of device we have different types of virtual registers.

Motors A&B

 
  1. Motor Status (r/w-8)
 Format: ??????DS. D is set to one when zero is written into the distance register. S is set to one when the strain on the motor goes over a safe value.
 
  1. Motor Control (r/w-8)
 Format: ccc?ssss. CCC are control bytes (00?-coast, 010-forward continuous using speed in SSSS, 011-forward using distance register, 100-backward continuous using speed in SSSS, 101-backward using distance register, 11?-brake). Speeds in SSSS can range from 0 to 10.
 
  1. Distance (r/w-16)
 When this register is non-zero, and the control register has forward or backword distance set, then the motor will do this many half-motor rotations which equates to the value in the register X 7.5 degrees, or the value X 2.5 mm (.1 inch) As the unit is moving, this register will be updated (counting down).

Digital In

 
  1. Status bits (r/w-8)
 Format: xcfnpl. X means that the input level changed, C means that pulse capturing is happening, F means that pulse capturing is finished, N means that no pulse was found by max time, P means that a pulse was found, and L is the input level.
 
  1. Action bits (r/w-8)
 Format: ???????c. C means to try to capture a pulse.
 
  1. Pulse capture time (r/w-16)
 Write this before starting a capture for the max time to wait. Read after a capture when status P is set for the pulse time. 10mS units (max time is 327.67 sec)

Digital Out

 
  1. Status bits (r/w-8)
 Format: ???????p. P means pulse time expired.
 
  1. Action bits (r/w-8)
 Format: ???????p. P means to output a pulse using pulse time below.
 
  1. Output driver level (r/w-8)
 Write 0 for low output, 1 for high. Reading returns last write.
 
  1. Pulse time (r/w-16)
 Write this before triggering action bit P, reading gives time left. Pulse is opposite of the output driver level. 10mS Units (max time is 327.67 sec)

Analog In

Note: This module can NOT be connected at locations 2, 4, 8 and 10!

 
  1. Input level (r-16)
 Format: ??????nnnnnnnnnn (10bit). N is the input level.

Line Tracker

Note: This module can only be connected at location 0!

 
  1. Status bits (r/w-8)
 Format: ??????cl. C is set if there is a change, L is 1 if the tracker is over a line, 0 otherwise
 
  1. Power on (r/w-8)
 Writing a 0 turns off power to the line tracker, 1 turns it on. Reading gives last value written.
 
  1. lightlevel (r-16)
 Format: ??????nnnnnnnnnn (10bit). N is the input light level detected.

Beeper

 
  1. Status bits (r/w-8)
 Format: ?????cou: C means that a clap was detected, O tone is done, U tune is done. (Write 0 to this register to clear the status)
 
  1. Action bits (w-8)
 Format: ?????bou. B means to do a beep, O to sound a tone, U to sound a tune.
 
  1. Tone Frequency (r/w-16)
 Calculated value for the frequency. See below.
 
  1. Tone Duration (r/w-16)
 10mS units (max is 327.67 seconds).
 
  1. Tune Pointer (r/w-8)
 Start of Bill's Tune notation in 8-bit memory. The notation is documented below.

Tone Frequency

The frequency value, f = 5529600 / desired freq in Hz. The desired freq in Hz can range from 1000 Hz to 5000 Hz.

Tune Notation

A sequence of bytes, terminated by a zero byte. Each byte is in the following format: RTTTNNNN, where R is a rest marker (and NNNN is ignored), TTT is the note time in units of 50mS each, and NNNN is the note to play, following this table:

  1. A (6th octave)
  2. B#
  3. B
  4. C (7th octave)
  5. D#
  6. D
  7. E#
  8. E
  9. F
  10. G#
  11. G
  12. A#
  13. A
  14. B#
  15. B
  16. C (8th octave)

IR Transmit

 
  1. Action bits (w-8)
 Format: ??????dt. D means to do obstacle detection, T means to transmit a character. Note that D and T can not both be set to 1!
 
  1. Transmit Character (w-8)
 Character to transmit in Bill protocol.

IR Receive

 
  1. Status bits (r/w-8)
 Format: ?dlcrvmb. D is 1 if an obstacle was detected (if the IR transmitter is configured to do obstacle detection). If D is set, then the actual obstacle detection is on the left (L), centre (C) or right (R). V means that the last check was valid, M means that an IR transmission matched in the IR table, and B means that a Bill protocol character was received.
 
  1. Action bits (w-8)
 Format: ???????c. C means to check the check index to see if it has valid bits captured.
 
  1. Check index (r/w-8)
 Index of the IR table to check for valid bits using the C action bit.
 
  1. Match index (r-8)
 The last IR transmission matched the bits at this index in the IR table.
 
  1. Received Character (r-8)
 The last received IR character in Bill protocol.

Bumper

 
  1. Status bits (r/w-8)
 Format: x????l. X means that the input level changed, and L is the input level (0 for not pressed, 1 for pressed).

LED

 
  1. Status bits (r/w-8)
 Format: ????????. No status bits used.
 
  1. Output driver level (r/w-8)
 Write 0 for LED off, 1 for LED on. Reading returns the last write.
 
  1. lightlevel (r-16)
 Format: ??????nnnnnnnnnn (10bit). N is the input light level detected.

Connectable Module Register Notes

  1. Bits called '?' are reserved and are read as 0 and should be written as 0.

Basic configuration for the Hybrid

  1. Line Tracker
  2. Bumper
  3. LED
  4. Motor-a
  5. Continuation of Motor-a
  6. IR Rx
  7. Beeper
  8. IR Tx
  9. Motor-b
  10. Continuation of Motor-b
  11. LED
  12. Bumper

Edison Configuration

  1. Line Tracker
  2. LED
  4. Motor-a
  5. Continuation of Motor-a
  6. IR Rx
  7. Beeper
  8. IR Tx
  9. Motor-b
  10. Continuation of Motor-b
  12. LED

Module Status bit details

Module status bits are set by the interpreter and are sometimes cleared by the interpreter and sometimes by the user. This allows the user to either poll them or set up an event handler to be triggered by them.

The following events marked man are manually cleared by the user so are ideal event sources.

To clear a status bit, the bitset math token can be used.

Downloading and Communication Settings

Download triggering - USB cable

Whenever the hybrid is powered on, and not currently downloading, it will monitor the serial channel (USB cable). If it receives the following sequence it will ACK (or NACK if the version is incompatible) the serial channel. If ACKED it will then wait for the Download Data.

After this header, the Download Data will be transmitted with pauses as per the USB cable communications, protocol flow control below.

Download triggering - Flashing Rectangle

If the download is done via the flashing block then the hybrid will have to be put into download mode via the LCD and buttons and then the computer instructed to send:

After this header, the Download Data will be transmitted with no pauses and not looking for any ACKs or NACKs.

Versioning

Note that the version is split into major (M), and minor (m) bits. The idea is that a difference in a Major would be definitly incompatible, while a minor change should be compatible. The firmware should be able to handle different versions of minor changes (say a difference in hardware requiring a different setting in a CPU register) but just NACK a difference in Major.

The first versions are:

Download format

Download Data looks like:

Notes:

Module table entries:

Notes:

Event table entries:

Notes:

Download Specifics for Edison

Edison uses an audio-to-light communications method which is much more reliable then the flashing rectangle, but doesn't need USB transceiver hardware. It does mean that downloads are one-way, but as they are faster and more accurate, that isn't a problem.

The format for the download header for Edison is the same as detailed above, but with the addition of a DOWNLOAD_TYPE_BYTE in front. The format for tokens downloads is then:

  • DOWNLOAD_TYPE_BYTE -- 0xf1 (tokens)
  • VERSION_BYTE -- for Edison this will always have the major version of 0x20
  • data size n (size of all data not including this size and crc) (16bits, LE)
  • crc (of all data not including size and this crc) (16bits, LE)
  • module table offset (MUST be 0 for Edison)
  • event table offset (0 means not used) (8bits)
  • main program offset (16bits)
  • table data (optional, size t)
  • program tokens (n - t - 4 bytes)

The format for firmware downloads is:

  • DOWNLOAD_TYPE_BYTE -- 0xf2 (firmware)
  • VERSION_BYTE -- for Edison this will always have the major version of 0x20
  • data size n (size of all firmware data) (16bits, LE)
  • crc (of all firmware data) (16bits, LE)
  • firmware data (n bytes)

Audio downloading specifics

Binary data to be communicated to Edison is converted to an audio 'wav' file first. The audio file is a 2 channel, 8-bit per channel, file with a frame rate of 44100Hz. Each byte is encoded with a start bit, 8 data bits (LSB first) and then a stop bit.

Each bit uses a sequence where the left and right channels are set to: left=255, right=0 called FAR; left=0, right=255 called NEAR; and left=128, right=128 called MID.

The sequence representing the bits and preambles are:

  • preamble:
    • Repeated 20 times:
    • FAR for 0.5ms
    • NEAR for 0.5ms
  • start bit:
    • FAR for 0.5ms
    • NEAR for 0.5ms
    • MID for 3ms
  • 0 bit:
    • FAR for 0.5ms
    • NEAR for 0.5ms
  • 1 bit:
    • FAR for 0.5ms
    • NEAR for 0.5ms
    • MID for 1ms
  • stop bit:
    • FAR for 0.5ms
    • NEAR for 0.5ms
    • MID for 4ms
  • postscript:
    • Repeated 20 times:
    • FAR for 0.5ms
    • NEAR for 0.5ms

The data is downloaded over the audio hardware in this order:

  • Preamble
  • Header
  • Data
  • Postscript

Special Characters

No characters are escaped (no framing controls) but the following are used for protocol flow control and downloading:

Flashing Rectangle communications

This type of communications doesn't need any cables but is extremely slow and not duplex. Information can only be transmitted by the computer and not by the hybrid.

The comms parameters are:

Note: For the hybrid the stop bit has been stretched to be approximately 1.3 bit times.

USB cable communications

This type of communication is much faster the the Flashing rectangle and is full duplex.

The USB reference device is the ATEN UC-232A (PL2303 based) USB to serial converter. All tests on the computer system will use this device. It is assumed that other USB to serial converters will work but the reference device is what the host computer is aiming to interoperate with.

The comms parameters are:

Protocol flow control:

At certain times the computer will stop transmitting and wait for a single byte from the hybrid.