177 Pi: Pix - Interactive Ascii Protocol for Pi Control of an RP2040 (177.html)

Pi: Pix - Interactive Ascii Protocol for Pi Control of an RP2040 (177.html)

KeyWords: Pix Interactive "Ascii Protocol" "Pico Control" TINY2040 MakerPiPico PixRead PixWrite VoltsMax3v3, VoltsMax010 VoltsMax100 TempC Model.txt SN.txt Unary "Pix Protocol" KY-18 KY-18Lum "Arduino Kit" Cytron Pimoroni photo-resistor 2040 "Pico 2040" "pktix for pico" pktix "pico pktix" "pktix protocol" "pktix packet protocol" ICH180RR "pktix packets" minicom PuTTY 9600 N81 TINIESTBIT "BOOT button" GP1 RX0 IX pix_pico.py pix_pi.py

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

IX or (IX by DC) or "|><"

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

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

PiWithPico

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

TINY2040 Top View

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

Pi with Maker Pi Pico

There are three popular versions of boards using the RP2040 chip (that costs US$1.00. The two shown above top are the Raspberry Pico and the Pimoroni TINY2040. The Raspberry Pi connected to the Maker Pi Pico by Cytron is shown below them. Much more is written about the Maker Pi Pico in Source 04.

Introduction

******************* WARNING: As of 2023JOct10, this code has not yet been written. ****************

This article describes an ascii (Source 08) protocol (called the Pix Protocol) that can be used so that a Raspberry Pi (Linux or any Mac or PC computer) can make use of an attached Pi Pico and any of the sensors or actuators (controllers) connected to the Pico. The Pix protocal can be used without any other special software. However, such usage has speed limitations, 9600 bps is often recommended. Much faster speeds can be accomplished using the pktix communications protocol which is described later in this article.

The Pix protocol can be used to send command phrases to the Pico which is powered by a Raspberry RP2040 processor. The Pico then performs the command and returns a reply to the computer that sent the command. (In some cases, it is necessary to prefix each Pix command with the space character.) Many commands are supported by the Pix protocol. For example, see the following commands:

COMMAND TYPE ID F_CONVERT VALUE PREVIOUS 1 Command Sent: PixRead ,ADC ,1 ,Unary Reply : value ,ADC ,1 ,Unary ,4032 2 Command Sent: PixWrite ,GP ,5 ,Unary ,1 Reply : written ,GP ,5 ,Unary ,1 3 Command Sent: PixRead ,ADC ,1 ,VoltsMax3v3 Reply : value ,ADC ,1 ,VoltsMax3v3,3.29 4 Command Sent: PixWrite ,GP ,99 ,Unary ,1 Reply : error ,GP ,99 ,Unary ,1 5 Command Sent: PixRead ,MODEL ,1 ,Unary Reply : value ,MODEL ,1 ,Unary ,TINY2040 6 Command Sent: PixWrite ,MODEL ,1 ,Unary ,TINY2040 Reply : written ,MODEL ,1 ,Unary ,TINY2040 ,Unknown 7 Command Sent: PixRead ,SN ,1 ,Unary Reply : value ,SN ,1 ,Unary ,None 8 Command Sent: BPS ,UART ,0 ,Unary ,9600 Reply : value ,UART ,0 ,Unary ,9600 ,300 9 Command Sent: HELP ,PIX ,0 ,Unary Reply : value ,PIX ,0 ,Unary ,e.g. BPS UART 0 Unary 9600 10 Command Sent: PIX ,HELP ,0 ,Unary Reply : value ,HELP ,0 ,Unary ,e.g. BPS UART 0 Unary 9600 11 Command Sent: PKTIX ,DOCS ,0 ,Unary Reply : value ,DOCS ,0 ,Unary ,ePhotoCaption.com/a/177/177.html 12 Command Sent: DOCS ,PKTIX ,0 ,Unary Reply : value ,PKTIX ,0 ,Unary ,ePhotoCaption.com/a/177/177.html 13 Command Sent: LIST ,COMMANDS ,0 ,Unary Reply : value ,COMMANDS ,0 ,Unary ,PixRead PizWrite BPS PIX PKTIX LIST READFILE RUN etc 14 Command Sent: READFILE ,EXAMPLES ,0 ,Unary Reply : value ,EXAMPLES ,0 ,Unary ,list of examples (14) follow 15 Command Sent: RUN ,hello ,0 ,Unary Reply : value ,hello ,0 ,Unary ,Hello World 16 Command Sent: HELLO ,hello ,0 ,Unary Reply : value ,hello ,0 ,Unary ,Hello World 17 Command Sent: RUN ,environ ,0 ,Unary Reply : value ,environ ,0 ,Unary ,model: Pico RP2040 18 Command Sent: SET ,EOL ,0 ,Unary ,IOS Reply : value ,EOL ,0 ,Unary ,IOS ,LINUX 19 Command Sent: EOL ,EOL ,0 ,Unary ,T Reply : value ,EOL ,0 ,Unary ,IOS ,LINUX

This protocol is part of the routine named Pix_pico.py which runs in the Pico. The protocol in the Raspberry Pi is part of the routine named Pix_pi.py which runs in the Raspberry Pi. The Pico can be controlled interactively in real time by simply sending the above command to the Pico via the serial port of the Pico. The reply will be sent back to the serial port via the USB connector on the Pico. Note that the command and the reply are composed of comma-delimited ascii text fields (each field is 11 characters wide) followed by a LF. [Note that 11 characters can store the highest signed 4 byte integer which is -2147483648]. Early versions of the Pix_pico.py software will use this format. Eventually, all space characters in the command and the reply can and will be ignored. This ultra-simple ascii communication protocol permits any modern computer to control the Pico. These routines will be tested on the Raspberry Pi using the Thonny python software language. One of the secondary routines to be developed will be the Command "PixInstall" which will download to the Pico various modules of the current version of the Pix software from the Raspberry Pi.

In future, the F_CONVERT (conversion function) field will permit the value sent or received to be modified before being used or reported. For example, if an ADC is used to measure the ambient light using the KY-18 photo-resistor in the Arduino kit (Source 3), the function KY-18Lum can convert the reading to the correct value so that the number in the displayed reply will be the amount of ambient light in lumens. The function named Unary, will always display the reply without converting the value at all. If the F_CONVERT field does not exist or contains spaces, the function "Unary" will be understood. If the required convert functions are too complicated, they will need to be performed in the controlling computer (e.g. the Raspberry Pi) not in the Pix routines.

In this Pix suite of programs, it is the intention of the author to provide software that will be compatible with the Raspberry Pico, the Maker series of Pico boards sold by Cytron (Source 1) and the TINY2040 sold by Pimoroni (Source 2). It is difficult to discern, but between the two buttons on the TINY2040, there is a tri-color LED that can be programmed by the user. One of the two buttons is a (Power) Reset button. The other button (BOOT) can be read by the user. The Maker Pico also has a similar tri-color LED, in addition to other devices. It will be the responsibility of the Raspberry Pi to add any time stamps and/or to log the results. The Pico will solely be used as an attached real-time set of sensors and actuators (controls) that are attached to the Raspberry Pi.

The video by LearnElectronics in Video Source 1 shows how the Pico can be used to blink the LED on the Pico. The second video reads the temperature sensor on the Pico.

Other Commands

The second command shown above is a simple write command. It will set the value of GPIO5 to 1 (which is High). The Reply confirms that the command was a valid command and that the value has been set to High. If this command is sent to the Tiny2040, GP5 must be used to designate pin D5. To ensure common names across the different models of devices, the pin numbers specified are the logical pin numbers, not the physical pin numbers.

The third command shown above is a variant of the first command. It returns the value (in volts) by using the function VoltsMax3v3 that is measured by ADC1. More is said about F_CONVERT in the next section. To measure voltages higher than 3v3, a resistor ladder must be attached to the Pico. If such a resistor ladder divides the voltage by 100, a conversion function VoltsMax100 should be used.

The fourth command shown above is a variant of the second command. It returns an error because pin GP99 does not exist. If a number needs to be returned to specify a specific error code, the error number will appear in the VALUE field. If the model is unknown, then a Raspberry Pico is presumed. If a TINY2040 is being used and the "Model.txt" file contains "TINY2040", then the valid pin numbers of the TINY2040 will be presumed when identifying errors.

The fifth command shown above is a variant of the first command. It returns a character string that identifies the model of Pico board. In this case the type of Pico board is the TINY2040 by Pimoroni. If a Raspberry Pico is being used, the model will be "Pico RP2040". If the type of board cannot be identified from the hardware, it should be written in the text file "Model.txt". The contents of the "Model.txt" file will take precedence, even if the model can be discovered from the hardware. If neither definition of the model exists, the string "Unknown" will be returned. If a Cytron Maker Pi Pico is being used, the "Model.txt" file should contain "MakerPiPico". If a TINY2040 is being used, the "Model.txt" file should contain "TINY2040".

The sixth command shown above is a variant of the second command. It will write the text "TINY2040" into the text file "Model.txt" on the RP2040, if this is possible. It is possible to write "TINY2040" into the "Model.txt" file on a pico (which is not a TINY2040). The user is responsible for any issues resulting from writing a wrong model name into the "Model.txt" file. This is permitted so that users can test the compatibility of software routines across different models using the Raspberry RP2040 chip.

The seventh command shown above is another variant of the first command. It returns a character string that identifies the Serial Number of Pico board. If the Serial Number of the board cannot be identified by examining the hardware, it should be written in the text file "SN.txt". The contents of the "SN.txt" file will take precedence, even if the SN can be discovered from the hardware. If neither definition of the SN exists, the string "Unknown" will be returned as the SN value.

The eighth command shown above is the very first command that the pix software should send or receive. The "short" version of this command is "BPS" which is short for the full comamnd 8 shown above. When the receiver detects the command "BPS" (or any invalid command), it should set the bps (Bit Per Second i.e. baud) rate of the uart on the pico (that is communicating with the Pi coomputer) to 9600 bps. The reply should show the value of the bps rate that the receiver was previously using. This will permit the pi computer to be reset to the previous bps rate, if the invalid command (that was interpreted to be a BPS command) was indeed not a bps problem.

The ninth and tenth commands shown above function identically. They help the user use the PIX commands, by returning an example of the format of the PIX command. The "short" versions of this command are "HELP" or "PIX". Both of these help commands return "e.g. BPS,UART,0,Unary,9600" which is an example of using the PIX command line.

The eleventh and twelfth commands shown above provide a link to this web page. The "short" versions of this command are "PKTIX" or "DOCS".

The thirteen command shown above lists the various commands that every Pix system should provide for the Pico processor. The "short" version of this command is "LIST".

The fourteenth command shown above lists all of the examples shown above. The "short" version of this command is "READFILE". This is the first main command that provides a multi-line reply.

The fifteenth and sixteenth commands shown above run the program hello_pico.py which merely replies "Hello World". The "short" version of this command is "HELLO".

The seventeenth command shown above lists the environment of the pico. It runs the program named "environ_pico.py. The "short" version of this command is "RUN". It is similar to the Environ.sh program (written by the author) for the Raspberry Pi. The reply is a complete mulit-line listing of the known environment on the pico computer, beginnning with the model of the Pico.

The eighteenth and nineteenth command shown above set the EOL to be comptatible with a controlling computer. The eighteenth command makes Pix compatible with a controlling computer that is running the Apple IOS. The "short" version of this command is "EOL" which is the nineteenth command. The nineteenth command toggles the EOL between all of its values which are currently (as of 2022) Linux, IOS and Windows. The reply is the previous setting of the EOL on the Pico. Note that an "extra" LF is presumed to have been sent whenever Pix receives a "short" EOL command. And an"extra" CR is sent before each reply to an EOL command. This facilitates the initial communication with an IOS user on the controlling computer.

Short Default Commands For Testing Purposes

These default commands have been selected because they require no physical external devices to be connected to any model of the 2040. The most simple command to send (that writes something) is "PixWrite". It will toggle the LED from a Off to On or vice-versa. The Led is the default because it exists on the Pico, the Maker Pi Pico and on the TINY2040. The most current previous value set on each pin is stored in the Pix_pico.py routine on the Pico.

Tri-Color LED Control in the Pix ID field
"pin"     Pix Name     Color
GP18      R-LED        Red
GP19      G-LED        Green
GP20      B-LED        Blue

The above table shows the names of the internal logical pins that must be referenced to display each color. There are no equivalent external pins to these 3 pins. Unfortunately, the TINY2040 pins have been defined with active-low logic which is opposite to the logic of the green LED on the Pico. If a TINY2040 is the model specified, the Pix software will automatically use the F_CONVERT function named "Invert", so that the G-LED command for a TINY2040 will have the same effect as the G-LED command for a Pico. Note that for the Pix software, the "Green" pin can be referenced using any of the three names: GP19, G-LED or LED. There is a Tri-Color LED on the Maker Pi Pico board, but it is controlled differently. The Pix software will (in a future version) turn on the correct color if the Pix Name is specified for a model of "MakerPiPico". Various intensities of each color can be produced. But such intensity control will not be available in early versions of the Pix software.

When the value of "T" is sent to an output pin, it is a signal to toggle the output of the pin. The reply will be the value of the LED that was in the LED prior the writing to the LED. Reading the value of the LED will simply return a "1" if the LED is currently Lit (or "0" if not lit). If the LED is read prior to it being written, it will be reported as being 0 (not lit) even though its true value is unknown. For Tri-color LEDs, the previous value of the Tri-Color will be returned in reply to a PixRead LED command in a similar manner to how a non-Tri-Color LED is reported. To be perfectly clear, the short command "PixWrite" is equivalent to:

                 COMMAND   TYPE        ID          F_CONVERT   VALUE

   Command Sent: PixWrite ,LED        ,G-LED      ,Unary      ,T
   Reply       : written  ,LED        ,G-LED      ,Unary      ,1

It might seem strange that the prior state of the LED is reported in the reply to the PixWrite LED command, but, in fact the value of the LED prior to it being "written" is what is indicated in the reply. It would provide no new information if the "new" value of the LED were returned. Because the previous value of the LED is available, it is returned in the reply.

The most simple command to send (that reads something) is "PixRead". It will read the temperature in the Pico chip, convert it to Centigrade (Celsius) and return the value. ADC4, is the default because it exists on the Pico, the Maker Pi Pico and on the TINY2040. To be perfectly clear, the short command "PixRead" is equivalent to:

                 COMMAND   TYPE        ID          F_CONVERT   VALUE

   Command Sent: PixRead  ,ADC        ,4          ,TempC
   Reply       : value    ,ADC        ,4          ,TempC      ,16.4

There are 4 ADC devices in the Pico 2040 but only 3 of them are externally usable, referenced as ADC0, ADC1 and ADC2. Nevertheless, the internal chip temperature sensor is referenced as ADC4. ADC3 is not defined for the Pico, perhaps because there is no physical ADC3 pin. The TINY2040 has 4 external physical pins: ADC0, ADC1, ADC2 and ADC3. The Pico can read the ADC_REF from physical pin 35. The TINY2040 does not have an equivalent pin to the ADC_REF.

Differences Between the Pico and the TINY2040

Of course, there are less pins on the TINY2040. The TINY2040 is slightly more modern (having been released in 2022) in that it has a USB-C connector instead of the soon-to-be-deprecated USB connector on the Pico. This means that a different cable is needed between the comtrolling computer (eg Raspberry Pi) and the TINY2040. The Tri-Color LED on the TINY2040 is controlled by 3 pins (R, G and B) that are Active Low compared to the Green LED that is active High on the Pico. For this reason, the TINY2040 should use the Invert function which gives opposite results to the Unary function on both the Pico and the TINY2040. The additional RESET button on the TINY2040 will save wear and tear on the USB connector. As mentioned earlier, the TINY2040 had one more physical ADC device connected to an external pin. Two versions of the TINY2040 are available: one with 2MB of RAM, the other with 8MB of RAM. The BOOT-Select Button can be used as a button by the user while the TINY2040 is running. The author has not yet experimented to discover if the chip temperature in the TINY2040 can be referenced using ADC4. The TINY2040 does not have a physical pin labelled ADC_REF, so the results of trying to read ADC_REF are unknown.

Pix protocol and pktix communications

The Pix protocol is expected to be used between a Raspberry Pi and an RP2040 pico microcomputer. It is expected that the Pix protocol in simple systems will be used as an ascii command text stream. But more complex systems will use the Pix protocol sent within a pktix packet system. These more complex systems using pktix will permit the transfer of commands, responses, source code, media (eg jpg, wav and mp3 files), data files and data streams. Even more complex systems will include error detection, acknowledgement and error correction. My pktix packet standard is described later in this article.

The first version of the Pix software is version 0 which contains very limited functionality. It responds to only one "short" command: BPS (or " BPS" which is preceeded by a space). Note that "BPS" (or " BPS" containing an initial space) will set the speed to 9600 bps and the byte structure to N81. If the first character received is SOM, an error message will occur reporting that pktix protocol cannot be used in version 0 of Pix. In version 0 of Pix, if the first character received is not a space (" ", 0x40) nor SOM,the error message sent as a reply is "Pix ERROR: no space prefix at 9600 bps N81 *********555555555" (TO VERIFY) with a 2 second quiet time between the N81 and the first asterisk. (In fact The 9 asterisks and nine 5s are sent to allow the a person with a data analyser or oscilloscope to detect the speed. The specific characters (asterisk and 5) are chosen because they have alternating 0's and 1's in their ascii definition. Nine of each are sent because the pktix protocol is named "packet-9". It is the intention of the author to create a pico program that will "listen to" an incoming data stream, measure the first 20 data transitions and report the shortest time between any of the bit state transitions. This program will be invoked on a TINY2040 pico when the BOOT button is depressed. This program will be called "tiniestbit_pico.py" and will be invoked using the Pix command "TINIESTBIT" which will monitor the GP1 pin (RX0) on the TINY2040. Some smart VT100 emulators (e.g. minicom in Source 09 or PuTTY) which run on the controlling computer have the capability of selecting between different common transmitting speeds in bits per second, bps (baud). The most standard speed is 9600 bps with a byte structure of N81.

The author has had good experiences using the minicom program to communicate with asynchronous serial devices such as the RP2040. To install minicom (Source 09) on a Raspberry Pi, use the following terminal command:

sudo apt-get install minicom

More RP2040 Pico Programs

Source 05 contains many routines recently written (modified or copied) for use on the RP2040 by the author. These routines were developed on RP2040 pico (SN . . . . 4f31) using my MicroSDRam card with volume # Fla53S032G. Note that Source 05 is a zipped file (using 7Zip). It will be necessary to unzip its contents once they are downloaded to the Raspberry Pi. Each routine usually explores one of the features of the Pico RP2040. These routines have been developed or tested in the MicroPython language using the Thonny (python) software that offers a special software development environment. This software environmentt bridges the "gap" between the Raspberry Pi and the RP2040 pico. A list of these pico routines is provided below. Most of these routines have been completely tested. The name of those that have only been partially tested are preceded by "X " in the list. Two routines are relatively complex: textpack and Packet Communication. They are described in more detail under these 2 headings following the list of pico routines:

List of Pico Routines

Pico Software on pico 4f31
as of 2022 E May 30
by D@CC
on Fla53S032G

Routine             Function       Description
******************  *************  ***************************************
1Char.py            bChar()        Converts b'w' to "w"
adcValue.py                        Prints adc value & voltage on pico ADC0
BoardId.py                         X reads Board ID
deviceReset_pico.py                Blinks then Resets all pins as Inputs
f3.py               f3()           format any number for printing
fadeLed_pico.py                    Fades the pico green LED using PWM
maker-pi-pico-rgb-led_pico.py      maker board demo program
intRed_pico.py                     drives Green LED and button 21
mid.py                             X converts any number to complex format
mod5.py                            X first MicroPython program 
mod8.py             import mod6    first MicroPython program
mpy_uart_pico.py uart.read         read/write using pico uart
parseComplex.py                    converts a complex number
picoButton_pico.py                 reads pico Button 22 on Maker board
printPicoUniqueId.py               Prints unique ID (char) of pico
printTImTemp_pico.py               Prints Time and Temperature F of pico
serTxC_pico.py                     X packet transmitter by D@CC
serTxRx_Fast_pico.py               X packet tx / rx by D@CC
signalGenerator_pico.py            hacked signal generator
signalGenerator_w_PotOn1_pico.py   worked with MakPiADC board
squareWave_pico.py                 drives Maker pico buzzer
test_TxH_pico.py                   packet transmitter (reads ADC) by D@CC
test_VSYS_pico.py                  Reads Vbus and Vsys
testButton_pico.py buttonAction()  reads button within T (secs)
testLeds_pico.py                   drives Maker pi (not pico) board
testPlot.py          plot()        tests plotting of a vector
testTxF_pico.py                    tested OK on pico
textpack_py.py                     source module transmitter for pi
tickLed_pi.py                      blinks the pi led

                     saveed in Pi/pico_4f31_on_Fla53
/Pico_Software.txt

textpack

On the RP2040 Pico, Thonny does not include the ability to copy multiple files between the Raspberry Pi and the RP2040 Pico; they must be transferred one by one. The Pack (textpack_pi.py) algorithm (textpack.py) packs multiple text (and/or source) files into one text file. An Unpack (unpack_pico.py) algorithm will also be included to unpack the full file of multiple programs. These two programs facilitate the transfer (and/or back-up in future) of all the text/source files on the RP2040 Pico. The syntax used in the textpack routines is compatible with the Article 174 in source 06 below. In that article look for the heading: IX "textpack" Program Package for Python (Not Thonny).

pktix packets

This packet protocol (pronounced pack'-e-ticks" or "packet-9") is a mini-Internet protocol. It is described in more detail in the preliminary comments in the routine named test_TxH_pico.py which is used to (read and) transmit the temperature of the processor in the RP2040 chip. The use of packets is essential to avoid the loss of characters, so that each use of the "read characters" routine can specify the correct number of characters to read. This packet protocol is described in more detail under the heading "pktix protocol" which appears next in this article.

pktix protocol

This packet protocol is designed to be somewhat self-synchronizing using a serial asynchronous ascii character stream. The initial basic version of this protocol uses 16 byte packets. Packets are presumed to be sent and received in correct sequence, although the packets can be numbered, so packet-synchronization errors can at least be detected. In the basic version of the pktix protocol, no special error checking and no acknowledgements are included, presuming that the communication line (between the Raspberry Pi and the RP2040 pico) is error-free. However, perfectly identical baud rates are NOT presumed. Delays between characters are allowed, as should be the case with asynchronous communications. The asynchronous communication has an opportunity to "stay" in sync by including a "quiet time" of either 5, 10 or 100 characters between packets. In future, the duration of this "quiet time" can be used to detect and report slight baud rate discrepancies between transmitter and receiver. Note that the packet delimiters for pktix are as follows: SOM is "[" and EOM is "]". Sufficient EOM characters follow each message to fill out the (or add a) last packet. The first character of each message is a single character defining "I", the pktix packet size (in characters). Initially I is "A" which means 16 characters, in future "B" will mean 256 characters and "C" will mean 65536 characters. Packet usage can be disabled by setting "I" = " " which is a single space. The maximum number of packets in any single message is limited to the same number as the number of characters in each packet. Therefore the maximum total characters in each message is the square of the number defined by "I". One purpose of the SOM and EOM is to pad the message so that the last packet contains at least one "EOM" character. The use of SOM/EOM permits the detection of transmission errors, which should be non-existent. A sequence of characters enclosed between a pair of SOM and EOM characters will be called a field. As mentioned previously, a non-packetized version of pktix can be used by setting "I" to a space. This option is described under the next heading "pktix packet sizes".

Defining The pktix Packet Size

In the pktix protocol, the packet size is selectable. The first character sent defines the packet size. This first character is called the "I" character. If "I" is a space, it means that packets are not being used. Other values for "I" are "A", "B" and "C".

ISSUE 01
The main issue with the pktix protocol is the use of 2 bytes for the packet number. These 2 bytes could contain a number up to 255, but such a number will contain control characters. To avoid this, and to allow for messages with up to 65536 packets, 5 bytes following the SOH are needed for packet types of "B" and "C". The packet type of "A" will be unchanged with "[16" being prefixed to every message. This allows for type "A" pktix packet sizes up to 99 character long. This may be desirable if type "A" is used to transmit packets corresponding to approximately the normal 80 character width of typewritten ASCII lines. This could be a quick and dirty way of allowing any person to type and send "normal" messages while still using type "A" pktix packets.

The case of "I" = " " is permitted. This does not use packets, and each character is transmitted and read separately. This protocol is simple to implement, but limits the maximum speed of character transmission and includes no special error detection/correction facilities. Speeds higher than 9600 bps should not be attempted when "I" = " ". The resulting text stream will have (and will appear to have) a space as the first character of each message. SOM and EOM are not used. In fact, when "I" = " ", the messages to be transmitted can be typed by a human who has no knowledge of any pktix protocol. When "I" = " ", the transmission of a "0" every minute is not even necessary. Just remember to begin each message with at least one space character. The pktix receiver software will remove all leading spaces in every message that it receives. When "I" = " ", the end of each message is not defined by an EOM. Instead, the end of each message is designated by an End of Line sequence. Normally, the End of Line sequence is designted by an LF character (0x0C), in accordance with the Linux software protocol. The Apple (IOS) protocol does not include LF and will not function correctly unless the receiver is notified that the Apple type of End of Line, CR (0x0D) is being used. Windows End of Lines (CR followed by LF) will function correctly, but the communication will appear to be "double spaced" because each End of Line is actually a CR-LF pair. An example of "I" = " " is shown below:

  
  msgOut = """
    #B +
    "BPS" +
    oxC +
    """

  Note that the """ should be ignored in the above definition of msgOut.

Note that #B is a space (0x20) and 0x0C is a LF (which is Ctrl-J). A LF is produced by typing the Enter key when using Linux. This Pix BPS command tells the receiver to set its speed (bps) to 9600 bps and to set the byte sequence to N81. To send this message using Linux, the operator simply types space,BPS,Enter (without the commas, where "Enter" is the Enter key). The receiver should reply with a message indicating its current (i.e. previous) speed. In most problematic cases, the receiver will send an error message saying:

pktix/pix ERROR: No space prefix. Use 9600 N81.
Prefix each command with the space character (ePhotoCaption.com/a/177/177.html).
   e.g. space,BPS,Enter   or     space,HELP,Enter *********555555555.

Note that a 2 second delay will be inserted between the "Help,Enter" and the first "*"
Returning to the case of "I" NOT being " ", the following message structure applies:

I
C
msgOut = """
S +
D +
E +
P +
C"""

# where (in the basic pktix) each field will contain
# I is the letter "A" meaning "1 to 16 packets of exactly 16 bytes each (pktSize)"
# S is SOM
# D is Data text to be sent (will not include any unescaped EOM or "/" characters
# and will be followed by one EOM)
# E is EOM
# P is the padding characters (enough EOMs to fill the last packet)
# V is t5c (5 character time delay: "roman numberal V")
# X is t10c (ten character time delay: "roman numeral X")
# C is t100c (100 character time delay: "roman numeral C")

# R is the address of the pico Card (at least the rightmost 4 characters of the SN of the Pico card)
# (the previous value of "A" has been deprecated, "R" can be the Rightmost 4 characters
# of the Pico card or the full Serial Number of the Pico card.)
# L is the number of data characters in all packets in the whole message (not used in basic pktix)
# N is the packet number (not used in basic pktix)
# F is the hash code function name (not used in basic pktix)
# H is the hash code (not used in basic pktix)
# B is a space (0x20) (must be the first character of each message when "I"=" "

# Most basic messages will have msgOut = "IC" "SDEPX"
# An escaped EOM in a basic pktix message data is a "/E", each "/" must be escaped as "//", each
# EOS must be escaped as "/S" all 3 being included in the character count in the message,
# A message field requiring more than one packet will have a packetized format of
# SDEPX which is "SDV" "DV" "DV" "DEPX"

# Between messages, each transmitter will send "0" (0x30) every minute indicating that it's alive but
# has no message to send.
# Before sending each message the transmitter will send a single character which is usually an "A" (0x41) indicating
# that the following message will be at most 16 packets of 16 bytes each. In the future when the packet
# size can be 256 characters, the transmitter will precede each message with a single "B" (0x42)
# indicating that each packet will contain 256 characters. This will allow future message lengths
# at least as big as 256 x 256 = 65536 characters. This is a total message length of 65536 characters.
# Later, "C" (0x43) will indicate a packet size of 65536 characters.

# Future advanced versions of pktix will have a 5-field msgOut = "SEV" "SAEV" "S0xLEV" "SDEPX" "SF:HEPX"
# with each data field having the format :
# SDEPX which is SNDV NDV . . . . NDV etc NDEPX
# Note that each packet is preceded by its packet number (N) in advanced pktix.
# The optional advanced pktix Null message of SEC SEC S0x0EC SEC S:EC re-establishes asynchronous synchronization
# and can always be ignored.
#
# In the pktix Protocol, the following conventions apply:

# In basic pktix, if "I" = " ", no packets nor packet numbers nor SOM nor EOM are used
# if "I" = "A" , packets are used but no packet numbers are used.
# Issue!!! U should not be used (i.e. U means a Null byte string)
# In advanced pktix, when I = "B" or "C"
# N represents the use of 2-byte (base 256) packet number.
# when I = "A", packets are used but no packet numbers are used.
# N should not be used (i.e. N means a Null byte string)
# when I = " ", no packets nor packet numbers nor SOM nor EOM are used
# L is the exact 4-byte message character "Count" not including the initial SOM nor the final EOM character(s)
# ISSUE!!! when is "L" used??????
# V is t5c (5 character time delay: "roman numeral V")

# In addition to the above:
# * is a full packet of "*" (0xAA or 0x55) characters (optional for synchronization)
# with the format:
# S**********************Ev

# When a pktix receiver starts up (and between messages) it should begin by expecting packets of single
# characters. It will read a single 8-bit character expecting it to be a "0" meaning an idle transmitter.
# If it is not a "0", it will keep reading single characters until it reads a "0".
# After it reads a "0", it will read another single 8-bit character expecting it to be an "A". If it is not an
# "A", the character will be discarded, but the receiver will presume that it is reading a character
# stream that is mid-message. It will read single 8-bit characters searching for a "]" which will indicate
# that this is the last packet of the message. It will keep reading and discarding all the "]" that it sees.
# After the last "]" or after a quite time, the next 8-bit character should be a "0". The receiver should
# keep reading and discarding the "0"
# characters. When an "A" is finally received (while reading single 8-bit characters) after a "0", the receiver
# will presume that subsequent packets will be packets of 16 characters. The receiver will now supposedly be fully
# "synchronized" with the transmitter". It is important that these single character message groups precede each packet stream.
# This is because the receiver must know the expected packet size so that the "read characters" routine can
# request the reading of each correct packet size. If something other than an "A" is received, the receiver should
# begin looking for a "]" (meaning "end of message") again. If the state of "being in mid-message
# continues 100 times, a human operator should be informed that this ERROR is occuring.

# Note that the Normal Initial UART speed between a Pi and a Pico should be 9600 bps with a byte structure of N81.
#

Escaped characters in Basic pktix

[Editors Note dated 2022FJun02] This note is written as a correction to this article. It has been noted that the method of escaping a "]" character in packets as described is not a leakproof method. More specifically, escaping each "]" by replacing each "]" with "]]" leads to ambiguous messages. A non-ambiguous method is to escape both "/" and "]" by prefixing each with a "/". Use of this escape methodology will produce messages that have no single occurrences of "/" except when the "/" is followed by "]" (where the "/]" should be converted to "]". Of course each occurence of "//" must also be converted to "/".) This article will soon be corrected to eliminate this error.

advanced pktix

The simple pktix protocol described above is for simple messaging where the user can control the use of the EOM character, "]", in the text messages. In basic pktix, to send the character "]", it must be escaped (repeated as "]]"). When the packets might contain the EOM character (and it cannot be escaped), such as when sending a program or a data file, the advanced pktix protocol must be used. Of course, it is possible to send such programs using basic pktix, but each "]" and "/" must be properly escaped. In the advanced pktix protocol, there are 5 fields, each field being enclosed within "[" and "]". The first field is an empty message. The advanced pktix message format must contain five fields each being formatted as follows:

[][picoSN][0x00FFFF][data . . . . end of data][ :checksum]

5 fields in advanced pktix

The 5 fields are:

 null header field
 pico address (SN) field
 length field
 data field
 checksum field

The advanced pktix format is identified by its first two characters being "[]" which is an empty message field, something that is meaningless in the basic (non-advanced) pktix packet definition. The empty message ("[]") field is followed by a field containing at least, the least significant 4 characters of the serial number of the Pico Device. The whole serial number can even be included, but only the least significant 4 characters will be used to identify the pico that is to receive and process the message. These 4 characters will be used to identify which pico is being addressed to receive this message. The next field will contain the exact character count of the message, e.g. 0x00FFFF. The 0x means hexadecimal representation of the count. (0j would mean a decimal count, 0c would mean a base 256 representaion of the count. Beware that base 256 might include "[" or "]" characters.) If any character of the message count is "]" (0x5D), a different base (usually a smaller base) should be used. The example of "00FFFF" means 255 in hexadecimal. This is the message length which is theexact number of data characters in the message (escape characters must not be used). This second field must be followed by a third field containing the "[" character followed by the data characters. These data characters can contain any value (even "[" or "]"). After exactly this number of characters (not counting the "["), the next character must be a "]" which terminates the data field. The advanced pktix protocol does not permit each EOM character be escaped within the data message. The next field of the packet is the checksum field, which is also enclosed within "[" and "]". The first 1 to 5 characters of the checksum field contains ":" or " :" which identifies the type of checksum. Four spaces (e.g. " :") or null (e.g. ":") means "nochecksum" and should be followed by a checksum which is null (i.e. an empty string). Other checksums will be identified by a name other than ":".

Note that the second, fourth and fifth fields can include the characters "[" and "]" as data within their field. Note also that the minimum length of an advanced pktix message (of data length of 1) where "I" = "A" is around 20 characters, if no check sum is used. But 5 message fields mean that the "overhead" in the messages brings the total characters in the 5 packets being sent to 100 (5x20). Compare this to the basic (non-advanced) pktix message length (for a data length of 1) which is 3 characters [in 1 packet which including overhead is 20 ( 1x20) characters]. Why should packets be used? Where a system is designed to include the packet concept, there are two main advantages:

 1) each "read characters" invocation will specify the exact number of characters to be read!
 2) multiple picos can be addressed on the same serial USB bus!

It is intended that the advanced pktix software can communicate with the basic pktix software, but in that case, communication will, of course be limited to the basic pktix software functionality. Of course the pktix software should always be backwards compatible.

Advanced pktix Error messages from the pico receiver

Every Pix command be followed by a reply froom the pico. The reply can be a logical reply or it can be an error message. The format of an error message will be either:

0X, ERROR: text describing the error, LF,X
(excluding the commas)

msgOut = "SEV" "SAEV" "S0xLEV" "SDEPX" "SF:HEPX"

(where D represents the actual Error message) Of course the length of the error 
message must not exceed the permitted maximum message length.

This type of error message does not require any POLLing by the controlling computer, but for non-Pix systems, the error message must begin to be sent during the 100 character quiet time following the message containing the error.

Furthermore, a NAK (0x15) can be sent by the receiver during any quiet time in the transmission. There is no guarantee that such a NAK will be noticed by the controlling computer. But if a NAK is noticed, the current message will be fully resent, from the beginning. When computers other than a Raspberry Pi are controlling the transmission, the computer might not be listening for a reply at all times. If PuTTY software is being used, a log of all transmissions and replies can be requested.

Advanced pktix Replies

Only one pico is supposed to reply to a command that is specifically addressed to it. Furthermore, a reply must be sent in response to each command.

Advanced pktix Polling of Picos

As of 2022, there is no method defined for polling all the picos on the serial bus. The reason for POLLing is to permit any pico to interrupt the messaging process that the controlling computer is conducting. The best POLLing method being contemplated is for the main computer to address each of the picos directly, one after another, using a POLL command. Another method is for one POLL command to be sent with an address of "****". Any pico that wishes to interrupt and send a message to the controlling computer will include its SN in its reply. If the resulting reply contains an error, it will be presumed that more than one pico tried to reply. In this case each pico will be addressed one after another, to determine exactly which picos replied to the POLL command. The message being sent as a reply to the POLL must contain a COMMAND of "INTERRUPT" specifying that it is replying to the POLL. This is indeed a similar process to that used on the I2C serial bus. The I2C bus comkunications is superior to the pktix protocol, but I2C is not yet supported on modern non-Raspberry computers. The I2C bus is also more susceptible to noise and requires special pull-up resistors compared to the USB serial line cables used by the pktix protocol.

Ongoing Software Development

As of 2022FJun03, my current software development includes the following projects:

1. Pix pico system software.
2. pktix protocol software.
3. textpack software for the pico.
4. FFQ delayed software invocation.
5. ICH180RR to replace MIC.
6. igalri.com improvements.
7. TooHot Temperature Detector.
8. MAKPiADC applications.

Sources

Video Sources

Video Source V177:01: (From Arduino to Pi Pico) LED Blinker [spoken English] (23 min)

by LearnElectronics c2021AJan21
Video Source V177:02: read the temperature sensor on the Raspberry Pi Pico (13 min)

by LearnElectronics c2021AJan29

Web Sources

Web Source S177:01: Cytron

by Cytron as of 2012CMar08
Web Source S177:02: Pimoroni

by Pimoroni as of 2012CMar08 >
Web Source S177:03: Pi: Sensor Kit for Arduino

by D@CC as of 2020LDec11
Web Source S177:04: Pi: Maker Pi Pico by Cytron

by D@CC as of 2021EMay19
Web Source S177:05: Pico programs: pico_4f31_on_Fla53 (zipped)

by D@CC as of 2022EMay30
Web Source S177:06: Creating Python Packages ... (174)

by D@CC as of 2022BFeb26
Web Source S177:07: Software Problems and Solutions ... (150)

by D@CC as of 2021FJun23
Web Source S177:08: US ASCII Table (wikipedia)

by D@CC as of 2021FJun23
Web Source S177:09: IT: Simple VT100 Monitor Emulation (172)

by D@CC as of 2022BFeb20

There is a way to "google" any of the part-numbers, words or phrases in all my articles. This "google-like" search limits itself ONLY to my articles. Just go to the top of "Articles by Old King Cole" and look for the "search" input box named "freefind".

WebMaster: Ye Old King Cole

Click here to return to ePC Articles by Old King Cole

Date Written: 2022 E May 01
Last Updated: 2024 B Feb 16
Font: Courier New 10

/177.html