187 Wio: WioIXkb : Wio Interface without KeyBoard (187.html)

Keywords

WioIXkb "Wio: WioIXkb : Wio Interface without KeyBoard" LCD uJoyStick pgdn touch more help py "Enter key" "Wio Terminal" WioTerminal SeeedStudio ICH180RR D@CC WioIXkb displayThis.txt main.py uf2 WioIXkb01o11.py CLI CL "command line" mainIX import ".def" ".py" functionsIX mainIX.py uSD "uSD card" meld mainNew.py copy-then-pasted wioPY "improvised py programs" improvised "py folder" stable "stable version" stand-alone "stand alone" grep.py pgup grepResultList cmdHistoryList

(To enlarge .....Click it)
thumb: IXimage.jpg
IX or DC (IX by DC) or "|><"


This software is a part of the IX family of software.

(To enlarge .....Click it)
thumb: IMG_5045.jpg

WioIXkb V 01.0

(To enlarge .....Click it)
thumb: IMG_5049.jpg

WioTerminal

The quality of the actual text on the LCD screen of the WioTerminal (Source 01) is much better than shown above left.

Table of Contents

187 Wio: WioIXkb : Wio Interface without KeyBoard (187.html)
Introduction
Versions of WioIXkb
WioIXkb Commands available for the WioTerminal (fut)
WioIXkb.py
Wio Standard Files in the \WioIXkb folder
Micro Python Program Development for the WioTerminal
Requirements
MicroPython Code for the 5 button Joystick etc by scruss[deprecated]
MicroPython Libraries
WioIXkb Command Line Interface : CLI
Creating the main.py program using mainIX.py on the RPi
Converting a Python program (improvising it) into a WioTerminal function module
Future List (wioPY.txt) of .py Modules in the py/ folder 
Full set of WioIXkb CLI commands
WioIXkb Functions
WioIXkb Error and Warning Messages
Future Applications for the WioIXkb
End of Article (Sources Follow)
Sources

Introduction

The WioTerminal (Video Source 01) can contain many text files and run many programs. It runs Python and c/c++ programs. But it needs to be plugged into an external computer to view, change or add programs or text files. To use REPL, it also needs an external computer but REPL cannot list files. The absence of a mouse/keyboard on the WioTerminal is a serious handicap. Another handicap is that the stand-alone WioTerminal cannot write files to its flash memory. Without a connection to a computer, the basic WioTerminal cannot display files, nor run selected Python programs. The program WioIXkb is a partial solution. The methodology used by the author in creating Micro Python software for the WioTerminal could be described in a separate article. However, the process of preparing this meaningful program (WioIXkb) illustrates why such a complicated methodology is needed.

To be useful in the absence of a keyboard and a mouse, the WioIXkb makes use of the switches and buttons on the WioTerminal. It also makes use of various lists of words, phrases, numbers and commands etc. The user can simply select items from these lists instead of typing on a keyboard. One such list contains the 1000 most frequently-used English words. Perhaps a future version of WioIXkb will provide an (slow yuk!) on-screen keyboard if it is deemed necessary. Perhaps Blue-Tooth keyboard support for the WioTerminal will arrive before that is necessary.

Versions of WioIXkb

Various versions of WioIXkb have been envisaged and will be designed to do the following:

v01.0
Display the last 16 lines of the directory in the top folder of the WioTerminal.
Blink the Blue LED once every 4 seconds.

v01.11 current version
Display the dir of the WioTerminal on multiple pages of the LCD.  One CLI command,
"pgdn" is executed when the user hits the Enter key (pressing straight down on the
uJoyStick button) on the WioTerminal.

v02.1 stable version (fut)
1. Display the directory of the top folder of the WioTerminal.  The CLI command,
"pgdn" is executed when the user hits the Enter key (which is the center key
of the uJoyStick) on the WioTerminal.
2.Display any file on the WioTerminal using the "more row (number) command. The 
"more row (number) command is selected by pressing (one at a time) the 3 buttons on 
the top edge of the WioTerminal. Hit the Enter Key (center button on the uJoyStick) 
to refresh the command because the (number) must be selected. The user will use 
the third (the rightmost) button on the top edge of the WioTerminal to scroll 
through the numbers from 0 to 15. When the CL (Command Line) shows the desired 
row number, the user should hit the Enter key. The LCD will select (highlight 
by blinking) the desired row on the CL (Command Line).   Hitting Enter 
(on the uJoyStick) a second time causes the current command on the Command 
Line (CL) to be executed. Occasionally, it is necessary to hit LEFT (on the 
uJoyStick) a second or third time to cause the CL to be executed.

v02.11 (fut)
Copy the directory in the top folder of the WioTerminal into the List named "aFullList".
Copy the first 16 rows of "aFullList" into "aList"
Display  "aList" on the LCD screen.
If keyStroke=Enter, copy the next 16 rows of "aFullList into "aList"
Display  "aList" on the LCD screen. etc
If keyStroke=UpArrow,     move the "terminal cursor" up   1 row in "aList"
Display  "aList" on the LCD screen. etc
If keyStroke=DownArrow,   move the "terminal cursor" down 1 row in "aList"
Display  "aList" on the LCD screen. etc
etc.

v03.0 (fut)
Include the first minimal CLI (Command Line Interface) for the WioTerminal

v04.0 (fut)
Include a comprehensive CLI (Command Line Interface) for the WioTerminal
the mainIX.py program is also added. It greatly increases the functionality
of the main.py program which is built around WioIXkb.py
(To enlarge .....Click it)
thumb: IMG_5050.jpg

WioIXkb V 01.11 page 1

(To enlarge .....Click it)
thumb: IMG_5051.jpg

WioIXkb V 01.11 page 2

As shown in the images above, the splash (and only) screen for WioIXkb (v01.0) consists of one command line
 at the top and as many lines of a text file as can be displayed on the LCD of the WioTerminal. The current
 version (v01.11) displays the first page of the top folder with one command ("pgdn") available.  Hitting the "Enter"
 key (by pressing down on the tiny uJoyStick) takes you to the next page. Future v01.12
 allows the user to interact more with the WioIXkb program on the WioTerminal. The tiny "uJoyStick" on the 
 bottom right hand corner of the WioTerminal (visible in the image above) can be thought of as the 4 
 direction keys (LEFT, RIGHT, UP, DOWN) normally found on a keyboard. The center uJoyStick key 
 (pushbutton) serves as the "ENTER" key.  The command that was automatically run when WioIXkb started
 was simply "dir".  After displaying the first page of the directory, the command text was changed  to "pgdn" 
 just to the right of the "$$" in the top left corner.  When the "ENTER" key is entered (when the center of 
 the uJoyStick is pressed) the command "pgdn" is executed.  This "pgdn" command causes the next screen of 
 the directory (shown on the right) to be displayed.  In this way the WioIXkb program runs without a keyboard. 

 Pressing down on the center of the uJoyStick ( i.e. hitting the Enter key) causes the next page of the file (or directory
 in this case) to be displayed as seen in the right-most image above.  As can be seen, the directory entries are
 not sorted. The name of the "uf2" file can be seen.  The original name of the "main.py" program is seen
 at the right side of the second row.
The source code of WioIXkb01o11.py (version v01.11 of WioIXkb [note the "o" in place of a "."]) can be downloaded from Source 12. The extension must be changed from ".txt" to ".py" before it can be loaded and run on the WioTerminal as "main.py". Its name must be changed to main.py in order for it to start up when the WioTerminal is rebooted. The WioIXkb, py and proc are folder names (not filenames) in the above images.

A fairly detailed description of the WioIXkb project can be found in Source 03: wioWiki.txt .

WioIXkb Commands available for the WioTerminal (fut)

The Enter key (press straight down on the uJoyStick)

The main key (when using WioIXkb) is the "Enter" key (Center position of the uJoyStick).  
Whenever this key is hit:

1. the full command on the command line is examined to see if any phrase need to be 
looked or evaluated on the CL (Command Line), if so the phrase (parm1 or parm2 is 
evaluated and written to the LCD. 
2. second; the command line is evaluted to see if it is invalid (any error will be 
replorted), 
3. the command is executed,  
4. the command is written on the right of the command line preceded by a "#". 
5. if the command is invalid, an error message is displayed, 
6. the resulting display is sent to the LCD, 
7. the next command on the command line (CL) is set to "pgdn", (always true, [I believe!].

The previous command (the one just executed) is displayed on the top row of the LCD (preceded by a "#"), to the right of the "pgdn" which makes it a comment for the proferred "pgdn" command. Another (invisible) action taken is that the command just executed is appended to the internal cmdHistoryList (that can be displayed by the user). If the user hits "Enter" again, the "pgdn" is executed which will display the second page of the result of the previous command, etc. But if "Enter" is not pressed, whatever the user enters (by using the 3 top buttons) forms a new command. When the user is satisfied with the new command (as shown on the CL), hitting "Enter" will cause execution of the new command.

other buttons

The leftmost button on the top edge of the WioTerminal when pressed, scrolls through the list of commands. The middle top edge button scrolls through the first parameter, parm1. The third button on the top edge scrolls through the second parameter, parm2. These three parts of the command line, "command parm1 parm2", form the full command. When the user accepts the full command line (CL) to be run, the user should hit "Enter".

The list of commands (only one word long) that are permitted by WioIXkb is shown below:
Note 1: file interactions are "read only" on standalone WioTerminals.
Note 2: grep is the tinyPython program, grep.py, with very limited functionality.
Note 3: a suffix of ">\dev\sd\filename" will write the output to
      the uSD memory card instead of to the LCD. (fut)
Note 4: a non-standalone WioTerminal is one that is plugged into a computer
      (file writing e.g. copying .uf2 and other files to the internal
     flash drive is permitted.)
Note 5: It will be possible to write files onto a removable uSD card

WioIXkb.py

The WioIXkb.py Python program (v01.0 as of 2023CMar22) can be downloaded as a text file from Source 02. Once it has been downloaded, its file extension should be changed from ".txt" to ".py". Then "main.py: can be deleted from the WioTerminal. Then WioIXkb.py should be renamed to "main.py" which can be Copy-then-Pasted to the WioTerminal. When the WioTerminal is subsequently restarted (Power turned OFF then ON again), the main.py that will be automatically run will be the WioIXkb.py program.

In version 01.0 the resulting LCD screen that appears will be as shown in the image below.

(To enlarge .....Click it)
thumb: IMG_5086.jpg

WioIXkb v01.11 with a 3v-5v Power Pack on a stand

The above image shows the WioTerminal (WioIXkb V 01.0) and a 3v-5 Volt Power Pack on a stand made for the author by Myrle on his 3D printer. The design of this printable phone stand can be found at Source 17.

The size of the LCD screen on the WioTerminal is 18 rows of 57 columns of characters.

The author has not yet (as of 2023 C Mar 22) tested the "Circuit Python for the WioTerminal" uf2 from Adafruit (Source 05) .

Wio Standard Files in the \WioIXkb folder

The following files are available to a WioIXkb user in the \WioIXkb folder to view or grep. They are placed in this folder to reduce the number of files in the top folder. The absence of a keyboard on the WioTerminal is a true handicap. However, the user can open any one of the special "keyboard" files and select a row of the file to be "pasted" into the command line of the WioIXkb program. Pasted lines will not contain record terminators such as \r or \n. The special "keyboard" files are: wioKeys.txt, wioNumbers.txt and wioWords.txt
The wioCmdEqual.txt file is used by WioIXkb to translate simple commands to an equal or equivalent command that is better processed by the WioIXkb program. A copy of the wioCmdEqual.txt file can be seen in Source xxx.

Wio Standard Lists

A few internal lists are of special interest to the user. They are:

Micro Python Program Development for the WioTerminal

It is somewhat difficult to develop software in Micro Python for the WioTerminal. I use minicom (Source 14) running on a Raspberry Pi-400 in order to send/receive characters in serial mode between the Pi-400 and the WioTerminal. The WioTerminal does provide an interactive interface via the REPL command. This is often called a "Headless" mode. A CLI (Command Line Interface) does not exist. This means that commands like "dir" and "grep" are not (yet) available. This is the reason that WioIXkb is being developed. As others have suggested, I use Thonny Python to discover the typos and simple logic/formatting errors in any newly coded Python program. Micro Python uses "board" constructs (on the WioTerminal) which cause syntax errors when running WioTerminal Python programs on the Pi-400. In order to test programs on the "WioTerminal", one cannot use a keyboard/mouse pair, the uJoyStick must be used. There is a way to partially get around this issue. Each program written for the WioTerminal can check the Model of Computer that the Python software is being run on (using the "getDevice()" function. On a Raspberry Pi, the Model can be read from the file /proc/cpuinfo. On the Raspberry Pi-400 the command:
>>> grep "Model" proc\cpuinfo 

returns

"Model         : Raspberry Pi 400 Rev 1.0"

One can create a folder named "proc" on the WioTerminal.  The file below named cpuinfo can be stored in it.

"Model         : SeeedStudio WioTerminal"

A program named grep.py can be created for the WioTerminal. When it runs as grep "Model" proc\cpuinfo
it can return:

"Model         : SeeedStudio WioTerminal"

Programs can use a mechanism based on this concept to use the Keyboard instead of the uJoyStick when running
WioIXkb on a Raspberry Pi instead of on the WioTerminal.  I plan to follow this train of thought in more detail.  
Perhaps typing text into the command line (avoiding the tedious 3 top buttons) is the biggest need (after
coping with the absence of WioTerminal peripherals) for this type of solution during development.

Requirements

MicroPython Code for the 5 button Joystick etc by scruss[deprecated]

Under the following heading, in Source 06, "scruss" says

MicroPython on the Seeed Studio WioTerminal: it works!

Nov 4, 2022 - There are three buttons on top, plus a 5-way joystick on the front. Their logic is inverted, so they read 0 when pressed, 1 when not.

"scruss" has published code for the 5 buttons (joystick) in Github (Source 07)

The author (D @ CC) will test this code.

MicroPython Libraries

machine - functions related to the hardware - class Pin - control I/O pins

At the MicroPython Libraries website, the writing and reading of data to/from pins is described (See Source 10). Some code is also provided. The WioTerminal permits control of the internal electronic perpipherals via the 40 GPIO pins. The uJoyStick (the micro Joystick on the WioTerminal ) consists of 5 simple pushbutton switches that can be read from 5 GPIO pins. This is the documentation for the latest development branch of MicroPython and may refer to features that are not available in released versions.

If you are looking for the documentation (in Source 10) for a specific release, use the drop-down menu on the left and select the desired version.

class Pin - control I/O pins

A pin object is used to control I/O pins (also known as GPIO - general-purpose input/output). Pin objects are commonly associated with a physical pin that can drive an output voltage and read input voltages. The Pin class has methods to set the mode of the pin (IN, OUT, etc) and methods to get and set the digital logic level. For analog control of a pin, see the ADC class.

A pin object is constructed by using an identifier which unambiguously specifies a certain I/O pin. The allowed forms of the identifier and the physical pin that the identifier maps to are port-specific. Possibilities for the identifier are an integer, a string or a tuple with port and pin number.

Usage Model (slightly altered by the author):

#wioButtonDownMP.py
from machine import Pin
import time

print("wioButtonDownMP.py")
print("This program reads all 40 pins and prints out the value read.")

if False :   #disable this code
	# create an output pin on pin #0
	p0 = Pin(0, Pin.OUT)
	
	# set the value low then high
	p0.value(0)
	p0.value(1)
#if end	

for i in range(40) :
	# create an input pin on pin #2, with a pull up resistor
	#p2 = Pin(2, Pin.IN, Pin.PULL_UP)
	# create an input pin on pin #i, with a pull up resistor
	p2 = Pin(i, Pin.IN, Pin.PULL_UP)
	
	# read and print the pin value
	print("pin:",i,p2.value())
#for end

if False :  # disable this code
	# reconfigure pin #0 in input mode with a pull down resistor
	p0.init(p0.IN, p0.PULL_DOWN)
	
	# configure an irq callback
	p0.irq(lambda p:print(p))
# if end

#/wioButtonDownMP.py
The above code is saved as "wioButtonDown.txt" in Source 08. Download it as ".txt", then change the extension to ".py". Then run it on the WioTerminal as main.py .

WioIXkb Command Line Interface : CLI

This CLI uses the 3 top buttons on the WioIXkb because there is no keyboard on the WioTerminal. Most commands on the Command Line are composed of 2 or 3 text phrases separated by spaces. For example, the commands:
grep "Model" /proc/cpuinfo

or

more INFO_UF2.TXT

It is possible to generate such commands using the top 3 push-buttons on the top edge of the WioTerminal. Pressing the first button will scroll through the possible first phrases of the command. Pressing the second button will scroll through the possible second phrases for the command. Pressing the third button will scroll through the possible third phrases. When WioIXkb starts up, the top folder appears on the LCD with the second default command (pgdn) appearing on the CL. The first command (dir) has already been executed with its results showing on the LCD. The second command is "pgdn #dir #begRec#0". The 2 comments on the right side of the CL begins with a "#" and are ignored by the CLI. Pressing the ENTER key (the center key of the uJoyStick) will cause the command on the Command Line (CL) to be executed. Each time the "Enter" key is hit, the information on the LCD screen will scroll down 16 rows as the "pgdn" command is executed.

Minimal set of WioIXkb CLI commands

Version v01.11 consists of a single CLI command
Button 1      Button 2                     Button 3
command       parm1                        parm2   
--------      ------------------           ---------------  
 pgdn      |                             |
Version v02.1 (the first stable version ) consists of two CLI commands. These two commands enable the user to see the content of any file stored on the WioTerminal. Beware: some files may contain characters that might not be displayed correctly on the LCD. Selecting (highlighting by blinking) is not possible in version 02.1 . Viewing files stored in folders (of the WioTerminal) is not possible in version 02.1 . Version 02.1 is a very stable version of the WioIXkb program. Addressing any reported issues related to a stable version will be given priority.
Button 1      Button 2                     Button 3
command       parm1                        parm2   
--------      ------------------           ---------------  
 pgdn      |                             |
 more      |  row[#]                     | 0
           |                             | 1
           |                             | 2
           |                             | 3
           |                             | 4
           |                             | 5
           |                             | 6
           |                             | 7
           |                             | 8
           |                             | 9
           |                             | 10
           |                             | 11
           |                             | 12
           |                             | 13
           |                             | 14
           |                             | 15
Version v03.0 consists of the minimal set of CLI commands shown below.
Button 1      Button 2                     Button 3
command       parm1                        parm2   
--------      ------------------           ---------------  
 pgdn      |                             |
 pgup      |  BlinkBlueLed01.py          | 0
 dir       |  cmdHistoryList             | 1
 more      |  Srow                       | 2
 pyi       |  row[#]                     | 3
 run       |  System_Volume_Information  | 4
           |  wioCmds.txt                | 5
           |  wioHelp.txt                | 6
           |                             | 7
           |                             | 8
           |                             | 9
           |                             | 10
           |                             | 11
           |                             | 12
           |                             | 13
           |                             | 14
           |                             | 15

Note that "more|System_Volume_Information" will attempt to list the rows of text in the file named 
"System_Volume_Information".  If a command containing underscores "_" fails, the WioIXkb program
will replace the underscores with spaces and will then try again before reporting an error.  
Similarly, "run|System_Volume_Information" will attempt to run a WIoIXkb module (function) named 
"def System_Volume_Information()".  Upon failure, all underscores are replaced by spaces, then retried.
The command "more" with no arguments will display wioHelp.txt .  Similarly the command "run" with
no arguments will display "wioCmds.txt" . The command "more|(row)|3" will list the file or program
whose name appears on row 3 of the LCD text.  The command "more|(Srow)" will list the file or 
program that is selected (highlighted by blinking).  The command "more|cmdHistoryList" will list 
all commands executed since the session began. If the command line (CL) is selected (highlighted
by blinking), clicking "SWITCH_UP" (the up switch) and "SWITCH_DOWN" (the down switch) on the 
uJoyStick will scroll through (circle through) the previously executed commands that have been 
executed during the current session.  

When the mainIX.py program runs on the Raspberry Pi to create a new main.py program, it prepends 
"mainNext.py" with the following modules. It prepends all Python functions (with extensions of ".def" 
in the folder named "functionsIX" on the RPi) and copies of all programs with extensions of ".py" in the main folder 
(after converting each program to a improvised function module). In this manner, the main.py program can make use 
of all functions known to mainIX.py and all Python (.py) programs (after attempting to convert each to an 
improvised Python function).
 
These prepends are followed by mainNext.py, to create "main_timestamped.py" , 
eg "main_2023CMar26_1405.py". Upon boot, all of these modules (functions and converted ".py" programs) 
are available to main.py without needing to change main.py. Of course, the user must copy-then-paste 
the new main_timestamped.py as main.py onto the flash drive in the WioTerminal.

Creating the main.py program using mainIX.py

The only Python program that can be run on the WioTerminal is "main.py"; which always starts upon boot-up of the WioTerminal. When user-coded Python functions are placed at the beginning of each program, the program grows in size and complexity called "bloating". An example of such a function is one defined with a "def" statement such as "def isShow(phrase):" ). One solution is to save each such function separately with an extension of ".def" . Then the main program can be saved without bloating (ie without also including the functions that it needs and uses). For example, the isShow function would be saved as "isShow.def". These functions should be located in a folder called "functionsIX" that is located under the current folder on the RPi. But how can suchfunctions be automatically added to a program when needed on the WioTerminal? To do this for the WioTerminal, I use a program called mainIX.py on the RPi

mainIX.py on the RPi

The author has created a "mainIX.py" Python program on the RPi. This very simple program named mainIX.py, finds all files (in the "functionsIX" folder on the RPi) that have an extension of ".def". Then "mainIX.py" concatenates ALL of these functions together, followed by mainNew.py and writes this file out, timestamped, for example as main_2023CMar25_1235.py . This timestamped name is referred to as "main.py" with an IX timestamp . The full list of all of the names of these modules is prepended to the latest IX-timestamped main.py as comment lines at the beginning of the IX-time-stamped main.py program. Finally the user must copy this IX-timestamped program into "main.py" on the RPi. Then the user must copy "main.py" from the RPi to the flash memory (often called the ARDUPY volume) on the WioTerminal.

Often the user will want to compare 2 files, such as 2 IX-timestamped main.py files. The CLI way is to use "diff", the better, GUI way is to use "meld". Both are run in Terminal on the Raspberry Pi. On Pi-400, the author uses the meld program (Source 13) to compare 2 text files. (Meld cannot be run on the WioTerminal.) The "meld" program shows differences visually (image below).

(To enlarge .....Click it)
thumb: meld_shot.jpg

GUI meld (screen shot)

The WioTerminal is now ready to use with this updated main.py program. Simply turn the WioTerminal's Power OFF then ON again. The program named "mainNew.py" (eventually stored as "main.py") will run using those functions (from the "functionsIX" folder) that it needs. The WioTerminal will have access to these functions because they will be part of the code in the "main.py" program that is copied to the WioTerminal. Hopefully, this is a workable alternative to using an "import" mechanism. A major concern is if it will over-tax the memory in the WioTerminal. Time will tell.

Converting a Python program (improvising it) into a WioTerminal function module

A program named anyName.py cannot be simply copied to the WioTerminal and be easily run. The only Python program that will currently (as of 2023CMar26) run on the WioTerminal is the one named "main.py". But a Python program can be "improvised" to run. For example the command "run|BlinkBlueLed_01.py" can use a Python program that has been converted into a function by preceding each row with 4 spaces and by prepending (inserting in front of it) two rows of code and by appending four rows of code containing:
#BlinkBlueLed_01_i():    #improv code
def BlinkBlueLed_01():   #improv code
( original file with all rows prefixed by "    ")
    return True                            #improv code
#def end of BlinkBlueLed_01()              #improv code
#the resulting file can be saved           #improv code
# as "BlinkBlueLed_01_i.py" on the RPi.    #improv code
Note that the name of the new program has a suffix of "_i" on the first and last line immediately above. Use this name when saving the new improvised program on the RPi, but not on the WioTerminal.

Original BlinkBlueLed_01.py program

The "_i" does not appear in the program immediately below.
#BlinkBlueLed_01.py
# for running on WioTerminal using MicroPython
import time
import board
from digitalio import DigitalInOut, Direction

led = DigitalInOut(board.D13)
led.direction = Direction.OUTPUT

while True:          #endless loop begins here
    led.value = True
    print("LED ON")
    time.sleep(1)
    led.value = False
    print("LED OFF")
    time.sleep(1)
#while end
#End of BlinkBlueLed_01.py
BlinkBlueLed_01.py code Improvised to run as a function module
The "_i" is mentioned twice in the code immediately below.
#BlinkBlueLed_01_i():    #improv code
def BlinkBlueLed_01():   #improv code
    #BlinkBlueLed_01.py
    # for running on WioTerminal using MicroPython
    import time
    import board
    from digitalio import DigitalInOut, Direction

    led = DigitalInOut(board.D13)
    led.direction = Direction.OUTPUT

    while True:          #endless loop begins here
        led.value = True
        print("LED ON")
        time.sleep(1)
        led.value = False
        print("LED OFF")
        time.sleep(1)
    #while end
    #End of BlinkBlueLed_01.py
    return True                            #improv code                            
#def end of BlinkBlueLed_01()              #improv code
#the resulting file can be saved           #improv code 
# as "BlinkBlueLed_01_i.py" on the RPi.    #improv code
The "improvised" function code immediately above needs a main.py to invoke it
This main.py code is described below. Originally it is called mainStub.py

This converts the unimprovised Python program into a function in a manner that usually works. The resulting module can be executed as the function named "BlinkBlueLed_01()". The main program only needs to invoke this function in order to run the program in this improvised manner. If the improvised program hangs, power OFF then ON to reBoot the WioTerminal. The mainStub.py program shown below will run the improvised Python program (which was originally named "BlinkBlueLed_01.py" ). It should have been saved (now as a function) as "BlinkBlueLed_01_i.py" [note the "_i.py") followed by the following statements from mainStub.py:

#########################################################################################
# Note: the improvised code (the function defined above with a name ending in "_i.py") 
# must prepend this mainStub.py program
progName="main.py"
# Purpose: to improvise the running of an improvised (ending in "_i.py") program as a function
# By:      D@CC on 2023CMar26
# Source:  http://ephotocaption.com/a/187/187.html
# Note:    prepend "BlinkBlueLed_01_i.py" to this short program

print("begin improvised:",progName)
result = BlinkBlueLed_01()    #invoke the improvised function (Insert the correct name!)
print("end of ", progName)
#mainStub.py end
#save the resulting program as main.py on the RPi
The code immediately below is the complete program that is needed to invoke the improvised function. This is the final program that invokes the improvised function defined in "BlinkBlueLed_01_i.py"including the improvised function code and the mainStub.py that invokes it. Skeptics should copy the exact code below to the WioTerminal. The blue led will start blinking. Note that a second set of improvised code can be added (with a second function call) in order to combine more than 1 Python program in the resulting code named and stored as "main.py" There is one slight problem: in that the original BlinkBLueLed_01.py runs in a endless loop. It is up to the reader to resolve this issue by including a button press to terminate the loop.
#BlinkBlueLed_01_i():    #improv code
def BlinkBlueLed_01():   #improv code
    #BlinkBlueLed_01.py
    # for running on WioTerminal using MicroPython
    import time
    import board
    from digitalio import DigitalInOut, Direction

    led = DigitalInOut(board.D13)
    led.direction = Direction.OUTPUT

    while True:          #endless loop begins here
        led.value = True
        print("LED ON")
        time.sleep(1)
        led.value = False
        print("LED OFF")
        time.sleep(1)
    #while end
    #End of BlinkBlueLed_01.py
    return True                            #improv code                            
#def end of BlinkBlueLed_01()              #improv code
#the resulting file can be saved           #improv code 
# as "BlinkBlueLed_01_i.py" on the RPi.    #improv code
#########################################################################################
# Note: the improvised code (the function defined above with a name ending in "_i.py") 
# must prepend this mainStub.py program
progName="main.py"
# Purpose: to improvise the running of an improvised (ending in "_i.py") program as a function
# By:      D@CC on 2023CMar26
# Source:  http://ephotocaption.com/a/187/187.html
# Note:    prepend "BlinkBlueLed_01_i.py" to this short program

print("begin improvised:",progName)
result = BlinkBlueLed_01()    #invoke the improvised function (Insert the correct name!)
print("end of ", progName)
#mainStub.py end
#save the resulting program as main.py on the RPi
Be sure to save the resulting program as "main.py" not as "mainStub.py" on the RPi.

This cannot be done fully automatically. The user must assign the resulting program the name "main.py" (on the RPi) and copy it to the flash drive on the WioTerminal as "main.py".

The above work should all be done on the RPi. When the main.py program is copied to the WioTerminal, the WioTerminal should reboot and run this new main.py program. If not, Power OFF and ON the WioTerminal.

--------------------------------------------------------------------------------------------------------------------------
  My future WioTerminal Python programs will all be functions called from a main program.
--------------------------------------------------------------------------------------------------------------------------


This is the end of the improvised Python program explanation.

Future List (wioPY.txt) of .py Modules in the /py folder:

Full set of WioIXkb CLI commands

With version 04.1, the following CLI (Command Line Interface) will be possible in WioIXkb. Pressing the top left button will scroll through the following commands for the CL, showing each of the commands below. Similarly the second part of the CL (parm1) is selected using the middle top button. The third part (parm3) is selected using the third button on the top edge. Note that the first scrollable value for Buttons 2 and 3 is blank. The list of Commands has been chosen to resemble similar Linux Terminal commands that are most useful.
Button 1       Button 2               Button 3          Phrase            Synonym
command        parm1                  parm2   
--------       ------------------     ---------------   ----------------  ----------------
 pgdn      |                       |
 cp(fut)   |   commands            |  *.*               commands          txt/wioCmds.txt
 dir       |   functionsIX         |  0                    
 grep      |   INFO_UF2.TXT        |  1
 help      |   list/               |  2
 ls        |   list/keyStrokeList  |  3                 ls                dir
 more      |   list/cmdHistoryList |  4
 pyi       |   list/grepResultList |  5
 select    |   media/uSD/f#        |  6                   
 touch(fut)|   "Model"             |  7
 pgup      |   newFile#            |  8                 newFile#          media/uSD/newFile#
 run       |   proc/               |  9
 #         |   proc/cpuinfo        |  10
           |   py/                 |  11
           |   row[#]              |  12
           |   (Srow)              |  13
           |   (Srow)[n]n=         |  14
           |   (Srow)[n])          |  15
           |   (Srow)[])           |  (cmdHistoryList)  (cmdHistoryList)  list/cmdHistoryList
           |   (Srow)+1)           |  cpuinfo
           |   (Srow)-1)           |  f#(fut)           f#(fut)           media/uSD/f#(fut)
           |   txt/                |  (grepResultList)  (grepResultList)  list/grepResultList      
           |   txt/wioCmdRules.txt |  media/uSD/f#(fut)
           |   txt/wioCmds.txt     |  proc/cpuinfo
           |   txt/wioHelp.txt     |  (Srow)
           |   txt/WioIXkb/        |  (word)
           |   txt/wioKeys.txt     |
           |   txt/wioNumbers.txt  |  
           |   txt/wioWiki.txt     |
           |   txt/wioWords.txt    |
           |   *.uf2               |
           |  (word)               |                    (word)            txt/wioWords.txt
           |  (number)             |                    (number)          txt/wioNumbers.txt
           |  *(fut)               |

Valid Combinations of the 3 Buttons

Many of the combinations of "command", "parm1" and "parm2" will be valid commands. However, before it can be used, each combination must be built into WioIXkb. (A full uptodated list of all the currently usable WioIXkb commands can be seen by using the command "wioCmds".) The following combinations are all possible in the first build of WioIXkb v04.0:
command parm1          parm2       result
---------------------------------- --------------------------------------------------------------------
dir                                displays the contents of the top folder of the "WioTerminal"
                                           This will include folder names and file names
dir     |proc/                     displays the proc/ folder of the "WioTerminal" which contains the file "cpuinfo"
dir     |py/                       displays the py folder of the "WioTerminal".  All programs in this
                                           folder will have been included as improvised py programs
                                           (converted to functions to run on the WioTerminal)
dir     |WioIXkb/                  displays the \WioIXkb folder of the "WioTerminal"
dir     |#            |(word)      lists the directory and adds a word from wioWords.txt [here, the 
                                            (word) is just a comment to make the command history 
                                            more easily understood.]
grep    |"Model"      |proc/cpuinfo displays the Model of the device which is "SeeedStudio WioTerminal"
grep    |(word)                    this is an intensive search for the selected word in every file
                                            accessible by WioIXkb. It is a 1-step or a 2-step process.
                                            The first step is to hit Enter once which will display
                                            the list of 1000 English words (wioWords.txt) in the LCD.
                                            These words are listed 16 per screenfull.  CLicking on the 
                                            UP and DOWN positions of the uJoyStick will select (highlight
                                            by blinking) one of the rows in the LCD. Clicking DOWN on
                                            the bottom row scrolls down one row and by selecting the next
                                            row down.  Clicking UP at the top of the screen does the
                                            same thing in the opposite direction.  Hitting Enter is
                                            how to select the highlighted word to be searched for.
                                            Presume that the highlighted word is "pear". After selecting
                                            (highlighting by blinking) "pear", then hitting Enter, the
                                            word "pear" will appear as parm1 in the command line enclosed
                                            in double quotes. Also the LCD will show the contents of 
                                            the top folder (the result of the dir command. without
                                            any row being highlighted. ow the user has two options: 
                                            
                                              1 search everywhere on the WioTerminal (To do this, hit "Enter" 
                                            again without selecting a row nor clicking button 3. This
                                            executes the command line with an empty parm3.  The results
                                            of this search will be written to grepResultList (overwriting  
                                            its contents. This make take a long time but  
                                            can be interrupted by hitting Power-OFF-then-ON.  The first 
                                            files to be searched are those currently listed on the LCD  
                                            of the WioTerminal. The output will be written to an 
                                            internal list called (grepResultList) which will be displayed on the
                                            LCD after the search is compete.  The whole list of rows of
                                            text where each row contains the selected word.  Nothing 
                                            will be displayed until the search is complete. (So take a break!!)
                                                 or
                                              2 select a single file to be searched (for the word "pear")
                                            To do this second option, use the rightmost top button to
                                            select a phrase for parm2 or select a row on the LCD screen.  
                                            The current contents of any internal List can be searched
                                            by selecting them using button 3. Three very interesting internal
                                            Lists to search are (cmdHistoryList), (grepRersultList) and
                                            (keyStrokeList).  The (keyStrokeList) contains the (cmdHistoryList)
                                            plus the intervening keyStrokes entered by the use. It is
                                            a very effective tool used when debugging WioIXkb. The net
                                            result is that one file or internal List can be selected to
                                            be searched using button 3. Hitting Enter will cause the 
                                            serarch to happen.  The result will be written to the internal
                                            List named "grepResultList (overwriting its previous contents"
                                             
grep    |(wioWords.txt) |(Srow)    searches the selected (highlighted by blinking) file for a single word.
                                            This does the same search as Option 2 (above). This command
                                            requires a 2-step approval process. The single word to be
                                            searched for is selected from the file named "wioWords.txt" 
                                            [aka (word) ]. The file named "wioWords.txt" is a list of the 
                                            1000 most frequently used words in the English language. The 
                                            file in which the word is searched (grepped) is the selected 
                                            (highlighted by blinking) file (ie (Srow). The user must hit
                                            the Enter button a first time to do the word lookup. After the
                                            word is selected, the new command will be displayed showing
                                            the revised command including the selected word.  The user 
                                            must select parm2 using button 3 as described in option 2 above.
                                            The results of this search (this grep) are stored in the
                                            internal List named grepResultList of which the first page will
                                            appear in the 16 row LCD
grep    |(word)       |(Srow)      is the same as the previous example
grep    |(word)       |cmdHistoryList  searches the cmdHistory file slooking for a single word selected
                                            from the wioWords.txt file.  Note that all 3 possible choices
                                            of any of the three parts that make up a command are included 
                                            in the wioWords.txt .  This permits the look up of the
                                            WIoIXkb commands in the wioHelp.txt file.  A version of these 
                                            command descriptions will appear in the wioHelp.txt file.
                                            The word returned will be enclosed in a pair of double quotes.

help                               displays the WioIXkb help file
help    |commands                  is the same as the previous example 
help    |WioIXkb                   is the same as the previous example 
help    |wioHelp.txt               is the same as the previous example

more    |cmdHistory                lists the history of all commands executed during this session of WioIXkb.
more    |(Srow)                    displays the currently selected (highlighted by blinking) row of the current 
                                           display when the Wio Terminal starts, the WioIXkb will select the 
                                           first file which (in the image above) is "boot_out.txt".  When (Srow) 
                                           is selected and the Enter Button is hit, the CLI will refresh the command 
                                           line to show the resulting command which will be "more boot_out.txt"
                                           The CL is executed by hitting the "Enter" button (which is the pressing
                                           the center of the uJoyStick). Note that the "Enter" Button must be hit twice.
more    |(row)         |1          is the same as the previous example if the screen is that in the left image above
more    |wioCmds.txt               is the same as the previous example 
more    |wioHelp.txt               is the same as the previous example

pgdn                               scrolls down to the next page of the current display
                                           with the top row "selected" (highlighted by blinking)
pgdn    |#             |dir        is the same as the previous example ( # denotes any comment that follows)
pgup                               scrolls to the previous page of the current display
                                           with the top row "selected" (highlighted by blinking)

py(fut) |(Srow)                    runs the selected (highlighted by blinking) Python program on a non-standalone 
                                           WioTerminal. This is only done when the WioIXkb is plugged into
                                           a computer such as a RPi or a laptop.  The selected
                                           Python program is copied into a new file mainNext.py.  Then
                                           the user (not WioIXkb) must copy-then-paste mainNext.py into
                                           main.py in the top folder of the WioTerminal. Before
                                           doing this, the main.py file must be deleted from the WioTerminal.
pyi    |row[#]         |2         runs a Python program that has been previously improvised as a 
                                            function in main.py (named "mainIX.py" on the RPi) .  
                                            The Python progam that will be run as a function is 
                                            the program whose name is currently on row 2 of the text display on
                                            the LCD screen of the WioTerminal.  The list of "improvised"
                                            py programs can be seen in wioPY.txt .
pyi    |(Srow)                    runs a ".py" program in improvised mode on the WioTerminal.  These
                                           ".py" programs must be loaded onto the WioTermninal before
                                           the mainIX.py program is run on the RPi.  The mainIX.py program
                                           creates the main.py to be copied to the WioTerminal

run    |(Srow)[n]n=    |3         runs the command in row 3 of the selected
                                           (highlighted by blinking) file. The new command will appear on
                                           the CL. The user must must hit the "Enter" button again to 
                                           execute it. Note that the "Enter" Button must be hit twice.
run    |(Srow[n])      |3         is the same as the previous example         
run    |(Srow)         |3         is the same as the previous example
run    |(Srow[])       |3         is the same as the previous example  
run    |row[#]         |5         runs the module with the same name as the file in row 5 of 
                                           the LCD even though row 5 might not be currently
                                           selected (highLighted by blinking).  The name of the command
                                           will appear in the "revised" CL (Command Line) as a "suggested"
                                           command. The user must hit Enter to actually execution the
                                           revised command. 

select  |(Srow+1)                 selects (ie highLightsby blinking) only the next lower row (if any)
                                           of the LCD. The selected (highLighted) row is blinking blank
                                           ( then full). When "full" the selected row is visible. When 
                                           "empty" the selected row is all blanks.
select  |(Srow-1)                 selects (ie highlights by blinking) the previous row (if any)

touch   |newFile#                 creates a new file with a unique name on the uSD card in the SD card 
                                           slot. The unique name is automatically created by selecting the 
                                           next available 3 digit number to replace "#". In standalone  
                                           mode, the WioTerminal never allows the creation of any files 
                                           on its flash drive.  Once this new file is written out, the
                                           WioTerminal should be connected to a computer such as an RPi.
                                           When attached to a computer, the file can be given a more-
                                           meaningful name.
touch   |media/uSD/newFile#       is the same as the previous example

wioCmds                           lists (alphabetically) all WioIXkb modules that can curently be run eg:
                                           "grep|"Model"|proc/cpuinfo"
                                           "help|WioIXkb" 
                                           "more cmdHistory"
                                           "more|Srow"   
                                           "run|(Srow)"
                                           "pgdn|#dir"
                                           "select|(Srow+1)>" 
                                            etc
#       |(word)    |(word)        is a command can be a list of words preceded by a "#" (ie a comment command)
Note 1: the "run (row) 3" command cannot run a Python program unless that program has been improvised (converted into a function module) and was placed earlier within WioIXkb and saved as "main.py".
Note 2: the uJoyStick "Up" button scrolls up and displays on the CL the previous command that was run.
WioIXkb contains a list called cmdHistoryList which is a list of all the commands run during this session
Note 3: the uJoyStick "Down" button scrolls down and displays on the CL the next command that was run
from the cmdHistoryList.
Note 4: the uJoyStick "Center" button peforms like an "Enter key" by executing the command that is visible on the command line. (Note that Srow measns "Selected row". An exception to this is when (Srow) [or (Srow+1) or (Srow-1) or (Srow[n]) or (row) or (word) ] appears in the Command Line (CL). In these cases, the selected (highlighted by blinking) row is looked up and is displayed in the CL awaiting the user to hit the "Enter" button a second time to confirm the renewed CL and execute it. An invalid command line (CL) results in the following error message:

     ERROR IX001: WioIXkb invalid CL (Command Line)

being displayed.
Note 5: Running WioIXkb on a standalone WioTerminal is a very stable environment that cannot be mutilated by a user. This is because such a user is not permitted to write anything to the internal flash drive of the WioTerminal (while not connected to an external computer), making it impossible to corrupt.) Of course, errors coded into WioIXkb will remain until they are corrected in a future version.
Note 6: Occasionally, a command might be ambiguous. For example, "more cmdHistoryList" is intended to display the history of all commands executed during this session. However, if a folder exists named "cmdHistoryList", an ambiguous command is the result. The WioIXkb program will only execute the first command found in the command list named wioCmds.txt. The commands comprised totally of words selected using the 3 top buttons will be preferred and will be given preference over commands using phrases found in folders on the WioTerminal flash drive. These preferred commands are all listed in the file named "wioCmds.txt"
Note 7: Some commands can contain underscores "_". If a command fails and it contains one or more underscores, the command will be executed a second time (including the "|" that separates the parts of the command) but with each underscore replaced by a single space. In this manner it is possible to execute a command that contains spaces within the phrases. An example is to list the WioTerminal file named "System Volume Information". The way to do this is to execute "more System_Volume_Information". WioIXkb will find that this command fails, but after automatically converting each "_" to a " ", the command will succeed.
Note 8: When the WioIXkb program starts, the CL on the top row will be selected (highlighted by blinking). Alternatively, the user can move the selected row by using the "SWITCH_DOWN" (the down switch) and "SWITCH_UP" (the up switch) on the uJoyStick one or more times.
Note 9: In this documentation, commands are sometimes shown with a "|" separating the 3 parts of a command. This is done merely to show a command in a more compact form. The user will never need to insert any "|" in a command for it to be executed. In fact, it would be very difficult for a user to insert a "|".
Note 10: The author intends to allow parm2 to be more than one word, permitting the user to select multiple words to compose more meaningful comments for some commands.
Note 11: The full command history (cmdHistoryList) and the most recent (grepResultList) can be wrriten to a uSD card to document any WioIXkb session. This is the only way to save the results of a WioIXkb session. It is impossible to write anything to the WioTerminal card when it is run in stand-alone mode.

WioIXkb Functions used internally when coding WioIXkb

These function names are only used by programmers who are modifying the code that makes up WioIXkb. The main functions (coded in MicroPython specifically for WioIXkb) are:

WioIXkb Error and Warning Messages

WioIXkb does not allow users to use a keyboard. Therefor not many errors will occur, only the following

ERROR   IX001: WioIXkb invalid CL (Command Line)
WARNING IX003: this device is not a WioTerminal 

Future Applications for the WioIXkb

If the author finds time, he plans on coding the following applications for the WioIXkb:

This program, WioIXkb.py, by D@CC, is a work-in-progress as of 2023CMar30.

This article, by D@CC, is of course, a work-in-progress as of 2023CMar30.

(To enlarge .....Click it)
thumb: IMG_5083.jpg

my software filing cabinet (thanks to Myrle)

Myrle's 3D printer model was made by PRUSA (Source 16)

End of Article (Sources Follow)

(Video Source 02 Time 10:08 min plus ads)

Recommended 10 Greatest Scientific Discoveries of all time

10 Heliocentrism
 9 Human Genome Project 
 8 The God Particle (Higgs Boson Particle)
 7 The Theory of Relativity
 6 Quantum Mechanics
 5 The Big Bang
 4 Evolution
 3 Germs
 2 Penicillin
 1 Vaccines

Sources

Video Sources

Video Source V187:01:www Exploring the Wio Terminal ( 1:14 min) by Seeed Studio in 2021
Video Source V187:02:www Top 10 Greatest Scientific Discoveries of All Time _ Watch (www is ok) by Daily Motion on 2023CMar30

Web Sources

Web Source S187:01:www Pi: Wio Terminal for Raspberry Pi (186.html) by D@CC of ICH180RR on 2023CMar21
Web Source S187:02:www WioIXkb.py v01.0 (as a .txt file) by D@CC of ICH180RR on 2023CMar21
Web Source S187:03:www WioIXkb Information (WioWiki.txt) by D@CC of ICH180RR on 2023CMar21
Web Source S186:04:www (nla) ArduPy_wio_terminal_lastest.uf2 By Seeed Studio on 2020MDec
Web Source S186:05:www Adafruit Circuit Python for Wio Terminal v 8.0.4 uf2 By Adafruit on 2023
Web Source S186:06:www Micro Python on the . . . . Wio Terminal: It works blog by scruss in Nov 4 2022
Web Source S186:07:www WioTerminal-MicroPython/Wio-Terminal-Buttons.py In Github by scruss in Nov 1 2022
Web Source S186:08:www wioButtonDown.py (saved as wioButtonDown.txt) by D@CC of ICH180RR on 2023CMar23
Web Source S186:09:www class Signal -control and sense external I/O devices in Micro Python Libraries on 2023CMar23
Web Source S186:10:www class Pin - control I/O pins in Micro Python Libraries on 2023CMar23
Web Source S186:11:www Joystick Issue addressed using Circuit Python By bhclowers in Nov 2020
Web Source S187:12:www WioIXkb.py v01.11 (as a .txt file) by D@CC of ICH180RR on 2023CMar24
Web Source S186:13:www GUI meld is better than CLI diff By Ben Nuttall in March 23, 2020
Web Source S187:14:www Pi: MMBasic driving the Maker Pi Pico: SDcard etc (166.html) by D@CC of ICH180RR on 202AJan11
Web Source S187:15:www WioIXkb command Rules by D@CCof ICH180RR on 2023CMar28
Web Source S187:16:www Myrle's 3D printer model (by PRUSA) by Myrle on 2023CMar29
Web Source S187:17:www [3D] printable model 187125-phone-stand by PlatinumStars on 2022AJan25
Web Source S187:18:www wioCmdEqual.txt by D@CC of ICH180RR on 2023CMar30

WebMaster: Ye Old King Cole

Click here to return to ePC Articles by Old King Cole

Date Written : 2023 C Mar 20
Last Updated: 2023 J Oct 111

Stored in E:\E\2022\DevE\MyPagesE\Globat\ePhotoCaption.com\a\187\187.html
Backed up as 187_2023CMar22.html
Backed up as 187_2023CMar26.html
Backed up as 187_2023CMar30.html

All rights reserved by (c) ICH180RR

Font: Courier New 10 (monospaced)
/187.html