1. Introduction

   Project Flying Letters (short: flylttrs) is a text input library for Circle OS.
   The user controls the functions in the library through the input button and
   the acceleration sensor, which are built-in on both the STM32 Primer 1 and
   STM32 Primer 2. The library is much more useful for Primer 2 though, as this
   device does have the ability to store information on the non-volatile memory.

   The project Flying Letters was created by Wincent Balin as an entry for
   "STM32 Primer2 Design Competition". It was created with compliance to the rules
   of this contest. If a question arises, the author may be reached via
   wincent DOT balin AT gmail DOT com .

2. Description of files

 

File	Description
flylttrs.c	Source code of the Flying Letters library
flylttrs.h	Include file
Eliza.c	Source code for example application (see below)
README.txt	Documentation
Primer1	Folder with project files for STM32 Primer 1
Primer2	Folder with project files for STM32 Primer 2

3. Usage

   To use the library you have to add the file flylttrs.o (compiled from
   flylttrs.c, look into the Primer2 or Primer1 example) to your project. Then
   you have to include the file flylttrs.h (with #include "flylttrs.h") into
   the source file where you need to use the input functions. Do not forget
   to add the include directory, where flylttrs.h resides, to the include file
   path ("Include directories" option in the Ride7 IDE).

4. Functional description

   To use the input functions from the Flying Letters library you will have to
   call them from your Circle OS Application_Handler() function. The library
   will be initialized within the first call. Also, during the first call
   the library stores the orientation of the screen till the end of input.
   All functions return true to signal end of output and false otherwise.

   bool fl_getinput(char* output,
                    size_t osize,
                    char* input,
                    size_t* isize,
                    const size_t max_isize);

      This is the simplest function to call. It shows the output screen first.
      On the output screen the char array output of the size osize is shown.
      If the screen is too long, it will be shortened with "..." an the end.

      After you pressed the button you get to the input screen. On top you will
      see the register indicator with arrow under the current one. Tilt the device
      away from yourself to change the register.
      Below the register indicator you see the character row. Tilt to the sides
      to scroll the character row. Tap on the device to input the character
      currently selected. You will see this character in the input line just below
      the character row. To delete the last character turn over the device.
      Below you see the abbreviated form of the instructions described above.
      The input line is stored in the char array input with size isize.
      The length of the input in characters can not go over max_isize.

      After pressing the button you get to the confirm screen. Tilt the device
      to move the pointer onto the one of the buttons "Ok", "Cancel" and
      "Correct errors". Press the button to confirm your input.

   bool fl_getinput_without_output(char* output,
                                   size_t osize,
                                   char* input,
                                   size_t* isize,
                                   const size_t max_isize);

      This function proceeds to the input screen at once. Except from this
      it behaves just like the first function.

   bool fl_getinput_without_confirm(char* output,
                                    size_t osize,
                                    char* input,
                                    size_t* isize,
                                    const size_t max_isize);

      This function does not have confirm screen. Otherwise it behaves
      like the first function.

   bool fl_getinput_without_output_and_confirm(char* output,
                                               size_t osize,
                                               char* input,
                                               size_t* isize,
                                               const size_t max_isize);

     This function has input screen only. The description of this screen
      is featured in the description of the first function.

5. Example application

   A rudimentary implementation of Eliza was created to serve as the example
   how to use Flying Letters library. Eliza is the first publicly successful
   attempt at natural language processing. Look at the source in the file Eliza.c
   for further explanations.
   To install the application, install Eliza.lib with the following command:
   Circle_Mgr AEliza.lib S
   Execute this command in the folder where Eliza.lib resides.

6. Troubleshooting

   Remember that the object file flylttrs.o was compiled for Circle OS 3.71.
   If you have any problems with Flying Letters, try to recompile flylttrs.o.
   Do not forget both to include flylttrs.h and to add the path to the folder
   where flylttrs.h resides to the "Include directories" entry in the Ride7 IDE.