USARTShell

USARTShell

Function of the miniUSB connector

Another of the communication interface is the USARTShell, which is used to communicate with the Unicard through an RS-232 serial line emulated through a miniUSB connector. A communication channel that uses a miniUSB connector is able to work in two modes:

USARTShell
emulation of a SIO channel from a B serial expansion card for SHARP computers (for example SHARP MZ-1E24)

The setup of the communication mode is controlled using a different interface MZFREPO or one of the CFG files. A more detailed description of the CFG files, including the one for setting up the miniUSB connector's working mode is here Emulated Peripherals.

Drivers Instalation

Firstly, download and install the STM32 Virtual COM port driver version 1.3.1. Depending on the type of OS we either run VCP_V1.3.1_Setup.exe or VCP_V1.3.1_Setup_x64.exe.

STMicroelectronics Virtual COM Port (COM11)

After successfully installing the drivers, a virtual COM Port should appear in your device manager. The number of the port can of course differ on various computers.
Displaying the “Properties” option tab

If the virtual COM port is correctly installed, it is still necessary to set the communication parameters. Pressing the right mouse button on the COM port line will bring up a selection, from which select “Properties”.
Setting up the parameters of the virtual COM port

Here we can set the communication parameters 115200, 8, N, 1, flow control is best set to none for starters, when working correctly it can later be set to hardware.

Warning

The latest version of the drivers does not work. Therefore it is necessary to install an older version of the drivers 1.3.1

UniUSARTShell

The UniUSARTShell program run from the command line is used for the communication with the USARTShell interface. If the program is run without any parameters, it will offer a guide - a list of all available commands for communication with the USARTShell.

c:\>UniUSARTShell
Unicard USART shell                                      PC build 2018-08-04.21


Usage:
        UniUSARTshell <device> <command> [<param1>] [<param2>]

Available commands are: date, remount, filelist, readdir, mkdir, unlink,
                        open, new, read, boot, state, laninfo, rev, gdg.


c:\>

As <device>, it is necessary to enter an installed virtual COM port using the above mentioned way (for example COM11). Supported commands <command> are:

date, remount, filelist, readdir, mkdir, unlink, open, new, read, boot, state, laninfo, rev, gdg

UniUSARTShell

Commands without parameters:

BOOT

Resets the computer.

c:\>UniUSARTShell COM11 boot
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending BOOT...
        BOOT
c:\>

REV

Displays MZ_ID, version and subversion of the current firmware, as they are written in the firmware header, see chapter Description of the header's structure.

MZ-800

c:\>UniUSARTShell COM11 rev
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending REV...
        REV
        OK:REV MZ800 v0.18

c:\>

MZ-1500

c:\>UniUSARTShell COM11 rev
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending REV...
        REV
        OK:REV MZ1500 v0.18

c:\>

GDG

Displays the contents of the display mode register.

MZ-800

c:\>UniUSARTShell COM11 gdg
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending GDG...
        GDG
        OK:GDG MZ_mode=1, MZ_graphic_mode=6

c:\>

MZ-800 in the MZ-700 mode

c:\>UniUSARTShell COM11 gdg
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending GDG...
        GDG
        OK:GDG MZ_mode=0, MZ_graphic_mode=8

c:\>

MZ-1500

c:\>UniUSARTShell COM11 gdg
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending GDG...
        GDG
        OK:GDG MZ_mode=0, MZ_graphic_mode=8

c:\>

STATE

The first number determines the collected data from the address bus - in this example (002C), the second number determines data from the data bus (3A). IN and OUT are images of the internal registers of the ARM processors in the Unicard.

MZ-800

c:\>UniUSARTShell COM11 state
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending STATE...
        STATE
        OK:STATE (002C)=3A, IN=FA, OUT=0D

c:\>

MZ-1500

c:\>UniUSARTShell COM11 state
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending STATE...
        STATE
        OK:STATE (332A)=3A, IN=52, OUT=0D

c:\>

LANINFO

Displays information about the current settings of the parameters for web configuration.

without a connected cable

c:\>UniUSARTShell COM11 laninfo
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending LANINFO...
        LANINFO
        KSZ8031: OK
        PHY_ID:  00221560
        LINK:    DOWN
        HWADDR:  00-1C-EE-1A-04-6F
        IPCFG:   STATIC
        IPADDR:  192.168.1.111
        NETMASK: 255.255.255.0
        GATEWAY: 192.168.1.20
        OK:LANINFO_DONE

c:\>

with a connected cable

c:\>UniUSARTShell COM11 laninfo
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending LANINFO...
        LANINFO
        KSZ8031: OK
        PHY_ID:  00221560
        LINK:    UP
        HWADDR:  00-1C-EE-1A-04-6F
        IPCFG:   STATIC
        IPADDR:  192.168.1.111
        NETMASK: 255.255.255.0
        GATEWAY: 192.168.1.20
        OK:LANINFO_DONE

c:\>

Commands with one parameter:

MKDIR <path>

Creates a folder <path> and displays the results of the operation:

OK:MKDIR <path> the folder was created
ERR:MKDIR <path> the folder could not be created (for example, if it already exists)

a non-existing folder as aparameter

c:\>UniUSARTShell COM11 mkdir \unicard\TESTMKDIR
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending MKDIR...
        MKDIR \unicard\TESTMKDIR
        OK:MKDIR \unicard\TESTMKDIR

c:\>

an existing folder as parameter

c:\>UniUSARTShell COM11 mkdir \unicard\TESTMKDIR
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending MKDIR...
        MKDIR \unicard\TESTMKDIR
        ERR:MKDIR \unicard\TESTMKDIR

c:\>

Before creating the folder TESTMKDIR
After creating the folder TESTMKDIR

UNLINK <filepath>

Deletes a file or folder <filepath> and shows the result of the operation:

OK:UNLINK <filepath> the file or folder was deleted
ERR:UNLINK <filepath> the file or folder could not be deleted (for example, if the folder or file do not exist)

an existing folder as parameter

c:\>UniUSARTShell COM11 unlink /unicard/TESTMKDIR
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending UNLINK...
        UNLINK /unicard/TESTMKDIR
        OK:UNLINK /unicard/TESTMKDIR

c:\>

a non-existing folder as parameter

c:\>UniUSARTShell COM11 unlink /unicard/TESTMKDIR
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending UNLINK...
        UNLINK /unicard/TESTMKDIR
        ERR:UNLINK /unicard/TESTMKDIR

c:\>

Before deleting the folder TESTMKDIR
After deleting the folder TESTMKDIR

REMOUNT <0..3 >

Disconnects the appropriate FD<0..3> ([A]:..[D]:) drive and calls for a remount, which is done normally according to the contents of a CFG file /unicard/fd<0..3>.cfg.

the attempt for a REMOUNT FD0 ([A]:) of the drive without a configuration file fd0.cfg

c:\>UniUSARTShell COM11 remount 0
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending REMOUNT...
        REMOUNT 0
        ERR:REMOUNT 0

c:\>

copying a configuration file fd0.cfg with a link to the floppy disk image Lemmings.dsk on a Unicard to folder \unicard\

c:\>UniUSARTShell COM11 new fd0.cfg \unicard\fd0.cfg
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending New...
        NEW \unicard\fd0.cfg
        OK:NEW \unicard\fd0.cfg
Sending FSIZE: 0x0000000e
        OK:SIZE 0x0000000e
Sending Data.
        OK:CLOSE 0xd2b7a6fb

*************************
* Size:            14 B *
* Time:          0.10 s *
* Speed:     137.25 Bps *
*************************


c:\>

REMOUNT FD0 ([A]:) remount of a drive based on a new configuration file fd0.cfg

c:\>UniUSARTShell COM11 remount 0
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending REMOUNT...
        REMOUNT 0
        OK:REMOUNT 0

c:\>

There is no configuration file on FD0 ([A]:) and the drive is not connected.
After loading the configuration file fd0.cfg into folder \unicard\ on the Unicard and executing a REMOUNT command the drive FD0 ([A]:) Lemmings.dsk will be connected

Commands with two parameters:

READ <src_file> <dst_file>

Copies the file <src_file> (the name of the file can contain the path) from an SD card in the Unicard to the PC into file <dst_file> (the name of the file can contain the path). Will open the file on the SD card for reading only, and will, in binary, send as DWORD its size, followed by the contents of the file and the result of the operation:

OK:CLOSE 0x???????? the successful copying and closing of the file with a displayed CRC32 checksum
ERR:READ <src_file> an error occured when reading the file

copies the file

c:\>UniUSARTShell COM11 read \unicard\mzfloader.cfg mzfloader.cfg
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending Read...
        READ \unicard\mzfloader.cfg
        OK:READ \unicard\mzfloader.cfg
Receiving FSIZE: 0x00000015
Receiving Data
        OK:CLOSE 0x0311000b

*************************
* Size:            21 B *
* Time:          0.00 s *
* Speed:       1.#J Bps *
*************************


c:\>

error when reading the file

c:\>UniUSARTShell COM11 read qd.cfg qd.cfg
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending Read...
        READ qd.cfg
Error USARTshell->READ: ERR:READ qd.cfg

c:\>

NEW <src_file> <dst_file>

Copies the file <src_file> (the name of the file can contain the path) from an SD card in the Unicard to the PC into file <dst_file> (the name of the file can contain the path). After successfully opening the new file for writing <dst_file> the input of USARTShell will switch to binary mode, in which it will expect as DWORD the file size, followed by its contents. After it is finished, it will display the result of the operation:

OK:NEW <dst_file> the file was successfully copied
ERR:WRITE An error occured when writing the file
ERR:DATA_TIMEOUT No data was received for more than two seconds, the Unicard will close the file and move back to command mode
ERR:NEW <dst_file> The file already exists

The command NEW can only be used for creating a new file, it will display an error when trying to overwrite an already existing file.

the file was successfully copied

c:\>UniUSARTShell COM11 new Flappy_A.mzq Flappy_A.mzq
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending New...
        NEW Flappy_A.mzq
        OK:NEW Flappy_A.mzq
Sending FSIZE: 0x0000f01f
        OK:SIZE 0x0000f01f
Sending Data....................................................................
.....................................................
        OK:CLOSE 0xc7138ef3

*************************
* Size:         61471 B *
* Time:         12.33 s *
* Speed:    4987.10 Bps *
*************************


c:\>

Attempt to overwrite an already existing file

c:\>UniUSARTShell COM11 new unicard800.app unicard.app
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending New...
        NEW unicard.app
Error USARTshell->OPEN/NEW: ERR:NEW unicard.app

c:\>

Attempt to copy a non-existing file

c:\>UniUSARTShell COM11 new CosmicCruiser3.mzt CosmicCruiser3.mzt
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Could not open src file: No such file or directory

c:\>

Before copying the new file mgr1500.mzf
After copying the new file mgr1500.mzf

OPEN <src_file> <dst_file>

Works the same way as the NEW command, the only difference being that it will copy the file <src_file> even if the target file <dst_file> already exists and overwrites its contents. After it finishes, it will display the result of the operation:

OK:OPEN <dst_file> The file was successfully copied
ERR:WRITE An error occured when writing the file
ERR:DATA_TIMEOUT No data was received for more than two seconds, the Unicard will close the file and move back to command mode

c:\>UniUSARTShell COM11 open mgr1500.mzf \unicard\mgr1500.mzf
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending Open...
        OPEN \unicard\mgr1500.mzf
        OK:OPEN \unicard\mgr1500.mzf
Sending FSIZE: 0x00001be2
        OK:SIZE 0x00001be2
Sending Data..............
        OK:CLOSE 0xb682acd8

*************************
* Size:          7138 B *
* Time:          1.45 s *
* Speed:    4936.38 Bps *
*************************


c:\>

Before overwriting the file unicard.app with size 190720b by a file of the same name and size 198988b
After overwriting the file unicard.app with size 190720b by a file of the same name and size 198988b

Commands with a varied number of parameters:

FILELIST (optional <path>)

Displays the contents of the folder <path>, if run without a parameter <path>, will put “\” after it (root of the SD card) and will display the result of the operation:

OK:FILELIST <path> The folder was successfully open, what follows is a list of files and at the end of it OK:FILELIST_DONE
ERR:FILELIST <path> The folder could not be open (for example, if it does not exist)
ERR:READDIR An error occured when attempting to read the individual subparts of the folder

without parameter

c:\>UniUSARTShell COM11 filelist
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending FILELIST...
        FILELIST \
        OK:FILELIST \

        TESTMKDIR/
        unicard/
        mgr800.mzf                             8462
        unicard.app                          190720

        OK:FILELIST_DONE

c:\>

an existing folder as a parameter

c:\>UniUSARTShell COM11 filelist \unicard
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending FILELIST...
        FILELIST \unicard
        OK:FILELIST \unicard

        mzfloader.cfg                            21
        QDisk-BASIC800.mzq                    61471
        mgr800.mzf                             8462
        ramdisc_sromloader.mzr              1048576
        ramdisc1.mzr                        1048576
        mzfloader1.mzq                        52868
        qd.cfg                                   31
        ramdisc.cfg                              21
        network.cfg                              41
        mz1r23.rom                           131072
        mz1r24.rom                           262144
        READDIRTEST1/
        READDIRTEST2/
        READDIRTEST3/

        OK:FILELIST_DONE

c:\>

a non-existing folder as a parameter

c:\>UniUSARTShell COM11 filelist wrongdir
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending FILELIST...
        FILELIST wrongdir
Error USARTshell->FILELIST: ERR:FILELIST wrongdir

c:\>

without a parameter (root) with a reading error

c:\>UniUSARTShell COM11 filelist
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending FILELIST...
        FILELIST \
        OK:FILELIST \

        TESTMKDIR/
Error USARTshell->FILELIST1: ERR:READDIR

c:\>

READDIR (optional <path>)

Displays the contents of the folder <path> in an expanded format. If run without a parameter <path>, it will put “\” after it (root of the SD card) andw ill display the result of the operation:

OK:READDIR <path> The folder was successfully open, what follows is a list of files and at the end of it OK:READDIR_DONE
ERR:READDIR <path> The folder could not be open (for example, if it does not exist)
ERR:READDIR An error occured when attempting to read the individual subparts of the folder

without a parameter

c:\>UniUSARTShell COM11 readdir
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending READDIR...
        READDIR \
        OK:READDIR \

[DIR]            TESTMKDIR                                             01-01-2017  00:00:00
[DIR]            unicard                                               11-13-2017  21:28:26
[ARC]            mgr800.mzf                               8.26 kB      11-02-2018  12:42:38
[ARC]            unicard.app                            122.25 kB      29-15-2017  22:11:08

        OK:READDIR_DONE

c:\>

an existing folder as a parameter

c:\>UniUSARTShell COM11 readdir \unicard
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending READDIR...
        READDIR \unicard
        OK:READDIR \unicard

[ARC]            mzfloader.cfg                              21  B      11-13-2017  21:30:10
[ARC]            QDisk-BASIC800.mzq                    4096.00 MB      04-01-2018  17:01:02
[ARC]            mgr800.mzf                               8.26 kB      11-02-2018  13:42:38
[ARC]            ramdisc_sromloader.mzr                   1.00 MB      27-08-2017  00:58:28
[ARC]            ramdisc1.mzr                             1.00 MB      27-08-2017  00:58:28
[ARC]            mzfloader1.mzq                        4095.99 MB      24-14-2016  23:39:16
[ARC]            qd.cfg                                     31  B      13-13-2017  10:09:26
[ARC]            ramdisc.cfg                                21  B      13-13-2017  10:10:02
[ARC]            network.cfg                                41  B      18-15-2017  22:19:22
[ARC]            mz1r23.rom                             128.00 kB      30-04-2014  15:36:34
[ARC]            mz1r24.rom                             256.00 kB      09-02-2003  15:26:56
[DIR]            READDIRTEST1                                          01-01-2017  00:00:00
[DIR]            READDIRTEST2                                          01-01-2017  00:00:00
[DIR]            READDIRTEST3                                          01-01-2017  00:00:00

        OK:READDIR_DONE

c:\>

a non-existing folder as a parameter

c:\>UniUSARTShell COM11 readdir wrongdir
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending READDIR...
        READDIR wrongdir
Error USARTshell->READDIR: ERR:READDIR wrongdir

c:\>

without the parameter (root) with a reading error

c:\>UniUSARTShell COM11 readdir
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending READDIR...
        READDIR \
        OK:READDIR \

[DIR]            TESTMKDIR                                             01-01-2017  00:00:00
Error USARTshell->FILELIST1: ERR:READDIR

c:\>

DATE (optional <rrrr-mm-dd hh:mm:ss>)

If run without a parameter, will display current data and time set in the Unicard. When run with a parameter in the form of <rrrr-mm-dd hh:mm:ss> will set the Unicard date and time to the written values. When the parameter is not written correctly, will display an error with the correct format of the parameter.

without a parameter

c:\>UniUSARTShell COM11 date
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending DATE...
        DATE
        OK:DATE 2018-08-03 13:48:51

c:\>

the correct format of the parameter

c:\>UniUSARTShell COM11 date 2018-08-03 13:47:00
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET
Sending DATE...
        DATE 2018-08-03 13:47:00
        OK:DATE 2018-08-03 13:47:00

c:\>

an incorrect format of the parameter

c:\>UniUSARTShell COM11 date wrongdate
Unicard USART shell                                      PC build 2018-07-22.20
Sending Reset...
        OK:RESET

Error, usage: USARTshell <device> date
              USARTshell <device> date YYYY-MM-DD HH:MM:SS

c:\>

Table of Contents

USARTShell

Function of the miniUSB connector

Drivers Instalation

Warning

UniUSARTShell

Commands without parameters:

BOOT

REV

GDG

STATE

LANINFO

Commands with one parameter:

MKDIR <path>

UNLINK <filepath>

REMOUNT <0..3 >

Commands with two parameters:

READ <src_file> <dst_file>

NEW <src_file> <dst_file>

OPEN <src_file> <dst_file>

Commands with a varied number of parameters:

FILELIST (optional <path>)

READDIR (optional <path>)

DATE (optional <rrrr-mm-dd hh:mm:ss>)