LEDybug

Power

Push Button On-Off

To turn the LEDybug On, press the recessed power push button switch located at the end of the device. To turn it Off, press the same button again.

The power switch is recognized when pressed down. The length of time held has no effect and the release has no effect. The debounce time for the switch for both On and Off is about 26 ms. There is an additional, noticeable, 500 ms delay between power-off actuation and display image disappearance.

Batteries and Charger

The LEDybug runs on 6 AA cells, which may be either rechargeable or non-rechargeable and any chemistry, such as NiMH, NiCd, etc.

The batteries are accessible through doors on the back of the device. Observe the polarity signs, plus and minus, for each cell. The device will not be damaged if the cells are placed in backwards; neither will it work.

For more than occasional use, I recommend rechargeable
Nickel Metal Hydride (NiMH) cells rated for 2000 mAh or more. -sz

The LEDybug has been powered at medium brightness for ten continuous hours in tests with a single set of fully charged NiMH cells rated at 2400 mAh. Your mileage may vary.

Batteries and chargers are available from Radio Shack and other local sources just about everywhere.

AC Adapter

An AC adapter is not required for the LEDybug. LEDybug was designed for portable, battery powered operation.

There is a power jack that accepts a plug from an AC wall adapter. This allows you to run without batteries. Of course you will need a power cord from the wall adapter to the LEDybug.

If the LEDybug has an AC adapter plugged in and has batteries, the adapter will be used, not the batteries. You can even switch from adapter to batteries or vice versa without causing LEDybug to reset or causing any other problem.

If your situation calls for an AC Adapter, the information on the AC Adapter page will be useful. It includes basic power requirements, in case you want to select an adapter, and recommendations.

Troubleshooting

If an image does not begin scrolling across the display within a split second of pressing the power push button, there is a problem. If you have not been fiddling with new Lists or new software, and if you are running from batteries, the batteries are probably dead.

If you have an wall adapter and connect it, since the wall adapter take precedence over the battery, if the display starts, then the batteries are definitely dead.

If you have been changing software or lists, it is possible that the batteries are good but the software or lists are bad in such a way that the display does not start. See those sections for advanced trouble shooting.

Display

Message Scrolling

Based on the pixel width of the display and of the characters, four characters can fit across the display. In order to display longer messages, characters must be scrolled across the display. In spite of this apparent limitation, he display seems to be quite readable. In fact, the shortness of the displayed portion of the message means that the viewer cannot take his eyes off of the display or else he will miss part of the message.

There are two Scrolling Modes:

  • Scroll Back: Scroll forward at reading speed. At the end of the message, scroll back fast to the beginning. Repeat. This has the effect of marking the end, and beginning, of a long message.
  • Scroll Continuous: Scroll forward at reading speed. At the end of the message, let the message run off the left of the screen, then show the message enter the right of the screen and display again. Repeat.

There is a Setting called Scroll that controls which scroll mode to use. When at this Setting, press the Right Arrow Key to toggle between settings.

Nack

Nack is short for negative acknowledge. The Nack flash, a repeated set of flashes of one pixel in four, is shown to acknowledge that a keystroke has been detected and to indicate that the requested operation cannot be preformed. An example of this is, in Normal mode, when the Up key is pressed but there is no previous message to go to.

Chase Lights

The chase lights are the pixels around the periphery of the display. When they are active, every fourth pixel is on and the position of the pattern advances by one pixel every 20 ms. The appearance is that a row of lights are traveling around the edge of the display. When they are inactive, these pixels are all off.

Push Buttons

There are eight Push Buttons on the face of the LEDybug that control its functions. A Push Button is recognized when pressed down. Release is not recognized. There is no repeat function.

The Push Button presses will be recognized as quickly as your finger moves. If you press the Push Buttons in a fast sequence, all actions will be taken but intermediate displays may be suppressed. In this way you will always see the display of the last key you pressed and the LEDybug display will not lag behind your actions.

There are two groups of four keys. One group is on the left side of the display and one group is on the right. The keys in each group are at the corners of a diamond. The keys may be referred to in general as "left side top key" or "right side left key", but key names are based upon the mode that the LEDybug is in. These key names and functions are described below and summarized on the Reference Card.

Modes

LEDybug has eight Push Buttons but many more functions that might be performed. A Mode in LEDybug is a set of up to eight functions assigned to the eight Push Buttons together with visual cues that give the mode a characteristic appearance. Each mode is associated with some activity.

This section is an overview of the LEDybug modes. The modes are described in more detail in Activities. See the Reference Card for a summary of the key names, key positions and mode appearances of all modes.

Normal Mode

Navigation through the hierarchy is performed in Normal Mode. Arrow keys are used for moving from one message to its directly connected parent, sibling, or child messages. See Activities » Navigation for details.

Searching through the hierarchy for character strings is performed in Normal Mode. See Activities » Text Search for details. Searching for tags is very similar to searching for character strings and is done in Normal Mode. See Activities » Tag Search.

The Edit Key of Normal Mode is the gateway to text editing and changing the message hierarchy. See Activities » Editing Text and Changing the Hierarchy for details.

When the LEDybug is powered up and started, it is in Normal Mode and the message that is the top of the hierarchy is displayed. Normal Mode is entered when Text Edit Mode is exited, and possibly when Character Selection Mode is exited.

The appearance of the Normal Mode is characterized by scrolling text and active chase lights.

Text Edit Mode

Text Edit Mode is entered by executing the Edit Text command in the Editing Menu.

The appearance of Text Edit Mode is up to four characters of text that are static, not scrolling. A cursor is displayed as a vertical line before or after a character; or if there are no characters, it will be displayed by itself. The chase lights are inactive.

In the Text Edit Mode you can

  • Move the cursor left and right through the characters of a message
  • Backspace or Delete characters
  • Enter Character Selection Mode

If the cursor is between characters, the Backspace/Delete Key will act as a Backspace, removing one character to the left of the cursor. If the cursor is to the left of the first character, the Key will act as a Delete, removing the character to the right of the cursor. As a result of these rules, if you press this Key repeatedly, you can always remove all characters in the message without repositioning the cursor.

You may exit Text Edit Mode to Normal Mode by pressing the Edit Key. You may also exit by pressing the Left Arrow key until the cursor is to the left the first character, the pressing it one more time. When you exit Text Edit Mode, the edited message is saved in RAM.

See Activities » Editing Text for more about the Text Edit Mode in the context of Editing Text.

Character Selection Mode

Character Selection Mode is use to select a character to be inserted at the cursor position.

When you enter Character Selection Mode, you will be at the top of a hierarchy of character strings. The menu will be something like the following and the current, scrolling message will be the first in the menu, in this case "lower case characters." In the messages that you see, the actual characters will appear, not these descriptions.

  • lower case characters
  • upper case characters
  • digits
  • punctuation and special characters

These character strings are arranged in a hierarchy. When you position to one of these messages and press the Right Arrow Key, you will see another level where each message is a subgroup of the character string that you just selected. Keep selecting more specific groups until, at the bottom level, you find one character per message. At that point, press the Right Arrow Key to "select" or insert the character at the cursor position. LEDybug will go back to Text Edit mode so that you can see the character that you just entered in the string that you are editing. The cursor will be to the right of the inserted character so that you can select another character without adjusting the cursor.

The appearance of the Character Selection Mode is characterized by scrolling character strings and inactive chase lights.

You may exit from each lower level of the character string hierarchy by pressing the Left Arrow Key, just as in a normal hierarchy. At the top level of the character string hierarchy, press the Left Arrow Key to exit Character Selection Mode and go back into Text Edit Mode. Also, you may press the Edit Key at any time in Character Selection Mode and exit to Text Edit Mode.

See Character Selection Menu for more detail.

Application Modes

When an application or game is operating, the appearance and the key effects are defined by the application.

Mode Appearance Summary

Mode/Appearance Scrolling Chasing
Normal Yes Yes
Edit Text No Yes
Character Selection Yes No

Menus

As in other computers, menus on the LEDybug are lists of commands. On the LEDybug, menu items are implemented as sequence of sibling messages which are navigated in Normal Mode like any other part of the hierarchy and displayed one at a time. When the menu is first shown, the first child is displayed.

There are two kinds of menus:

  1. Menus at particular places in the Hierarchy:
    • Generally the action applies to the whole list or the overall action of LEDybug.
    • These correspond to a pull down menu at the top of a window.
    • The parent is a heading, like "Settings" or "Commands" below.
  2. The edit menu attached to the current message:
    • Generally, the action applies to the current message.
    • These correspond to a popup menu, appearing in response to the edit key.
    • The parent is the current message.

Menus in the Hierarchy

  • Settings…
    • Brightness!
    • Scroll: Back | Continuous
    • Alphabet
  • System…
    • Commands…
      • Turn Display Off!
      • Turn Power Off!
      • Pixel Test!
      • Unused RAM
Settings
Menu of options or preferences. Once saved as a part of the User hierarchy, these are persistent during power off.
Brightness
Press the Right Arrow Key to increase Brightness to the next of six levels.
Scroll
Press the Right Arrow Key to toggle between Scroll Back and Continuous Scroll.
Alphabet
Set Alphabet for Character Selection Menu. The alphabet that is the first child of Alphabet is selected.
System
Heading for all system items.
Commands
Menu of system commands.
Turn Display Off
Press the Right Arrow Key to turn off the display to conserve power but retain RAM. Then, press any key to turn the display on again and restart the LEDybug.
Turn Power Off
Press the Right Arrow Key to turn power off completely. Press the On-Off push button to restart.
Pixel Test
Press the Right Arrow Key to display a group of pixels at a steady level to determine if a pixel error exists. Press the Right Arrow Key again to display the next group of pixels. Press the Left Arrow Key to display the previous pixel group, and, if at the beginning, exit the command. Press either the Up or Down Arrow Key to immediately exit the command.
Unused RAM
This message displays the amount of available RAM in the LEDybug without an additional keystroke.

Edit Menus

  • Edit Text!
  • Insert Message…
    • New After!
    • New Child!
    • Paste After!
  • Cut Message!
  • Move Up!
  • Move Down!
  • Save!
Edit Text
The Right Arrow Key executes this command, which enters the Edit Text Mode.
(Edit Text Mode)
This is not a message in the message hierarchy. Described in Activities»Editing Text. The Down Arrow Key goes to Character Selection Menu.
Character Selection Menu
A hierarchical menu to select a character and insert it at the cursor. See overview at Activities»Editing Text and detail at Character Selection Menu.
Insert Message
Heading for three types of insert commands.
New After
The Right Arrow Key inserts a new sibling message after the current one.
New Child
The Right Arrow Key inserts a new child message under the current one.
Paste After
The Right Arrow Key inserts a previously cut message as a sibling message after the current one.
Cut Message
The Right Arrow Key cuts the current message. It may be pasted elsewhere. If it is not pasted, this command is effectively a delete message command.
Move Up
The Right Arrow Key moves the current message up one position, ahead of its previous sibling. If there is no previous sibling, a Nack is shown and no other action is taken.
Move Down
The Right Arrow Key moves the current message down one position, after its following sibling, otherwise as Move Up.
Save
The User Hierarchy in RAM is saved in Flash.

See Activities»Changing the Hierarchy for some of these commands.

Activities

The previous sections describe the individual actions at a keystroke level. This section describes how the individual actions are used together to perform simple activities.

Navigation

Navigation means moving through the hierarchy, one message at a time, from a message to its parent or sibling or child. At each step, the message at the current position in the hierarchy is displayed. Navigation takes place in Normal Mode.

Hierarchy Visualization and Terminology

The hierarchy of messages may be visualized as an old-fashioned outline such as the Table of Contents at the top right of this page. It may also be visualized as a multilevel pull-down menu on the Macintosh or Windows.

The terminology used here is that one message can be the parent of one or more child messages. A single message in the hierarchy has no parent; this message is at the top of the hierarchy. A message can have at most one parent. A child is deeper than its parent and the parent higher than the child.

The relation between any two child messages of a single parent is that of sibling. Sibling messages have an ordering, with the first message being number one.

When visualized as an outline, a child is indented more than its parent and is shown below its parent. The top of the hierarchy appears at the top of the outline and is indented the least. The order of child messages in the visualized outline is the same as the ordering of the sibling messages.

Oversimplified Navigation

The following is an oversimplified, but mostly correct, navigation scheme. It is not exactly what is used in LEDybug.

The responses to the arrow keys:

  • Left Arrow/Parent
    • if parent exists, position to parent, display message
    • if no parent exists, show Nack
  • Right Arrow/Child
    • if a command is defined for this message, execute the command
    • if a child exists, position to first child, display message
    • if no child exists, show Nack
  • Up Arrow/Previous sibling
    • if after first, position to previous sibling, display message
    • if at first sibling, show Nack
  • Down Arrow/Next sibling
    • if before last sibling, position to next position, display message
    • if at last sibling, show Nack

The words in bold are incomplete. The reason for the extended action is given next.

Hint: You can always get to the top of the hierarchy by pressing the Left Arrow/Parent key repeatedly, until you see a (Nack) flash, indicating that the message you are on has no parent.

Finding Hierarchy Location by Navigating

When you are lost in the hierarchy you may need a way to determine your location within the hierarchy. Your location in the hierarchy is determined by the parent message of the current message, and the parent messages all the way to the top of the hierarchy.

Since LEDybug displays one message at a time, one approach is to display the messages at each higher level with a keystroke per level. This can be done one message at a time from the current message to the top of the hierarchy, and then one message at a time from the top back to the current. In this way, you not only discover the parents at all upper levels, you do so without changing the current position.

Navigating from the current to the top can be done with the Left Arrow/Parent key, as in the simple navigation.

Navigating from top to the current can be done with the simple navigation rules: go to the first child using the Right Arrow/Child key, and then through the siblings using the Down Arrow key to get to the proper sibling; repeat at each level. However, this means that you have to memorize the messages at every level going up and find them, in reverse order, while going back down. It also takes more keystrokes than one per level.

A better way is for the LEDybug Right Arrow/Child key to go to the previously visited child instead of the first child at each level. With this feature, when navigating from the top back to the current message, you only need to use the Right Arrow key and the LEDybug retraces your steps for you.

However, this feature raises a few questions:

  • When does LEDybug go to the previously visited child, and when does LEDybug just go to the first child?
  • Can this feature be turned off so that you can go to the first child, if desired?

The general rule is that the Right Arrow will go to the previously visited child if you have only used the Left Arrow key to go to the top and the Right Arrow key to return to the current message. If you use the Up or Down key, the following Right Arrow key will go to the first child because you have not been down that branch immediately before. If you use the Left Arrow key when at the top, which generates a Nack, then the Right Arrow key will go to the first child; this is another way to turn off the previously visited child and restore the first child method.

Rules of Navigation

Here are the full rules of Navigation.

There are three variables:

  • Stack: one element per level of depth in outline, each element has sibling-number at that depth
  • Variable: current-depth
  • Variable: max-depth

The stack keeps track of the current message in the hierarchy of messages. The element at each level of the stack gives the sibling number at that level, 1 being the first sibling. The message that is displayed is the message at the sibling-number of the element at current-depth whose parents are given by the sibling-number of all lower-numbered depths than the current-depth.

The responses to the arrow keys:

  • Left Arrow/parent
    • if at top (current-depth=1), Nack, set max-depth to current-depth value
    • if not at top, decrement current depth, display parent message
  • Right Arrow/child
    • if Hidden Text command exists, execute it
    • if hierarchical command exists, execute it
    • if child exists,
      • if max > current, increment current-depth, display previously visited child message
      • if max = current, increment current-depth and max-depth, set sibling-number to 1 at current-depth, display first child message
    • if neither, Nack
  • Up Arrow/previous sibling
    • set max-depth to current-depth value
    • if at first sibling, Nack
    • if after first, decrement sibling number at current stack position, display sibling message
  • Down Arrow/next sibling
    • set max-depth to current-depth value
    • if at last sibling, Nack
    • if before last sibling, decrement sibling-number at current-depth stack position, display sibling message

Note that "set max-depth to current-depth value" effectively removes any memory of deeper previously visited child sibling-numbers and restores first child action at this and deeper levels.

Editing Text

Editing text is the manipulation of text, character by character. It is important not only for changing text in messages to be displayed, but also for searching.

Initiating Text Edit

To initiate editing the text of any message in the hierarchy:

  • Navigate to the desired message.
  • Press the Edit Key, which causes LEDybug to
    • Tack the Edit Menu on to the desired message.
    • Position to first child message of the edit menu, which is Edit Text, and display it.
  • Execute the Edit Text command by pressing the Right Arrow Key, which causes LEDybug to
    • Enter Text Edit Mode,
    • Display the first characters of the message in static form.
    • Position the cursor before the first character.

To edit the Search Argument for a search:

  • Press the Search Key, which causes LEDybug to
    • Navigate to the Search Argument message
    • Tack the Edit Menu on to the Search Argument message.
    • Enter Text Edit Mode,
    • Display the first characters of the Search Argument message in static form.
    • Position the cursor before the first character.

After either of these two action, you will be in Text Edit Mode.

Text Edit and Character Selection

In Text Edit Mode, as described in more detail above in Text Edit Mode, you may:

  • Position the cursor to the left or right
  • Backspace or Delete
  • Initiate Character Selection
  • Exit Text Edit Mode and go to Normal Mode

When you first get to Text Edit Mode after Initiating Text Edit, actually at any time, you can delete unwanted characters. If you want to delete all existing characters in a message, especially if you want to clear an old search argument, you can just repeatedly press the Backspace/Delete Key until all the characters disappear.

To enter a string of characters, first position the cursor where you want to insert the string. If there are no existing characters, just proceed.

Repeat this loop to enter a string of characters. It starts in Text Edit Mode and goes back and forth between Text Edit and Character Selection Mode as follows:

  • In Text Edit Mode, press the Select (Down Arrow) key to enter Character Selection Mode.
  • In Character Selection Mode, narrow down the selection, level by level, until you select a single character with the Right Arrow Key.
  • LEDybug inserts the character at the cursor, moves the cursor to the right of the character, and goes back to Text Edit Mode.
  • In Text Edit Mode, verify that you got the character you wanted, and that it is where you wanted it. Reposition the cursor if it helps to see where you are.
  • If you got the wrong character, press the Backspace key to remove it. Reposition the cursor if necessary.
  • Still in Text Edit Mode, repeat the loop for the next character.

If you just want to change just one character, the instructions are essentially the same, just abbreviated. Start by positioning to the right of the bad character, then Backspace to remove it. Next, go through the loop just one time to insert one character.

To exit, if you are editing some message in the hierarchy, press the Edit Key to exit from Text Edit Mode. Then press the Left Arrow Key to exit from the Edit Menu. At this point you will see the message that you just edited scrolling on the display.

To exit and perform the first search, if you are editing the Search Argument, press the Next (or Previous) Key. You will see the next (or previous) message that matches the Search Argument. If there are no matches, you will see "Not Found". This message is tacked on to the Search Argument. To clear the Not Found message, press the Left Arrow key and you will see the Search Argument.

Text Search

With Text Search you can jump anywhere in the hierarchy to a message that matches a search argument, which is a text string.

Text Search is similar to internet search in that you have to key in a search argument. It is different in that internet search provides a page full of results while LEDybug provides one message at a time.

A message matches the search argument if it has a substring exactly equal to the search argument. Capitalization must be exactly the same. The search argument, including blanks, is treated as a single character string, not separate words.

The Text Search process happens in two phases: preparing the search argument and jumping to the next match.

  • Set up Search Argument
    • Start to set up Search Argument by pressing the Search Key in Normal Mode
      • LEDybug will perform the following behind the scenes:
        • Navigates to the search argument.
        • Attaches the edit menu to the search argument.
        • Executes Text Edit command and enters Text Edit Mode.
        • You could perform these commands manually and get exactly the same effect.
      • You will see the beginning of the old search argument with the cursor before first character.
      • Delete any unwanted characters in the Search Argument.
    • Edit the text of search argument as usual, using Text Edit and Character Selection Modes.
    • Jump to the first match by pressing the Next or Previous Key.
      • LEDybug will perform the following behind the scenes:
        • Exit Character Selection Mode, if necessary, to Edit Text mode.
        • Exit Text Edit Mode to Normal Mode, at the Edit Text command.
        • Exit Edit Text command, at the Search Argument message.
      • LEDybug jumps to the first match, as below.
        • If there are no matched messages, LEDybug displays "Not Found"
          • The "Not Found" message is tacked on to the Search Argument.
          • Press the Parent/Left Arrow key to dismiss this message.
          • Press the Edit key or the Search key to re-edit the Search Argument.
  • Jump to Matches
    • Press the Next (Previous) Keys to display the next (previous) matched message.
    • The LEDybug will find the Search Argument, itself, as it jumps from match to match through the entire hierarchy.

The section for "Jump to Matches" can come at any time after the Search Argument is set up. Either using Tag Search or directly editing the Search Argument would invalidate you previous Search Argument.

If you want to abort the Search Argument setup, the simple way is to press the Next Key. This will save the changes that you may have made to the Search Argument so far and attempt a search. From this point, you could just press the Left Arrow Key until you get to the top of the hierarchy. Alternatively, you could exit from Character Selection Mode and then exit from Text Edit Mode, as described in Editing Text.

If you want to quit jumping to matches, just don't press Next or Previous again. You may perform any other activity.

The Search Argument is part of the User hierarchy and is saved with the Save command. This means that you can set up the Search Argument for some special purpose, such as for a demonstration, then do the Save and power down. When you turn on the LEDybug, the Search Argument is as you left it and you can just press the Next Key to go to the first matching message.

Tag Search

With Tag Search you can jump anywhere in the hierarchy to a message that contains a desired tag. A tag can be one or more characters, excluding blanks. Tags matching is case sensitive.

Putting Tags into Messages

Tags must be coded in a message before you can search for them.

A tag must be placed in Hidden Text (more about that below). Basically, Hidden Text is text in a message that is enclosed in curly brackets. Nether the Hidden Text or the enclosing curly brackets display.

The tag consists of the Tag indicator, an upper or lower case "T", a space, and the tag name.
For the tag named BR, the tag would be "T BR".
This tag in Hidden Text in a message could be something like this:

“{T BR)A brighter display is easier to read and more eye-catching.”

You can enter the tag and Hidden Text with the normal Text Edit procedures.

Searching for Tags

Tag Search is very similar to Text Search in that first, you specify what you want to search for, in this case a Tag, and second, you jump to each message with that Tag. The second part is identical to Text Search: see "Jump to Matches" above.

There are two ways to specify the Tag for the Search Argument.

  1. Select a tag from a list. One advantage of this approach is that it requires no text entry. A second advantage is that the tag is sure to exist.
  2. Enter the tag indicator and the tag as search argument. If you are good at text entry, this could be quicker. It also gives you some insight to what is happening behind the scenes.

To select a tag from a list of all tags:

  • In Normal Mode, navigate to the top of the hierarchy (press the left arrow key repeatedly).
  • Press the child/right arrow key to go to the second level.
  • Press the down key to go to the "Tags" message.
  • Press the child/right arrow key to go to the first tag.
  • Press the down key to go through the tags until you find the tag that you want.
  • Press the execute/right arrow key to go to the first message containing the selected tag.
  • LEDybug will
    • prepare the tag in the Search Argument as if you had entered the tag as described below.
    • jump to the first message that it finds, with the selected tag, and display it.

To enter the tag in the Search Argument:

  • Press the Search Key in normal mode, the same as starting a Text Search.
  • Edit the text of the search argument.
    • Delete any previous characters in the Search Argument
    • Enter the tag indicator "T" or "t" at the beginning of the line, then a space.
    • Enter the desired tag name next, eg "BR" from the example above.
    • At this point your search argument might look something like "T BR".
  • Jump to the first match by pressing the Next or Previous Key.

Changing the Hierarchy

This section describes changing the messages in the hierarchy. For changing the text in any message see Editing Text.

General

From Normal Mode, pressing the Edit Key will tack on the Edit Menu. You will see the first item int the Edit Menu which is Edit Text. The following items are concerned with changing the hierarchy. They are:

  • Insert Message…
    • New After!
    • New Child!
    • Paste After!
  • Cut Message!
  • Move Up!
  • Move Down!

These commands apply to the message that was displayed before you pressed the Edit Key. This message is called the current message.

Commands

New After
The Right Arrow Key inserts a new sibling message after the current one. The inserted message contains "<New Msg>". After the command, the Edit Menu is on the new message.
New Child
The Right Arrow Key inserts a new message as a child of the current one, if the current message has no child. The inserted message contains "<New Msg>". After the command, the Edit Menu is on the new message. If there is already a child message, there is no action and a Nack is displayed.
Paste After
The Right Arrow Key inserts a previously cut message as a sibling message after the current one. If there was no previous Cut, or if there was a Paste after the last Cut, then there is no action and a Nack is displayed. Other commands, such as New After, after the Cut but before this command do not prevent this Paste from working. After the command, the Edit Menu is on the pasted message.
Cut Message
The Right Arrow Key removes the current message, and its sub-hierarchy, and holds it for a Paste. If it is not pasted, this command is effectively a delete message command. After this command, the edit menu is on the message following the (deleted) current message; if there is no message following the current message, it is on the message preceding the current message; if the deleted message was the only child of its parent, then the edit menu goes to the top of the hierarchy.
Move Up
The Right Arrow Key moves the current message up one position, ahead of its previous sibling. If there is no previous sibling, a Nack is shown and no other action is taken. The Edit Menu remains attached to the moved message so that a subsequent press of the Right Arrow Key will move the message up again, if possible.
Move Down
The Right Arrow Key moves the current message down one position, after its following sibling, If there is no following sibling, a Nack is shown and no other action is taken. The Edit Menu remains attached to the moved message so that a subsequent press of the Right Arrow Key will move the message down again, if possible.

Suggestions

Delete before Adding Text

If you Insert After or Insert Child, when you go to Text Edit Mode, you probably want to delete the "<New Msg>" characters before adding your own content. The cursor will initially be to the left of all characters. Without repositioning the cursor, just press the BackSpace/Delete key nine times. The Backspace/Delete rule is a little complicated, but in operation, it eliminates a few keystrokes required to reposition the cursor.

Where to insert new messages

You may wonder where to insert new messages in the hierarchy.

The simplest place, especially if you are in a rush, is after the top of hierarchy message. On the plus side, if you are lost in the hierarchy, you can press Left Arrow until you get to the top of hierarchy, then press the Edit Key, then navigate to Insert Message » New After. On the negative side, if you insert messages after the top of hierarchy, the rule that pressing Left Arrow takes you to the top of hierarchy will be broken. In this case, you will have to press Left Arrow repeatedly, then Up Arrow repeatedly.

The second place is after the User heading. After you get to the top of hierarchy, one Right Arrow Key gets to the User heading. Then you can press the Edit Key and insert there. This does not break the rule of pressing the Left Arrow Key to get to the top of the hierarchy.

The third place is with the User hierarchy. After you get to the top of hierarchy, two Right Arrow Keys gets to the first message under the User heading.

Fourth, you can set up a new message called New Messages first under the User heading and insert under that. This is the neatest although it takes a few extra key presses to find.

Don't Do These Things

These are things you should not do.

  • Cut the top of hierarchy (when no messages are after it) — If you try this, LEDybug will ignore you.
  • Cut the top of the hierarchy when messages are after it — After Cut, Search will fail. If Saved, restart may fail.
  • Insert message after the top of hierarchy, then move it Up. — After Cut, Search will fail. If Saved, restart may fail.
  • Cut System — You may not see immediate problem. If Saved, restart may fail.

Things you probably don't want to do.

  • Cut the User hierarchy — You will loose all User data. If Saved, it will be permanent.
  • Cut Settings - You will loose ability to do these Settings. If Saved, it will be permanent.
  • Cut Tab - You will loose Tab function. If Saved, it will be permanent.

Things that look serious but are harmless.

  • Cut Search — No problem. This will be added automatically if you search.
  • Cut something in the System sub-hierarchy. — No problem. The System sub-hierarchy is not saved with the Save command.

If you do any of these things, do not Save. Just turn power off and on and you will restore RAM from Flash. If you Save your damaged hierarchy to Flash, you will have to reload Flash to restore the functions that you have deleted. In fact, the LEDybug may not start at all on power up.

Settings

The Setting items make heavy use of Hidden Text. These items function as commands when executed by the Right Arrow Key. They also display their current state values. The value giving the current state of the Setting is saved in Hidden Text in the commands, themselves. The value representing the current state is used during the Initialization process to make the value available for running code. The specialized code as well as the value representing the current state is kept in Hidden Text in the commands. It can be seen by Editing the text of the command.

When the command functions, it changes the state variable in the command itself, which is in RAM. In order to make the variable persist during power off, the Save command must be activated.

The individual Setting items are as follows:

Brightness
Press the Right Arrow Key to increase Brightness to the next of six levels; after the maximum brightness, the minimum brightness is selected. The current brightness value is shown as a digit from 1 to 6, brightest to dimest.
Scroll
Press the Right Arrow Key to toggle between Scroll Back and Continuous Scroll. Scroll back moves the message text right to left at a readable speed, then moves the text backwards very fast, then repeats. Continuous Scroll always moves the text right to left at a readable speed, with a blank space after the text disappears to the left and before it reappears at the right.

Save

Changes to text in messages, changes to the hierarchy, and changes to Settings are first stored in RAM. If you power down the LEDybug before saving them to Flash, these changes will be lost. The Save command saves User RAM to Flash.

The data that is saved with the Save command is called the User hierarchy. It includes the top of hierarchy message at the first level and all messages and their sub-hierarchies at the second level except the sub-hierarchy of the System message. It also includes siblings following the top of hierarchy message at the first level.

The saved data does not include the sub-hierarchy below the System message. If you want to change that, you must use the LEDybird.

The Save command is at the bottom of the Edit Menu. Execute it with the Right Arrow Key, as with any other command.

Save
The User hierarchy in RAM is saved as the User List in Flash. If no error is encountered, the message "Success" is tacked onto this command and displayed. (Use the Left Arrow Key to dismiss the Success message and go back to the Save command.) If there is an error, a Nack will be shown.

If you damage the User hierarchy and then save it, you make the damage permanent and you will have to load a file from a PC to fix the damage. If you damage the User hierarchy, then turn power off, the damage is lost as is any other change.

The suggested way to make and save changes is as follows:

  • Turn power off and on. This gives you a fresh copy of Flash, presumably good.
  • Pay attention and make your changes.
  • If something seems wrong, start from the top and turn power off and on again.
  • Don't get distracted. Proceed immediately to the next step.
  • If your changes were OK and you didn't cause any damage, then Save.

In other words, the time and action from power on through making changes to Save should be minimized.

Read the section: Changing the Hierarchy » Suggestions » Don't Do These Things.

Forth

Forth is a computer language characterized by

  • Two stacks: return stack and parameter stack.
  • Postfix operators, ie, Reverse Polish notation.
  • Can be interpreted. Can be compiled in single pass.

Languages like C have a fixed format stack frame for every subroutine call. If you pass nothing to or from a subroutine, you still get a stack frame. Forth does not have this overhead. You pass in and get back just what you need. The Forth subroutine call is cheaper in code and time. This makes small subroutines much cheaper. This makes it more economical to make smaller subroutines than in C. This makes reuse economical. This all makes Forth more efficient than C.

Postfix operators in Forth make source code look funny. They do not, however, contrary to many reports, make your computer run backwards.

The interpretation and compilation pattern in Forth make it easier to experiment, debug, and test interactively. It also enables the extensibility seen in LEDybug in Hidden Code.

LEDybug is built on Forth supplied by MicroProcessor Engineering Limited (MPE). The variants of MPE Forth used with LEDybug are

  • Forth 6 Cross Compiler ARM/XScale — A PC cross-compiler for LEDybug embedded code.
  • VFX Forth for Windows v3.9 — A PC compiler for the LEDybird windows application.
  • ARM ANS ROM PowerForth v6.30 — A run-time interpreter and compiler used for everything else. Every LEDybug includes a licence to MPE PowerForth.

MPE Forth was selected because

  • An interpreter and compiler are included in both PC and embedded run time code.
  • There is high level of compatibility between PC vs. embedded run time interpreter and compiler.
  • There is high level of compatibility between PC vs. embedded compiled code.

Uses of Forth in the LEDybug system.

  • LEDybug embedded code — Cross compiled and loaded into the LEDybug device.
  • Code in Hidden Text — Settings. Mostly interpreted. Calls cross compiled routines.
  • Code in Hierarchy — Apps and games like Pong. Source in messages in hierarchy. Compiled to RAM.
  • USB serial access to Forth — Used for debug and communication.
  • LEDybus serial access to Forth — Used for communication with daughter board.
  • LEDybird application — Compiled and run on a PC. LEDybird includes a simulator for LEDybug. The accuracy of the simulation is due to a large body of code shared between the LEDybug and LEDybird.
  • Lists holding hierarchical menus are actually Forth source code in Flash, compiled code in RAM.

Every LEDybug is, in effect, a LEDybug application development system. The first prototype application is the game Pong. It is distributed in the User hierarchy as Code in the Hierarchy. You can modify it and see your changes. You can study it, code other games or apps, and run them on the LEDybug.

Hidden Text

Hidden Text is text contained in a message that is delimited by and contained within curly brackets { }. The Hidden Text does not include the containing brackets. When the containing message is displayed, neither the Hidden Text or the containing curly brackets are displayed. More than one hidden text string can be coded in a message.

Hidden Text is viewed and edited normally by the standard Text Edit feature of LEDybug. If you are new to editing messages in LEDybug, you will not need to be concerned with Hidden Text. Just recognize it and leave it alone.

Hidden Text is actually Forth Code and follows Forth Syntax. It is executed in certain contexts listed below. It makes use of a special Forth vocabulary of cross-compiled. It can contain most Forth words, even key and print(.), but these words are directed to the USB serial lines, not to messages. The following description assumes some familiarity with the Forth Language.

Hidden text is executed in three contexts, and Search has four sub-contexts:

  • Display — Executed while building text for message display.
  • Execute — Executed by Right Arrow Key.
  • Search — Executed when stepping through the hierarchy by various processes.
    • Initialize or after edit
    • Search for string
    • Search for tag
    • %ExecLoad, Code in Hierarchy

Vocabulary

The construct "( n — )" is a Forth comment used in Forth to describe the parameters on the stack before and after execution of a Forth word (routine). This construct means that there is an integer, n, on the stack before the word executes and nothing is on the stack afterward.

h.
( n — ) If Display context, print the value to the message display. Otherwise, drop the value.
hBright+
( n — ) Preceded by a digit 1..6 representing brightness. This word implements Setting » Brightness. If Display context, display the brightness as a digit 1..6, in the message. If Execute context, increase the brightness, ie, decrement the brightness number; wrap the number around from 1 to 6. If Search/Initialize or Edit context, move the brightness value from hidden text to a global variable so that is available to control the display brightness.
hExecOnly
Continue executing the hidden text only if Execute Context. Otherwise exit the hidden text string.
hInitUnused
If Display context, print the initial unused RAM to the message display. Otherwise do nothing.
hPromo:
Promotion code follows. Parse and store the following promotion code. If Search/Initialize context, save promotion code in a global variable.
hPromo.
If Display context, print the global promotion code variable to the message display.
hScroll+
( n — ) Preceded by 0 for Scroll Back, 1 for Scroll Continuous. This word implements Setting » Scroll. If Display context: if n=0, display "Back", if n=1, display "Continuous". If Execute context, toggle between Back and Continuous.
hUnused
If Display context, print the current unused RAM to the message display. Otherwise do nothing.
T
A tag name follows. The action of the T routine, when executed is:
  • Parse and store the following tag name.
  • Search for tag context?
    • No. Continue executing remainder of hidden text.
    • Yes.
      • Does this tag match the tag being searched for?
        • No. Continue executing remainder of hidden text.
        • Yes. Return to calling search routine indicating match occured.
%ExecLoad
Compile the "Code in Hierarchy" from the last sibling message and its sub-hierarchy to RAM.
%ExitLoad
Usage: "[defined] Pong %ExitLoad". The routine [defined] returns True if the following word, in this case Pong, is defined in RAM. Otherwise it returns False. The word %ExitLoad exits the %ExecLoad process if its parameter is True. The purpose of this construct is to prevent a Code-in-Hierarchy application from being loaded twice.

Code in Hierarchy

%ExecLoad is a hidden text command which causes a Forth application to be loaded. The loaded program is not hidden text contained in {}. The loaded program is contained in a message and its sub-hierarchy. The message at the top of the program must be the last sibling of the message containing the %ExecLoad.

The loading process steps through the sub-hierarchy and performs EVALUATE on each message. See Forth » %ExecLoad.

This mechanism is used to load the code for the Pong game.

Vocabulary

getkeybit
?
keyTO
?
xypAsetpix
?
keybits
?
DisplayPause2
?
MenuHereUI
?

Initialization

  • Power On switch pressed.
  • Power Supplies turn on in sequence.
    • 5 V supply powers USB.
    • After above, 3.3 V and 1.8 V power CPU.
    • After above, LED supply is turned on.
  • CPU starts when power is available.
  • Forth system boots and runs from Flash.
  • Input from push button switches is enabled.
  • Down Arrow Key is tested.
    • Key Up, Normal.
      • LEDybug embedded code boots and runs from Flash.
      • Lists are read from Flash and compiled to RAM.
      • Hidden Text initialization done.
      • Prepare to display top of hierarchy.
      • Start Display cycle.
    • Key Down, Suppress Normal Load.
      • USB is active for debug or loading.
      • Forth is active for debug or loading.

Data Formats

ASCII, EOL
User and System Lists
List Format in PC File
List Format in Flash
List Transfer Format

LEDybus

The LEDybus makes it possible to mount daughter boards inside the LEDybug case. The following are available through this bus:

  • Battery and regulated power.
  • Serial connection to the Forth engine.
  • Serial connection to the external USB.
  • An Inter-Integrated Circuit (I2C) serial bus.

Possible daughter board applications:

  • WiFi
  • Radio Frequency Link
  • USB Host for communication or storage
  • Speaker
  • Real Time Clock
  • Accelerometers (motion sensors for games)
  • GPS
  • Battery Gauge
  • Speech Recognition

The connector is a female header, 2x5 pins on 0.1" centers.

LEDybus Pin Definitions:

Signal Pin Pin Signal Notes
V5 1 2 GND
V3.3 3 4 Vbat
SCL 5 6 SDA I2C
USBTxD 7 J 8 CPURxD input path
USBRxD 9 J 10 CPUTxD output path

J indicates a jumper that must be cut to interpose the daughter board between the CPU and USB.

Internal Operations

Tack On

To temporarily attach one or more messages as a children to another message. Once attached, the child messages can be navigated as any others in the hierarchy. Once you navigate from the children back to the parent message, the tacked-on message is removed. If a message has normal children, those child messages are not accessible until you navigate back to the parent and the tacked-on message is removed.

Examples of Tacked-on messages:

  • "Success" message is tacked on to the "Save" message.
  • The Edit Menu can be tacked on to any message.

Next and Previous Stepping

Used in search for text, search for tag, initialization, %ExecLoad.
Step vs process current item.


© 2010 LEDybug LLC