From 054ad98b910d2e918123f60be1a227061067a7fb Mon Sep 17 00:00:00 2001 From: Andrew Owen Date: Sun, 27 Aug 2023 12:23:35 +0100 Subject: [PATCH] revised English translation --- doc/src/English ZXTRES Manual.adoc | 1244 +++++++++++++++------------- doc/src/miniduino_en.adoc | 107 ++- 2 files changed, 722 insertions(+), 629 deletions(-) diff --git a/doc/src/English ZXTRES Manual.adoc b/doc/src/English ZXTRES Manual.adoc index d18bbd9..96c1b68 100644 --- a/doc/src/English ZXTRES Manual.adoc +++ b/doc/src/English ZXTRES Manual.adoc @@ -1,12 +1,13 @@ -= ZXTRES, ZXTRES+ and ZXTRES++ Manual += ZXTRES ZXTRES+ and ZXTRES++ Manual :author: kounch +:editor: aowendev :revnumber: 1.0.0 :doctype: book :notitle: :front-cover-image: image:img/portada_zxtres.jpg[] :email: kounch@users.noreply.github.com :Revision: 1.0 -:description: English Manual of ZXTRES +:description: ZXTRES Manual (Hiberno-English) :keywords: Manual, English, ZXTRES, ZXTRES+, ZXTRES++ :icons: font :source-highlighter: rouge @@ -18,29 +19,29 @@ == Introduction -ZXTRES, ZXTRES+ and ZXTRES++ are the continuation of https://zxuno.speccy.org[ZX-Uno] a hardware and software project based on an FPGA board programmed to work like a ZX Spectrum computer, and created by the ZX-Uno team: Superfo, AVillena, McLeod, Quest and Hark0. +The ZXTRES ZXTRES+ and ZXTRES++ are a continuation of the https://zxuno.speccy.org[ZX-Uno] hardware and software project created by Superfo AVillena McLeod Quest and Hark0. The ZX-Uno team created an FPGA board programmed to behave like a ZX Spectrum computer. -Over time, the project has been growing, and now it is possible to use different software configurations (cores), which work like different systems than the ZX Spectrum, and you can choose to start the ZXTRES with the desired configuration among all those available. +Over time the project grew and it's now possible to use different software configurations (cores) that work like different systems other than the ZX Spectrum. You can choose to start the ZXTRES with your desired configuration from all those available. -ZXTRES official web page is . +The ZXTRES official web page is https://www.example.com[https://www.example.com]. **FIXME** -Most of the functions and features of ZXTRES, ZXTRES+ and ZXTRES++ and are the same, so this document will generally talk about ZXTRES, indicating the differences where necessary. +Most of the functions and features of the ZXTRES ZXTRES+ and ZXTRES++ are the same, so this document typically refers to the ZXTRES indicating the differences when necessary. -=== Aknowledgements +=== Acknowledgements -A lot of the content of this manual is based on information previously shared: +Much of the content of this manual is based on information previously shared at: -- At https://www.forofpga.es/[foroFPGA] -- At https://www.zxuno.com/forum/[ZX-Uno forum] -- Several existing FAQ, mostly the original version https://uto.speccy.org/zxunofaq.html[by @uto_dev], and the latest one http://desubikado.sytes.net/zx-uno-faq-version-desubikado/[by @desUBIKado] -- Official Telegram Channels for https://t.me/zxuno[ZX-Uno], https://t.me/zxdosfpga[ZXDOS] and https://t.me/zxtresfpga[ZXTRES] -- At https://github.com/zxtres/wiki/wiki[ZXTRES official wiki] +- https://www.forofpga.es/[foroFPGA]. +- https://www.zxuno.com/forum/[ZX-Uno forum]. +- Several existing FAQs; mostly the original version https://uto.speccy.org/zxunofaq.html[by @uto_dev] and the latest one http://desubikado.sytes.net/zx-uno-faq-version-desubikado/[by @desUBIKado]. +- the official Telegram channels for https://t.me/zxuno[ZX-Uno] https://t.me/zxdosfpga[ZXDOS] and https://t.me/zxtresfpga[ZXTRES]. +- https://github.com/zxtres/wiki/wiki[ZXTRES official wiki]. -Without the previous work of all of these people (and more), this manual wouldn't exist. +Without the previous work of all these people (and more) this manual wouldn't exist. <<< -=== Ports and Connectors +=== Ports and connectors [.text-center] image:img/ZXTRESfront.jpg[scaledwidth=90%] @@ -48,19 +49,19 @@ image:img/ZXTRESfront.jpg[scaledwidth=90%] [align="center",width="80%",cols="1,4"] |=== |1 -|Left Joystick Port +|Left joystick Port |2 -|microSD Card Slot +|microSD card Slot |3 -|Right Joystick Port +|Right joystick Port |4 -|Power Socket +|Power socket |5 -|Power Switch +|Power switch |6 -|PS/2 Keyboard Port +|PS/2 keyboard port |7 -|PS/2 Mouse Port +|PS/2 mouse port |=== <<< @@ -71,19 +72,19 @@ image:img/ZXTRESback.jpg[scaledwidth=90%] [align="center",width="80%",cols="1,4"] |=== |8 -|Audio In +|Audio in |9 -|Audio Out +|Audio out |10 -|USB Port (Only to use with middleboard installed) +|USB port (only for use with middleboard installed) |11 -|RGB/VGA Out +|RGB/VGA out |12 |JTAG access |13 -|Expansion Port +|Expansion port |14 -|DisplayPort Out +|DisplayPort out |=== [.text-center] @@ -99,70 +100,70 @@ image:img/ZXTRESbottom.jpg[scaledwidth=90%] <<< -=== Initial Setup +=== Initial setup -In order to be able to set up and use a ZXTRES you need, at least, the following: +To set up and use the ZXTRES you need at least: -- A USB charger, a TV or other device that provides USB power (5VDC and, at least, 1A). The connector is a coaxial jack "barrel" plug of 5.5 mm outer diameter and 2.1 mm inner diameter, with positive polarity (center positive) -- A DisplayPort, VGA or RGB cable and compatible display (the RGB connection can also be used with a VGA to SCART adapter and connected to compatible TVs). +- DisplayPort, VGA or RGB cable and compatible display (the RGB connection can also be used with a VGA to SCART adapter and connected to compatible TVs). - PS/2 keyboard +- USB charger, TV or other device that provides USB power (5VDC and at least 1A). The connector is a coaxial jack "barrel" plug of 5.5mm outer diameter and 2.1mm inner diameter with positive polarity (centre positive) [TIP] ==== -It is important that the source has stable voltage and sufficient current, or erratic behavior (keyboard or DisplayPort failure, etc.) may occur. Some keyboards or peripherals might need a similar power supply but with 2 amps or more. +It's important that the source has stable voltage and sufficient current or erratic behaviour may occur (the keyboard or DisplayPort may fail and so on). Some keyboards or peripherals may require a similar power supply but with 2A or more. [.text-center] image:img/powerConnector.png[scaledwidth=20%] ==== -In order to take advantage of its full potential, you may also have: +To take advantage of its full potential you may also need: -- A microSD card, 32GB capacity or less -- PC speakers to connect to the audio output, or a stereo jack converter to two red/white RCA connectors to connect to the TV -- At least one standard Atari joystick, such as a Megadrive DB9 gamepad -- A PS/2 mouse -- An audio cable with a stereo 3.5 mm jack on one side, and both audio channels split into two mono outputs on the other side, if you want to use an audio player and/or recorder, like, for example, a Miniduino (<<#_miniduino,see more info later>>)., a PC/Mac/Raspberry PI, etc. or a https://en.wikipedia.org/wiki/Cassette_tape[cassette tape] recorder/player. The right sound channel is used as input (EAR) and the left channel can be used as output (MIC). +- Atari standard joystick such as a Sega Mega Drive (Gensis) game pad. +- Audio cable with a stereo 3.5mm jack on one side and both audio channels split into two mono outputs on the other side if you want to use an audio player or recorder such as a Miniduino (<<#_miniduino,see more information later>>), a modern computer or a https://en.wikipedia.org/wiki/Cassette_tape[cassette tape recorder]. The right sound channel is used as input (EAR) and the left channel can be used as output (MIC). +- microSD card 32GB capacity or less. +- PS/2 mouse. +- Speakers to connect to the audio output or a stereo jack converter to two red and white RCA connectors to connect to a TV, <<< ==== microSD card formatting -This table shows special requirements of the cores that use the microSD card. +This table shows the requirements of cores that use the microSD card. [align="center",width="100%",%header,cols="4a,1a,1a,1a,3a,2a,4a,5a",options="header"] |=== |[.small]#Core#|[.small]#FAT16#|[.small]#FAT32#|[.small]#+3e#|[.small]#Primary Partition Type#|[.small]#Extra Partitions#|[.small]#Access#|[.small]#Notes# +|[.small]#ColecoVision#|[.small]#Yes#|[.small]#Yes#|[.small]#No#|[.small]#Any#|[.small]#No#|[.small]#Only ROMs (`ROM`)#| +|[.small]#Neo-Geo#|[.small]#Yes#|[.small]#Yes#|[.small]#No#|[.small]#Any#|[.small]#No#|[.small]#Only ROMs (`.neo`)#|Requires BIOS +|[.small]#ZX81#|[.small]#Yes#|[.small]#Yes#|[.small]#No#|[.small]#Any#|[.small]#No#|[.small]#Only images (`O` and `P`)#| +|[.small]#zxsp#|[.small]#Yes#|[.small]#Yes#|[.small]#Yes#|[.small]#Any#|[.small]#No#|[.small]#Disk Images (`VHD`)#|Requires ROM |[.small]#ZX Spectrum EXP#|[.small]#Yes#|[.small]#Yes#|[.small]#Yes#|[.small]#Any#|[.small]#Yes#|[.small]#Full#|[.small]#Using SPI Flash esxdos# -|[.small]#ColecoVision#|[.small]#Yes#|[.small]#Yes#|[.small]#No#|[.small]#Any#|[.small]#No#|[.small]#Only ROMs (`.ROM`)#| -|[.small]#Neo-Geo#|[.small]#Sí#|[.small]#Yes#|[.small]#No#|[.small]#Any#|[.small]#No#|[.small]#Only ROMs (`.neo`)#|Needs BIOS -|[.small]#ZX81#|[.small]#Yes#|[.small]#Yes#|[.small]#No#|[.small]#Any#|[.small]#No#|[.small]#Only images (`.o` and `.p`)#| -|[.small]#zxsp#|[.small]#Yes#|[.small]#Yes#|[.small]#Yes#|[.small]#Any#|[.small]#No#|[.small]#Disk Images (`.vhd`)#|Needs ROM |=== [NOTE] ==== -FAT16 partitions have a maximum size of 4GB +FAT16 partitions have a maximum size of 4GB. ==== [CAUTION] ==== -When naming a partition which will be used with esxdos, it's important not to use the same of any directory inside, or an access error will happen when trying to see the contents (e.g. do not name the partition as `BIN`, `SYS` or `TMP`). +When naming a partition to be used with esxDOS you can't also use it as a folder name on that partitio. Otherwise an error occurs when trying to access the contents (don't name the partition as `BIN` `SYS` or `TMP`). ==== [TIP] ==== -The Spectrum core can also have <<#_microsd_advanced_format_3e,the first partition in +3DOS format, and then the second one in FAT16 or FAT32 format>> to use with a +3e ROM. +The ZX Spectrum core can also have <<#_microsd_advanced_format_3e,the first partition in +3DOS format and then the second one in FAT16 or FAT32 format>> to use with the +3e ROM. ==== <<< ===== Windows -For simple configurations, and cards of the right size (less than 2GB for FAT16 or less than 32GB for FAT32), you can use https://www.sdcard.org/downloads/formatter/[the official formatting tool of the SD Association ]. +For simple configuration of microSD cards of the correct size (less than 2GB for FAT16 or less than 32GB for FAT32) you can use https://www.sdcard.org/downloads/formatter/[the official formatting tool of the SD Association ]. -For other, more complex, configurations, and depending on operating system version, you may use the command line tool `diskpart` or Windows Disk Managemente GUI. +For other more complex configurations and depending on operating system version you can use the command line tool `diskpart` or the Windows Disk Management GUI. -For example, to format a card, shown as disk 6 when executing `list disk` from `diskpart`, with only one FAT16 partition (if the card size is less than 4GB): +For example, to format a microSD card shown as disk 6 when executing `list disk` from `diskpart` with only one FAT16 partition (if the microSD card size is less than 4GB): [source] ---- @@ -174,7 +175,7 @@ format FS=FAT label=ZXTRES exit ---- -To create two FAT 16 partitions (e.g. to use MSX core) and have the rest of space as another FAT32 partition (for cards more than 8GB in size): +To create two FAT16 partitions (for example to use MSX core) and have the rest of space as another FAT32 partition (for microSD cards more than 8GB in size): [source] ---- @@ -191,7 +192,7 @@ format fs=FAT32 label=DATA quick exit ---- -To create one FAT32 4GB partition (e.g. to use with Amstrad CPC 6128 core), and then have the rest of space available as a second FAT32 partition (for cards more than 4GB in size): +To create one FAT32 4GB partition (for example to use with Amstrad CPC 6128 core) and then have the rest of space available as a second FAT32 partition (for microSD cards more than 4GB in size): [source] ---- @@ -208,13 +209,13 @@ exit <<< -===== MacOS +===== macOS -For simple configurations, and cards of the right size (less than 2GB for FAT16 or less than 32GB for FAT32), you can use https://www.sdcard.org/downloads/formatter/[the official formatting tool of the SD Association ] or Disk Utility, which is included with the operating system. +For simple configuration of microSD cards of the correct size (less than 2GB for FAT16 or less than 32GB for FAT32) you can use https://www.sdcard.org/downloads/formatter/[the official formatting tool of the SD Association ] or Disk Utility which is included with the operating system. -In other case, you should use the command line. +In other case you should use the command line. -For example, to format a card, shown as `disk6`, with only one FAT16 partition (if the card size is less than 2GB): +For example, to format a microSD card shown as `disk6` with only one FAT16 partition (if the microSD card size is less than 2GB): [source,shell] ---- @@ -222,7 +223,7 @@ diskutil unmountDisk /dev/disk6 diskutil partitionDisk /dev/disk6 MBR "MS-DOS FAT16" ZXTRES R ---- -To split it into two FAT16 partitions of the same size (if the card size is 4GB or less): +To split it into two FAT16 partitions of the same size (if the microSD card size is 4GB or less): [source,shell] ---- @@ -230,7 +231,7 @@ diskutil unmountDisk /dev/disk6 diskutil partitionDisk /dev/disk6 MBR "MS-DOS FAT16" ZXTRES 50% "MS-DOS FAT16" EXTRA 50% ---- -To create two FAT 16 partitions (e.g. to use MSX core) and have the rest of space as another FAT32 partition (for cards more than 8GB in size): +To create two FAT16 partitions (for example to use MSX core) and have the rest of space as another FAT32 partition (for microSD cards more than 8GB in size): [source,shell] ---- @@ -242,12 +243,12 @@ sudo newfs_msdos -F 16 -v EXTRA -b 4096 -c 128 /dev/rdisk6s2 [NOTE] ==== -`diskutil` cannot create FAT16 partitions which are bigger than 2G and also format them. That's why, in this example, after only creating the partitions, we have to format them. +`diskutil` can't create FAT16 partitions that are bigger than 2GB and then format them. That's why in this example you must format them only after creating the partitions. ==== <<< -To create one FAT32 4GB partition (e.g. to use with Amstrad CPC 6128 core), and then have the rest of space available as a second FAT32 partition (for cards of more than 4GB): +To create one FAT32 4GB partition (for example to use with the Amstrad CPC 6128 core) and then make the rest of space available as a second FAT32 partition (for microSD cards of more than 4GB): [source,shell] ---- @@ -257,7 +258,7 @@ diskutil partitionDisk /dev/disk6 MBR "MS-DOS FAT32" ZXTRES 4G "MS-DOS FAT32" EX [NOTE] ==== -In this example, since the partition has a size of exactly 4G, MacOS will use a cluster size of 4096, which is the one neede for the Amstrad CPC 6128 core. For a smaller size, you may have to format again the first partition with some commands like these: +In this example because the partition has a size of exactly 4GB, macOS uses a cluster size of 4096 bytes which is the one required for the Amstrad CPC 6128 core. For a smaller size you may need to format the first partition again. For example: [source,shell] ---- @@ -268,7 +269,7 @@ newfs_msdos -F 32 -v ZXTRES -b 4096 /dev/rdisk6s1 [TIP] ==== -The Spotlight feature in MacOS you to search the items on the microSD card, creating a number of hidden files. You can disable the indexing with these commands (assuming that the SD partition is named `ZXTRES`): +The Spotlight feature in macOS enables you to search the items on the microSD card creating a number of hidden files. You can switch off the indexing with these commands (assuming that the SD partition is called `ZXTRES`): [source,shell] ---- @@ -285,9 +286,9 @@ cd - ===== Linux -There are a lot of tools for Linux that can format and/or partition a microSD card (`fdisk`, `parted`, `cfdisk`, `sfdisk` or `GParted` to name a few). It should only be taken into account that the partition scheme must always be MBR, and the first partition (the one that will be used for esxdos) must be primary partition. +There are many tools for Linux that can format or partition a microSD card (`fdisk` `parted` `cfdisk` `sfdisk` or `GParted` to name a few). Note that the partition scheme must always be MBR and the first partition (the one to be used for esxDOS) must be the primary partition. -For example, to format a card, shown as `sdc`, with only one FAT16 partition (if the card size is less than 4GB): +For example to format a microSD card shown as `sdc` with only one FAT16 partition (if the microSD card size is less than 4GB): [source,shell] ---- @@ -325,7 +326,7 @@ Device Boot Start End Sectors Size Id Type /dev/sdc1 62 31116288 31116288 984,9M 6 FAT16 ---- -Formatear la partición FAT (requiere permisos de root) +Format a FAT partition (requires root permission): [source,shell] ---- @@ -338,24 +339,26 @@ sudo mkfs.fat -F 16 -n ZXTRES -s 128 /dev/sdc1 ==== PS/2 keyboard -The keyboard map (physical keys of the keyboard assignment to the keystrokes that are presented to the different cores) is changed using the `Advanced` menu of the BIOS. There are three different maps to choose from: Spanish (default), English, and Spectrum (advanced). +The keyboard map (physical keys of the keyboard assignment to the keystrokes that are presented to the different cores) is changed using the `Advanced` menu of the BIOS. There are three different maps to choose from: Spanish (default), English and Spectrum (advanced). -You can also change it using the `keymap` utility. Inside `/bin` you have to create a directory named `keymaps` and copy inside the keyboard map files that you want to use. For example, to switch to the US map you have to write `.keymap us` from esxdos. +You can also change it using the `keymap` utility. Inside `/bin` you can create a folder called `keymaps` and copy the keyboard map files that you want to use inside it. For example to switch to the US map, enter `.keymap us` from esxDOS. -For the map to be preserved after a master reset, it has to be selected as `Default` in the BIOS. +For the map to be preserved after a hard reset it must be selected as `Default` in the BIOS. -For more information, see https://www.zxuno.com/forum/viewtopic.php?f=37&t=208[this message in the ZX-Uno forum]. +For more information see https://www.zxuno.com/forum/viewtopic.php?f=37&t=208[this message in the ZX-Uno forum]. -==== Spanish - -[.text-center] -image:./img/keyboardEsp.png[scaledwidth=70%] +Note, <<#_se_basic_iv>> uses its own native system to set the keyboard map and has its own https://github.com/source-solutions/sebasic4/wiki/Keyboard-layouts[layouts]. ==== English [.text-center] image:./img/keyboardEng.png[scaledwidth=70%] +==== Spanish + +[.text-center] +image:./img/keyboardEsp.png[scaledwidth=70%] + ==== Spectrum [.text-center] @@ -365,50 +368,49 @@ image:./img/keyboardAV.png[scaledwidth=70%] ==== Special keys and buttons -Special keys which can be used during startup: +Special keys that can be used during startup: -- `F2` Enter BIOS setup -- `Caps Lock` or `Cursor down` or, if a joystick is connected, pressing `down`: Core selection menu -- `Esc`, or if a joystick with two or more fire buttons is connected, pressing the 2nd fire button: ZX Spectrum core ROM selection menu -- `R`: Loads the Spectrum core ROM in "real" mode, disabling esxdos, new graphics modes, etc. -- `/` (numeric keyboard): Load the default ZX Spectrum core ROM in "root" mode -- Number from `1` to `9`: Load the core in the flash location corresponding to that number. On the latest BIOS versions, `9` is used to load the core installed to the temporary slot used by the <<#_bob_fossil_browser,ZX3 plugin>> +- `Esc` or joystick button `2` (if a joystick with two or more fire buttons is connected): ZX Spectrum core ROM selection menu. +- `F2`: Enter BIOS setup. +- `1` to `9`: Load the core in the flash location corresponding to that number. On the latest BIOS versions `9` is used to load the core installed to the temporary slot used by the <<#_bob_fossil_browser,ZX3 plugin>>. +- `R`: Load the ZX Spectrum core ROM in "real" mode; switching off esxDOS, new graphics modes and so on. +- `Caps Lock`, `Cursor Down` or joystick `down` (if connected): Core selection menu. Special keys that can be used while running the main core (ZX Spectrum): -- `Esc`: BREAK -- `F2`: Edit -- `F5`: NMI -- `F7`: Play or pause when playing .PZX files -- `F8`: Rewind .PZX file to the previous mark -- `F10`: Graph -- `F12`: Turbo Boost. Speeds up CPU to 28MHz -- `Ctrl+Alt+Backspace`: Hard reset. Backspace is the delete key, located in the top-right portion of the keyboard, above `Enter` -- `Ctrl+Alt+Supr`: Soft reset -- `Scroll Lock`: Switches between RGB and VGA video modes. DisplayPort is always enabled -- `Home`: Switches between the several DisplayPort deinterlacing modes (Blend, Off, Auto and On). This option is only available for ZXTRES+ and ZXTRES++ core versions -- `End`: Select one of the monochrome color modes +- `Esc`: Break. +- `F2`: Edit. +- `F5`: NMI. +- `F7`: Play or pause when playing `PZX` files. +- `F8`: Rewind a `PZX` file to the previous mark. +- `F10`: Graph(ics). +- `F12`: Turbo boost (speeds up CPU to 28MHz). +- `Ctrl+Alt+Backspace`: Hard reset. Backspace is the delete key located in the top-right portion of the keyboard above `Enter`. +- `Ctrl+Alt+Supr`: Soft reset. +- `Scroll Lock`: Switches between RGB and VGA video modes. DisplayPort is always enabled. +- `Home`: Switches between the several DisplayPort deinterlacing modes (Blend Off Auto and On). This option is only available for ZXTRES+ and ZXTRES++ core versions. +- `End`: Select one of the monochrome colour modes. <<< -=== esxdos +=== esxDOS -https://esxdos.org/index.html[esxdos] is a firmware for the DivIDE/DivMMC hardware interfaces (which ZXTRES implements). This allows access to storage devices such as a microSD card. It includes commands similar to those of UNIX, although to use them you must precede them with a period, for example `.ls`,` .cd`, `.mv`, etc. +https://esxdos.org/index.html[esxDOS] is a firmware for the divIDE/divMMC hardware interfaces (that ZXTRES implements). This enables access to storage devices such as a microSD card. It includes commands similar to those of UNIX although to use them you must precede them with a dot (`.`) for example `.ls`, `.cd`, `.mv` and so on. -For it to work, it is necessary to include the corresponding files in the first partition of the microSD card. +For it to work it's necessary to include the corresponding files in the first partition of the microSD card. -At the time of writing this document, the version included with ZXTRES is 0.8.9, and it can be downloaded from the official website https://www.esxdos.org/files/esxdos086.zip[at this link]. +At the time of writing this document the version included with ZXTRES is 0.8.9 and it can be downloaded from the https://www.esxdos.org/files/esxdos086.zip[official website]. -Once downloaded and extracted, you have to copy the directories `BIN`, `SYS` and `TMP`, and all of their content, to the root of first partition of the microSD card. +After you've downloaded and extracted the `ZIP` archive, you must copy the folders `BIN`, `SYS` and `TMP` and all their contents to the root of first partition of the microSD card. -If everything has been done correctly, when you turn on the ZXTRES Spectrum core, you will see how esxdos detects the card and loads the necessary components to work. +If everything was done correctly, when you start the ZX Spectrum core you'll see esxDOS detect the microSD card and load the required components to work. [.text-center] image:./img/esxdos.png[scaledwidth=70%] <<< -It is also recommended to add the specific esxdos commands for ZXTRES. These can be obtained from the project source page (https://github.com/zxdos/zxuno/tree/master/SD[here], https://github.com/zxdos/zxuno/tree/master/[here] and https://guest:zxuno@svn.zxuno.com/svn/zxuno/software/upgrade[here]), and are as follows: +You should add the ZXTRES-specific esxDOS commands. These can be obtained from the project source page (https://github.com/zxdos/zxuno/tree/master/SD[here], https://github.com/zxdos/zxuno/tree/master/[here] and https://guest:zxuno@svn.zxuno.com/svn/zxuno/software/upgrade[here]): back16m backzx2 @@ -423,7 +425,6 @@ It is also recommended to add the specific esxdos commands for ZXTRES. These can loadtap playmid playrmov - romsback romsupgr upgr16m upgrzx2 @@ -431,7 +432,7 @@ It is also recommended to add the specific esxdos commands for ZXTRES. These can zxuc zxunocfg -<<#_zxtres_commands,It is explained later> what each of them does. +<<_#_zxtres_commands,It's explained later>> what each of these commands does. <<< @@ -440,18 +441,17 @@ It is also recommended to add the specific esxdos commands for ZXTRES. These can [.text-center] image:./img/boot_zxtres.png[scaledwidth=80%] -Pressing the `F2` key during boot will access the BIOS setup. The BIOS firmware is the first program that runs when the ZXTRES is turned on. The main purpose of BIOS is to start and test the hardware and load one of the installed cores. +Press the `F2` key during boot to access the BIOS setup. The BIOS firmware is the first program that runs when the ZXTRES is powered on. The main purpose of BIOS is to start and test the hardware and load one of the installed cores. -Using left and right cursor keys, you can navigate through the BIOS setup screens. With up and down keys you can choose the different elements of each screen and, with the `Enter` key, it is possible to activate and choose the options for each of these. `Esc` key is used to close open option windows without applying any action. +Using left and right cursor keys you can navigate through the BIOS setup screens. With up and down keys you can choose the different elements of each screen. With the `Enter` key you can activate and choose the options for each of these. The `Esc` key is used to close open option windows without applying any action. -Other special keys which can be used during startup: +Other special keys that can be used during startup: -- `F2` Enter BIOS setup -- `Caps Lock` or `Cursor down` or, if a joystick is connected, pressing `down`: Core selection menu -- `Esc`, or if a joystick with two or more fire buttons is connected, pressing the 2nd fire button: ZX Spectrum core ROM selection menu -- `R`: Loads the Spectrum core ROM in "real" mode, disabling esxdos, new graphics modes, etc. -- `/` (numeric keyboard): Load the default ZX Spectrum core ROM in "root" mode -- Number from `1` to `9`: Load the core in the flash location corresponding to that number. On the latest BIOS versions, `9` is used to load the core installed to the temporary slot used by the <<#_bob_fossil_browser,ZX3 plugin>> +- `Esc` or joystick button `2` (if a joystick with two or more fire buttons is connected): ZX Spectrum core ROM selection menu. +- `F2` Enter BIOS setup. +- `1` to `9`: Load the core in the flash location corresponding to that number. On the latest BIOS versions `9` is used to load the core installed to the temporary slot used by the <<#_bob_fossil_browser,ZX3 plugin>>. +- `Caps Lock` or `Cursor down` or joystick `down` (if connected): Core selection menu. +- `R`: Load the ZX Spectrum core ROM in "real" mode, switching off esxDOS, new graphics modes and so on. <<< @@ -460,32 +460,32 @@ Other special keys which can be used during startup: [.text-center] image:img/bios.png[scaledwidth=70%] -In the first configuration screen, in addition to being able to run several tests, you can define the default behavior for the following: +From the _Main_ screen you can run several tests and define the default behaviour for: -- Boot Timer: Sets how long the boot screen is available (or hiding it completely) -- Check CRC: Check ROM integrity when loading (more secure) or bypassing it (faster) -- Keyboard -- Timing: ULA Behaviour (48K, 128K, Pentagon Modes) -- Contended -- DivMMC -- DivMMC NMI Support -- New Graphic Modes Support (ULAPlus, Timex, Radastan) +- Boot Timer: Sets how long the boot screen is available (or hiding it completely). +- Check CRC: Check ROM integrity when loading (more secure) or bypassing it (faster). +- Keyboard: Set keyboard map. +- Timing: ULA Behaviour (48K, 128K or Pentagon). +- Contended: Set lower RAM contention (on or off). +- DivMMC: Enable or switch of divMMC. +- NMI-DivMMC: Enable or swtich off divMMC NMI support (used by the NMI browser). +- New Graphic Modes: (ULAplus, Timex, Radastan). -More technical information can be found on https://www.zxuno.com/wiki/index.php/ZX_Spectrum[de ZX-Uno Wiki]. +More technical information can be found at the https://www.zxuno.com/wiki/index.php/ZX_Spectrum[ZX-Uno Wiki]. ==== ROMs [.text-center] image:img/bios2.png[scaledwidth=70%] -The second screen shows the installed ZX Spectrum ROMs. You can reorder (Move Up, Move Down), rename or delete each of them, as well as choose the one that will be loaded by default at startup (Set Active ). +The _ROMs_ screen shows the installed ZX Spectrum core ROMs. You can reorder (move up or move down), rename or remove each of them. You can also choose the one that is loaded by default at startup (Set Active ). ==== Upgrade [.text-center] image:img/bios3_zxtres.png[scaledwidth=70%] -_Upgrade_ screen is used to perform the different updates of the Flash memory content: esxdos, BIOS, Cores, etc. (see <<#_upgrade,the section corresponding to upgrades>> for more information). +The _Upgrade_ screen is used to perform updates to the Flash memory content; esxDOS, BIOS, cores and so on. For more information, see the <<#_upgrade,section corresponding to upgrades>>. <<< @@ -494,7 +494,7 @@ _Upgrade_ screen is used to perform the different updates of the Flash memory co [.text-center] image:img/bios4_zxtres.png[scaledwidth=70%] -In the _Boot_ screen you can choose which one of the installed cores is loaded by default at startup. +In the _Boot_ screen you can choose which of the installed cores is loaded by default at startup. <<< @@ -503,16 +503,16 @@ In the _Boot_ screen you can choose which one of the installed cores is loaded b [.text-center] image:img/bios5_zxtres.png[scaledwidth=70%] -The Advanced configuration screen is used to edit the following settings: +From the _Advanced_ screen you can configure: -- Keyboard layout (Keyb Layout): See <<#_keyboard,the corresponding section>> for more information) -- Joystick behavior connected to the right port and also the emulated joystick using the numeric keypad (Joy Keypad): Kempston, Sinclair Joystick 1, Sinclair Joystick 2, Protek, Fuller or simulate the keys `Q`,` A`, `O`,` P`, `Space` and `M` -- Behavior of a joystick connected to the left port (Joy DB9): Kempston, Sinclair Joystick 1, Sinclair Joystick 2, Protek, Fuller or simulate the keys `Q`,` A`, `O`,` P`, `Space` and `M` -- Video output: PAL, NTSC or VGA (DisplayPort is always active) -- Scanline simulation: Enabled or Disabled -- VGA horizontal frequency: 50, 51, etc. -- CPU speed: Normal (1x) or accelerated (2X, 3X, etc.) -- Csync: Spectrum or PAL +- Keyboard layout (Keyb Layout): For more informaiton, see <<#_keyboard,the corresponding section>>. +- Joystick behaviour connected to the right port and also the emulated joystick using the numeric keypad (Joy Keypad): Kempston, Sinclair 1, Sinclair 2, Protek, Fuller or simulate the keys `Q`,` A` `O`,` P` `Space` and `M`. +- behaviour of a joystick connected to the left port (Joy DE9): Kempston, Sinclair 1, Sinclair 2, Protek, Fuller or simulate the keys `Q`,` A` `O`,` P` `Space` and `M`. +- Video output: PAL, NTSC or VGA (DisplayPort is always active). +- Scanline simulation: enabled or switched off. +- VGA horizontal frequency: 50, 51 and so on. +- CPU speed: Normal (1X) or accelerated (2X, 3X and so on). +- Csync: Spectrum or PAL. <<< @@ -521,70 +521,81 @@ The Advanced configuration screen is used to edit the following settings: [.text-center] image:img/bios6.png[scaledwidth=70%] -Finally, from the last screen you can: +From the _Exit_ screen you can: -- Exit BIOS configuration saving changes (in some cases a power reset is also neeeded) -- Discard changes and exit -- Save changes without exiting -- Discard Changes +- Exit BIOS configuration saving changes (in some cases a power cycle is also required). +- Discard changes and exit. +- Save changes without exiting. +- Discard changes. == ZX Spectrum -The main core is the one implementing a ZX Spectrum computer. This core is special, and it cannot be replaced for another that is not a ZX Spectrum, since the ZXTRES uses it for its operation. +The main core is the one implementing a ZX Spectrum computer. This core is special and can't be replaced with another that's not a ZX Spectrum because the ZXTRES uses it for its operation. -These are some of its main characteristics: +Some of its main characteristics include: -- ZX Spectrum 48K, 128K, Pentagon and Chloe 280SE implementation -- ULA with ULAplus, Timex and Radastan modes (including hardware scroll and selectable palette group) -- Ability to disable memory contention (for Pentagon 128 compatibility) -- Ability to choose the keyboard behavior (issue 2 or issue 3) -- Possibility to choose the timing of the ULA (48K, 128K or Pentagon) -- Control of screen framing, configurable for type of timing, and possibility to choose between original Spectrum synchronisms or progressive PAL standard. -- Timex horizontal MMU support with HOME, DOC and EXT banks in RAM. -- Programmable raster interruption in line number, for any TV line. -- Possibility of activating/deactivating memory bank management registers, for better compatibility with each implemented model -- Ability to activate / deactivate the devices incorporated into the core to improve compatibility with certain programs -- ZXMMC and DIVMMC support for + 3e, esxdos and compatible firmwares -- Turbo Sound support -- SpecDrum support -- Each channel A, B, C of the two AY-3-8912, beeper and SpecDrum chips can be directed to the left, right, both or neither outputs, allowing the implementation of configurations such as ACB, ABC, etc. +- ZX Spectrum 48K, 128K, +3, Pentagon and Chloe 280SE implementation. +- ULA with ULAplus, Timex and Radastanian modes (including hardware scroll and selectable palette group). +- Memory contention select (for Pentagon 128 compatibility). +- Keyboard behaviour select (issue 2 or issue 3). +- ULA timing select (48K, 128K or Pentagon). +- Control of screen framing configurable for type of timing and possibility to choose between original Spectrum synchronisms or progressive PAL standard. +- Timex horizontal MMU support with HOME, DOC and EX banks in RAM. +- Programmable raster interrupt on any TV line. +- Memory bank management register select for better compatibility with each implemented model. +- Activate or deactivate the devices incorporated into the core to improve compatibility with certain programs. +- ZXMMC and divMMC support for +3e, esxDOS and compatible firmwares (such as UnoDOS 3). +- TurboSound-AY support. +- SpecDrum support. +- Each channel (A, B and C) of the two AY-3-8912, beeper and SpecDrum chips can be directed to the left, right, both or neither outputs enabling the implementation of configurations such as ACB, ABC and so on. - Real joystick and keyboard joystick support with Kempston, Sinclair 1 and 2, Cursor, Fuller and QAOPSpcM protocol. -- Turbo mode support at 7MHz, 14MHz, 28MHz -- Keyboard support (PS/2 protocol) and user-configurable mapping from within Spectrum itself. +- Turbo mode support at 7MHz, 14MHz and 28MHz. +- Keyboard support (PS/2 protocol) and user-configurable mapping from within the ZX Spectrum core itself. - PS/2 mouse support emulating the Kempston Mouse protocol. -- Possibility of video output in RGB 15kHz, VGA and DisplayPort. -- User selectable vertical refresh rate to improve compatibility with VGA monitors -- Multicore boot support: from the Spectrum you can select an address of the SPI Flash and the FPGA will load a core from there -- Different colour modes including monochrome -- I^2^S and DeltaSigma audio output -- MIDI Support (General MIDI) via middleboard -- `PZX` file loading from SD emulating tape audio -- Multiple deinterlacing modes for DisplayPort including an option to blend the colours. This is only available for ZXTRES+ and ZXTRES++ core versions +- Video output in RGB 15kHz, VGA and DisplayPort. +- User selectable vertical refresh rate to improve compatibility with VGA monitors. +- Multicore boot support: from the ZX Spectrum core you can select an address of the SPI Flash and the FPGA will load a core from there. +- Different colour modes including monochrome. +- I^2^S and DeltaSigma audio output. +- MIDI Support (General MIDI) using the middleboard. +- `PZX` file loading from microSD card emulating tape audio. +- Multiple deinterlacing modes for DisplayPort including an option to blend the colours. This is only available for ZXTRES+ and ZXTRES++ core versions. <<< === ROMs -The ZX Spectrum core can be initialized using different ROM versions (48K, 128K, Plus 2, etc.). These are stored in the flash memory of the ZXTRES, and you can choose which one to load by pressing the `Esc` key during boot. You can also define the ROM that you want to load by default using the BIOS setup. +The ZX Spectrum core can be initialized using different ROM versions (48K, 128K, +2 and so on). These are stored in the flash memory of the ZXTRES and you can choose which one to load by pressing the `Esc` key during boot. You can also define the ROM that you want to load by default using the BIOS setup. -See the <<#_roms_3,updates section>> for more information on how to expand or modify the ROMs stored in flash memory. +For more information on how to expand or modify the ROMs stored in flash memory, see the <<#_roms_3,updates section>>. ==== DerbyPro -https://www.facebook.com/groups/DerbyPro[DerbyPro or Derby{pp}] is an enhanced firmware ROM for the ZX Spectrum, based on v1.4 of the Derby development ROM. The Spectrum 128 (codename "Derby") was a Spanish machine commissioned by Investronica and launched in 1985. It came with a keypad that provided additional editing keys. In 1986, the UK version came out with a simplified version of 128 BASIC and no keypad. Derby++ is developed from the Spanish ROM to include the benefits of both versions, without the drawbacks, and support for new hardware developments. +https://www.facebook.com/groups/DerbyPro[DerbyPro or Derby{pp}] is an enhanced firmware ROM for the ZX Spectrum based on v1.4 of the Derby development ROM. The Spectrum 128 (codename "Derby") was a Spanish machine commissioned by Investronica and launched in 1985. It came with a keypad that provided additional editing keys. In 1986 the UK version came out with a simplified version of 128 BASIC and no keypad. Derby++ is developed from the Spanish ROM to include the benefits of both versions without the drawbacks and support for new hardware developments. + +Features include: + +- 100% binary compatible 48K mode. +- 6-channel PLAY commmand. +- Access the esxDOS NMI browser from the boot menu. +- Debugged 128 BASIC with additinoal commands and full scren string editor. +- esxDOS support in 128 BASIC. +- Menu access to TR-DOS. +- PALETTE command for ULAplus. +- Run most Spectrum software without the need to switch configuration in the BIOS. You can download the ROM, a user manual and other files from the https://www.facebook.com/groups/DerbyPro[official Facebook Public Group]. -Since it is a 64K ROM with support for new hardware, these flags can be used when <<#_zx123_tool,adding it to the SPI flash>>: +Because it's a 64K ROM with support for new hardware these flags can be used when <<#_zx123_tool,adding it to the SPI flash>>: [align="center",width="60%",%header,cols=2*] |=== |Flag |Meaning |`d` -|Enable DivMMC +|Enable divMMC |`n` -|Enable NMI DivMMC (esxdos Menu) +|Enable NMI divMMC (esxDOS Menu) |`t` |Use 128K timings |=== @@ -593,52 +604,52 @@ Since it is a 64K ROM with support for new hardware, these flags can be used whe ==== CargandoLeches -CargandoLeches is a set of ZX Spectrum ROMs that started as a project to load games in any Spectrum model 15-20x faster. No tape is needed, but a digital audio source, as a computer, mobile device, MP3 player, etc. The new ROM detects the loading method and reverts to the original ROM code if needed. This is handled transparently, with no user or program intervention. +CargandoLeches is a set of ZX Spectrum ROMs that started as a project to load games in any Spectrum model 15 to 20 times faster. No tape is needed but a digital audio source such as a computer, mobile device, MP3 player and so on is required. The new ROM detects the loading method and reverts to the original ROM code if required. This is handled transparently with no user or program intervention. -Since version 2.0 the project changed from a single ROM to more, each one with different options. This way, you can choose a different mix of options that may include: +From version 2.0 the project changed from a single ROM to more; each one with different options. This way you can choose a different mix of options that may include: -- Ultrafast loading -- Reset & Play (After a sofware reset of the core, the system is ready to load from tape) -- POKE editor -- Enable or disable Sinclair BASIC token expansion +- Enable or switch off Sinclair BASIC token expansion. +- POKE editor. +- Reset & Play (After a sofware reset of the core the system is ready to load from tape). +- Ultrafast loading. The whole ROM set is available to download from the repository in GitHub https://github.com/antoniovillena/CargandoLeches/tree/master/binaries[here]. -Depending on which ROM you choose, the flags when <<#_zx123_tool,adding to the SPI flash>> may vary. For example, for the ROM `48le_ea_re_po` (with all features enabled), these flags can be used (we cannot enable NMI DivMMC since the POKE editor will use it): +Depending on which ROM you choose the flags when <<#_zx123_tool,adding to the SPI flash>> may vary. For example, for the ROM `48le_ea_re_po` (with all features enabled) these flags can be used (you can't enable NMI-DivMMC because the POKE editor uses the NMI): [align="center",width="60%",%header,cols=2*] |=== |Flag |Meaning |`d` -|Enable DivMMC +|Enable divMMC |`h` -|Disable ROM high bit (1FFD bit 2) +|Switch off ROM high bit (1FFD bit 2) |`l` -|Disable ROM low bit (7FFD bit 4) +|Switch off ROM low bit (7FFD bit 4) |`x` -|Disable Timex mode +|Switch off Timex mode |=== ===== POKEs When using a ROM with POKE option enabled: -. Once the game is loaded, after pressing NMI (`F5`) a field will appear in the upper left corner of the screen -. Enter the POKE address and press `Enter` -. Enter the POKE value and press `Enter` again -. Repeat steps 2. and 3. until all the desired POKEs are entered. To finish and return to the game, press `Enter` twice +. After the game is loaded, press `F5` (NMI button). A dialog is displayed in the upper left corner of the screen +. Enter the POKE address and press `Enter`. +. Enter the POKE value and press `Enter` again. +. Repeat steps 2 and 3 until all desired POKEs are entered. To finish and return to the game press `Enter` twice. <<< ===== Preparing ultrafast loading tapes -The ROMs with ultrafast loading enabled, need special tape audio data which is made from normal loading `TAP` files, without protections or turbo loading. +The ROMs with ultrafast loading enabled need special tape audio data that is made from normal loading `TAP` files without protections or turbo loading. -In order to create an ultrafast loading tape you need `leches` and `CgLeches` command line utilities. Those can be obtained, for Windows, from the -https://github.com/antoniovillena/CargandoLeches/tree/master/binaries[official repository]. You can also obtain an unofficial version for MacOS from https://github.com/kounch/CargandoLeches/tree/master/binaries/MacOS[this other repository]. +To create an ultrafast loading tape you need the `leches` and `CgLeches` command line utilities. Those can be obtained for Windows from the +https://github.com/antoniovillena/CargandoLeches/tree/master/binaries[official repository]. You can also obtain an unofficial version for macOS from https://github.com/kounch/CargandoLeches/tree/master/binaries/macOS[this other repository]. -In any other case, you can compile from the https://github.com/antoniovillena/CargandoLeches[source code at the official repository]. For example, in Linux, to compile using `gcc` you only need these commands: +Otherwise you can compile from the https://github.com/antoniovillena/CargandoLeches[source code at the official repository]. For example, in Linux to compile using `gcc` you only need these commands: [source,shell] ---- @@ -646,69 +657,89 @@ gcc leches.c -o leches gcc CgLeches.c -o CgLeches ---- -To create an ultrafast loading tape you have to use the `CgLeches` command from a terminal, giving, at least, the path to the original `TAP` file and also to the new file to create (`WAV` or `TZX`). There are also some other optional parameters, like the loading speed, between 0 and 7 (where 0 is fastest but also more incompatible), if you want to create a mono or stereo file (when making a `WAV`), and more. +To create an ultrafast loading tape you must use the `CgLeches` command from a terminal giving at least the path to the original `TAP` file and the new file to create (`WAV` or `TZX`). There are also some other optional parameters such as the loading speed between 0 and 7 (where 0 is fastest but also more incompatible), if you want to create a mono or stereo file (when making a `WAV`) and more. -Thus, to make a `WAV` file with an ultrafast loading tape from the file `Valley.tap`, with loading speed 5, you could type: +To make a `WAV` file with an ultrafast loading tape from the file `Valley.tap` with loading speed 5 you could enter: [source,shell] ---- (...) CgLeches Valley.tap Valley.wav 5 ---- -This way, the file `Valley.wav` can be played from a computer or another device and load using the ROM (see the section about <<#_loading_from_tape,loading from tape>> for more info). +This way the file `Valley.wav` can be played from a computer or another device and load using the ROM (see the section about <<#_loading_from_tape,loading from tape>> for more info). [WARNING] ==== -Due to hardware limitations, `TZX` files made with `CgLeches` do not work with a <<#_miniduino,Miniduino>>, although they usually work with <<#_playtzx,`PlayTZX`>>. +Due to hardware limitations, `TZX` files made with `CgLeches` don't work with a <<#_miniduino,Miniduino>> although they usually work with <<#_playtzx,`PlayTZX`>>. ==== <<< ==== SE Basic IV -https://github.com/cheveron/sebasic4[SE Basic IV] is a free open-source Z80 interpreter for Microsoft BASIC. SE Basic IV is designed to run on the https://www.patreon.com/chloe280se[Chloe 280SE] but it can also run on ZX-Uno and similar computers. +https://source-solutions.github.io/sebasic4/[SE Basic IV] is a free open-source BASIC interpreter for the Z80 architecture. Although it aims for a high degree of compatibility with Microsoft BASIC, there are some differences. It's designed to run on the https://www.patreon.com/chloe280se[Chloe 280SE] but it's also compatible with the ZX Spectrum core of the ZXTRES. -SE Basic was originally conceived as a new firmware for the https://sinclair.wiki.zxnet.co.uk/wiki/ZX_Spectrum_SE[ZX Spectrum SE]. The earliest versions of SE Basic were patches applied to the original ZX Spectrum ROM, but later versions have been rewritten based on the https://groups.google.com/g/comp.sys.sinclair/c/F90HbKTDkRk[open source TS1000 / ZX81 improved ROM]. +SE BASIC began developement in 1999 as the firmware for the https://sinclair.wiki.zxnet.co.uk/wiki/ZX_Spectrum_SE[ZX Spectrum SE], the ancestor of the Chloe 280SE. Early versions were patches applied to the original Spectrum ROM. From version 1, it used its own assembly file. From version 2, it added support for ULAplus. -Version 3, also known as https://zxdesign.itch.io/opense[OpenSE BASIC], is still maintained as an open source replacement firmware for the Spectrum. It’s https://tracker.debian.org/pkg/opense-basic[included in the main Debian repository] for use with emulators. +Version 3 (https://zxdesign.itch.io/opense[OpenSE BASIC]) replaced the original ROM code with an open source version derived from the https://github.com/cheveron/open81[ZX81] and https://github.com/cheveron/samrom[SAM Coupé] ROMs. It's still maintained as an open source replacement firmware for the Spectrum. and is inlcuded in the main https://tracker.debian.org/pkg/opense-basic[Debian repository] for use with emulators. -Version IV is a fork of the previous version, done because there was no room left to add new features to the 16K ROM. The initial release (4.0 Anya) added another 16K ROM with support for Timex hi-res mode. The syntax was still largely Sinclair BASIC compatible at this point. Version 4.2 was rebuilt specifically for the Chloe 280SE, dropping support for legacy devices such as tape, adding full compatibility and integrated support for the esxdos kernel, and migrating to Microsoft BASIC syntax. +Version 4.0 added support for 80 column mode. Version 4.1 was an unsuccessful attempt to refactor the code. Starting in 2019, the latest version (4.2 Cordelia) was rebuilt from the ground up to take full advantage of the ZX Spectrum core of the ZX-Uno (and ZXTRES). While earlier versions retained a high level of compatiblity with Sinclair BASIC and software, this version has no support for Sinclair software and is closer in dialect to Atari BASIC. -While it shares a common code base with many versions of Sinclair BASIC (the TS1000 ROM), it differs from them in significant ways: +Version 4.2 requires that divMMC support `is enabled with esxDOS or UnoDOS 3 installed. However, "dot" commands and the NMI browser are not supported. -- Code page (8-bit ASCII) support. -- Error message localization. -- 38 additional tokens. -- Standard terminal display (80 x 24). -- Terminal character entry (CTRL, META). -- Keyboard buffer. -- Full sized keyboard support. +Features include: -The main differences from Microsoft BASIC are: - -- Token abbreviation. -- On-entry syntax checking. -- Typically, brackets are optional. -- Motorola style number entry: - % – binary - @ – octal - $ – hexadecimal -- Always-on expression evaluation. -- Separate logical and bitwise operators. +- 40 column (16 colour) and 80 column (2 colour) paletted video modes. +- Always-on expression evaluation (use variables as filenames). +- Application package format with support for turning BASIC programs into apps. - Automatic data typing. +- Bitwise logic (AND, NOT, OR, XOR). +- Built-in help system. +- Choice of Microsoft (LEFT$, MID$, RIGHT$) or Sinclair (TO) string slicing. +- Composable characters (supports Vietnamese). +- Disk-based filesystem (no tapes). +- Error handling (ON ERROR..., TRACE). +- Flow control (IF...THEN...ELSE, WHILE...WEND). +- Full random file access from BASIC (OPEN, CLOSE, SEEK). +- Full-size keyboard support (DEL, HOME, END and so on). +- Graphics commands in 40 column mode (CIRCLE, DRAW, PLOT). +- Localisation of character sets, error messages, and keyboard layouts. +- Long variable names. +- Motorola style number entry (%; binary, @; octal, $; hexadecimal). +- NMI BREAK. +- On-entry syntax checking. +- PLAY command with 6-channel PSG and MIDI support. +- Recursive user-defined functions. +- Smart firmware updates. +- Token abbreviation and shortcuts (&; AND, ~; NOT; |; OR, ?; PRINT, '; REM'). +- Undo NEW (OLD). +- User-defined channels. +- User-defined character sets (256 characters). +- User-defined macros. +- User-defined screen modes. -You can find much more information, including the user manual, etc. at https://github.com/cheveron/sebasic4/wiki[the official wiki page]. +[NOTE] +==== +For the smart firmware update option to work, SE Basic IV must be installed in the second and third 16K ROM slots. +==== + +[CAUTION] +==== +Using the smart firmware update feature replaces the version of esxDOS you're using with the latest version of UnoDOS 3. +==== <<< ==== Other ROMs -Here are flag settings which work when <<#_zx123_tool,adding to the SPI flash>> some other known custom ROMs: +Here are flag settings that work when <<#_zx123_tool,adding to the SPI flash>> some other known custom ROMs: [align="center",width="60%",%header,cols=2*] |=== |ROM Name |Flags +|Arcade Game Designer 0.1 +|thl17x |Gosh Wonderful ROM v1.33 |dnhl17x |Looking Glass 1.07 @@ -717,56 +748,55 @@ Here are flag settings which work when <<#_zx123_tool,adding to the SPI flash>> |dnhl17 |ZX85 by Daniel A. Nagy |dntmh1 -|Arcade Game Designer 0.1 -|thl17x + |=== <<< === microSD advanced format (+3e) -ZX Spectrum +3e is one ROM that can be used with ZX Spectrum core. This is an improved Sinclair ZX Spectrum +3, wich can use hard disks or memory cards. +The ZX Spectrum +3e ROM can be used with the ZX Spectrum core. This is an improved Sinclair ZX Spectrum +3 ROM that can use microSD cards and other media. -+3e uses its own partition format (called IDEDOS), to split de hard disk into several partitions to store data. ROM version 1.28 and later can share IDEDOS partitions with MBR partitions. In other case, you must reserve the whole card for IDEDOS partitions. +The +3e uses its own partition format (called IDEDOS) to split the hard disk into several partitions to store data. ROM version 1.28 and later can share IDEDOS partitions with MBR partitions. Otherwise you must reserve the whole microSD card for the IDEDOS partitions. [IMPORTANT] ==== -The following partition scheme can only be used with ZX Spectrum core. +This partition scheme can only be used with the ZX Spectrum core. ==== [TIP] ==== -Each partition in IDEDOS can be between 1 and 16 Megabytes (16 million bytes) in size, and each disk can have between 1 and 65535 partitions. This means that the maximum space used in a card is about 1 TB. +Each partition in IDEDOS can be between 1 and 16MB (16 million bytes) in size and each disk can have between 1 and 65535 partitions. This means that the maximum space used in a microSD card is about 1TB. ==== -This is one method to split a card into two or three parts, with the first partition IDEDOS (1GB), the second one FAT16 (4GB) and the third one FAT32 (using the remaining space in the card). +This is one method to split a microSD card into two or three parts with the first partition IDEDOS (1GB) the second one FAT16 (4GB) and the third one FAT32 (using the remaining space in the microSD card). -exsdos and other programs can be installed into the second partition <<#_esxdos,as explained earlier>>. +exsDOS and other programs can be installed into the second partition <<#_esxdos,as explained earlier>>. ==== Windows You can use Windows Disk Management utility. The steps are: -. Remove all partitions from the card +. Remove all partitions from the microSD card. -. Create a new extended partition, using the desired space for IDEDOS +. Create a new extended partition using the desired space for IDEDOS. -. Create a primary partition, 4GB in size, and format as FAT16 +. Create a primary partition 4GB in size and format as FAT16. -. Optionally, create another primary partition using the remaining space and format as FAT32 +. Optionally create another primary partition using the remaining space and format as FAT32. <<< -==== MacOS +==== macOS -You will have to use the command line. The first task is to find out which device is the disk to format: +You need to use the command line. The first task is to find out which device is the disk to format: [source,shell] ---- diskutil list ---- -For this example, it will be disk 6: +For this example it's disk 6: [source] ---- @@ -793,13 +823,13 @@ fdisk: could not open MBR file /usr/standalone/i386/boot0: No such file or direc Enter 'help' for information fdisk: 1> erase fdisk:*1> edit 1 -Partition id ('0' to disable) [0 - FF]: [0] (? for help) 7F +Partition id ('0' to switch off) [0 - FF]: [0] (? for help) 7F Do you wish to edit in CHS mode? [n] Partition offset [0 - 31116288]: [63] 128 Partition size [1 - 31116287]: [31116287] 2017152 fdisk:*1> edit 2 -Partition id ('0' to disable) [0 - FF]: [0] (? for help) 06 +Partition id ('0' to switch off) [0 - FF]: [0] (? for help) 06 Do you wish to edit in CHS mode? [n] Partition offset [0 - 31116288]: [2017280] Partition size [1 - 29099135]: [29099135] 7812504 @@ -810,7 +840,7 @@ fdisk:*1> flag 2 [source] ---- fdisk:*1> edit 3 -Partition id ('0' to disable) [0 - FF]: [0] (? for help) 0B +Partition id ('0' to switch off) [0 - FF]: [0] (? for help) 0B Do you wish to edit in CHS mode? [n] Partition offset [0 - 31116288]: [9829784] Partition size [1 - 21286504]: [21286504] @@ -829,7 +859,7 @@ fdisk: 1> quit ---- [start=2] -. Format the FAT partitions (admin privileges required) +. Format the FAT partitions (admin privileges required): [source,shell] ---- @@ -839,7 +869,7 @@ sudo newfs_msdos -F 32 -v EXTRA -c 128 /dev/rdisk6s3 ---- [start=3] -. Confirm that the new partition scheme has been applied: +. Confirm that the new partition scheme was applied: [source,shell] ---- @@ -861,14 +891,14 @@ diskutil list ==== Linux -You can use the command line. First, find out the device to erase: +You can use the command line. First find out the device to erase: [source,shell] ---- lsblk ---- -For this example, it will be `sdc`: +For this example it's `sdc`: [source] ---- @@ -960,7 +990,7 @@ Device Boot Start End Sectors Size Id Type ---- [start=2] -. Format both FAT partitions (requires root privileges) +. Format both FAT partitions (requires root privileges): [source,shell] ---- @@ -971,7 +1001,7 @@ sudo mkfs.fat -F 32 -n EXTRA -s 128 /dev/sdc3 <<< [start=3] -. Confirm that the partition scheme has been changed: +. Confirm that the partition scheme was changed: [source,shell] ---- @@ -990,27 +1020,27 @@ sda 179:0 0 15,8G 0 disk ==== +3e -Once the microSD card is ready to use, you can start Spectrum core with a +3e ROM and format the IDEDOS part. +After the microSD card is ready to use you can start the ZX Spectrum core with a +3e ROM and format the IDEDOS part. -The first step is determine the disk geometry. With the cart inserted into the ZXTRES, type the command: +The first step is determine the disk geometry. With the microSD card inserted into the ZXTRES enter the command: [source,basic] ---- CAT TAB ---- -This will give a result showing the number of https://en.wikipedia.org/wiki/Cylinder-head-sector[cylinders, heads and sectors]. +This gives a result showing the number of https://en.wikipedia.org/wiki/Cylinder-head-sector[cylinders heads and sectors]. -Whith this info, we estimate the size of our partition, using cylinders. For example, if the number of cylinders is 32768, and we want to use 1GB of a 16GB card, the number of cylinders needes would be 32768/16=2048. This way, the IDEDOS partition can be formatted using that number: +With this information you estimate the size of your partition using cylinders. For example, if the number of cylinders is 32768 and you want to use 1GB of a 16GB microSD card, the number of cylinders needed would be 32768/16=2048. This way the IDEDOS partition can be formatted using that number: [source,basic] ---- FORMAT TO 0,100,2048 ---- -The first value (`0`) is the drive to use (the first one), the second value is the maximum number of IDEDOS partitions, and the third one yis the number of cylinders to use. +The first value (`0`) is the drive to use (the first one). The second value is the maximum number of IDEDOS partitions. The third one is the number of cylinders to use. -Once formatted, you can create new partitions. For example, to create a 16MB partition with the name "Software", another 4GB partition named "Swap" (to use as swap) and another one name "Utils", 8MB in size: +After formatting, you can create new partitions. For example, to create a 16MB partition called "Software", a 4GB partition called "Swap" (to use as swap disk) and an 8MB partition called "Utils": [source,basic] ---- @@ -1019,111 +1049,115 @@ NEW EXP "Swap1",4 NEW DATA "Utils",8 ---- -For more information about the different +3e disk commands , you can check https://worldofspectrum.org/zxplus3e/index.html[this page at World of Spectrum]. +For more information about the different +3e disk commands refer to https://worldofspectrum.org/zxplus3e/index.html[this page at World of Spectrum]. <<< -=== esxdos commands +=== esxDOS commands -==== Basic Guide +==== Overview -There are two different kind of esxdos commands, the so-called "DOT" commands, which, as the name suggests, begin with a period, and the commands that are extensions to the existing ones in BASIC. +There are two different kind of esxDOS commands: the so-called "dot" commands that, as the name suggests, begin with a dot (`.`), and extensions to existing BASIC commands. -The main "DOT" commands are the following: +The main "dot" commands are: -- `128`: Para enter 128K mode from within 48K mode -- `cd`: Change current working directory -- `chmod`: Change file attributes -- `cp`: Copy a file -- `divideo`: Play a DivIDEo (.DVO) video file -- `drives`: Show currently available drives -- `dskprobe`: Utility which shows low level content of an storage device -- `dumpmem`: Can dump RAM memory content to a file -- `file`: Tries to recognize the type of data contained in a file (like the UNIX command) -- `gramon`: Monitor to search graphics, sprites, fonts, etc. in RAM memory -- `hexdump`: Shows the contents of a file using hexadecimal notation -- `hexview`: Allow to see and navigate through the contents os a file using hexadecimal notation -- `launcher`: Creates a shortcut (launcher) to open directly a TAP file -- `ls`: Show the content of a directory -- `lstap`: Show the content of a .TAP file -- `mkdir`: Create a directory -- `mktrd`: Create a .TRD disk file -- `more`: Show the content of a text file -- `mv`: Move a file -- `partinfo`: Show partition information of an storage device -- `playpt3`: Play .PT3 music file -- `playsqt`: Play .SQT music file -- `playstc`: Play .STC music file -- `playtfm`: Play .TFC music file -- `playwav`: Play .WAV audio file -- `rm`: Remove a file or a directory -- `snapload`: Load snapshot file -- `speakcz`: Reads text aloud using czech pronunciation -- `tapein`: Mounts a .TAP file so that it can be used then from BASIC using LOAD sentence -- `tapeout`: Mount a .TAP file so that it can be used then from BASIC using SAVE sentence -- `vdisk`: Mount a .TRD disk file to use with the TR-DOS environment (once all the drives have been mounted, you can enter TR-DOS emulation by typing: `RANDOMIZE USR 15616`) +- `128`: Enter 128 mode from within 48 mode. +- `cd`: Change current working folder. +- `chmod`: Change file attributes. +- `cp`: Copy a file. +- `divideo`: Play a divIDEo (`DVO`) video file (divIDE only). +- `drives`: Show currently available drives. +- `dskprobe`: Utility that shows low level content of an storage device. +- `dumpmem`: Can dump RAM memory content to a file. +- `file`: Tries to recognise the type of data contained in a file (like the UNIX command). +- `gramon`: Monitor to search graphics sprites fonts and so on in RAM memory. +- `hexdump`: Shows the contents of a file using hexadecimal notation. +- `hexview`: Allow to see and navigate through the contents os a file using hexadecimal notation. +- `launcher`: Creates a shortcut (launcher) to open directly a `TAP` file. +- `ls`: Show the content of a folder. +- `lstap`: Show the content of a `TAP` file. +- `mkdir`: Create a folder. +- `mktrd`: Create a `TRD` disk file. +- `more`: Show the content of a text file. +- `mv`: Move a file. +- `partinfo`: Show partition information of an storage device. +- `playpt3`: Play `PT3` music file. +- `playsqt`: Play `SQT` music file. +- `playstc`: Play `STC` music file. +- `playtfm`: Play `TFC` music file. +- `playwav`: Play `WAV` audio file. +- `rm`: Remove a file or a folder. +- `snapload`: Load snapshot file. +- `speakcz`: Read text aloud using Czech pronunciation. +- `tapein`: Mounts a `TAP` file so that it can be used then from BASIC using LOAD sentence. +- `tapeout`: Mount a `TAP` file so that it can be used then from BASIC using SAVE sentence. +- `vdisk`: Mount a `TRD` disk file to use with the TR-DOS environment (after all drives have been mounted you can enter TR-DOS emulation by typing: `RANDOMIZE USR 15616`). Some BASIC extended commands are: -- `GO TO` to change the current drive and/or directory (e.g.: `GO TO hd1` or `GO TO hd0"games"`) -- `CAT` to show the content of a drive -- `LOAD` to lad a file from a drive (BASIC Program, SCREEN, CODE, etc. for example `LOAD *"Screen.scr" SCREEN$`) -- `SAVE` to save data in a file (e.g: `SAVE *"Program.bas"`) -- `ERASE` to delete a file +- `GO TO` to change the current drive or folder (for example: `GO TO hd1` or `GO TO hd0"GAMES"`). +- `CAT` to show the content of a drive. +- `LOAD` to lad a file from a drive (BASIC Program SCREEN CODE and so on for example `LOAD *"Screen.scr" SCREEN$`). +- `SAVE` to save data in a file (for example, `SAVE *"PROGRAM.BAS"`). +- `ERASE` to remove a file. -In addition, esxdos also has an NMI manager, an application that loads when NMI (`F5`) is pressed, and lets you browse the microSD card and load easily files (TAP, Z80, TRD, etc.). Pressing the "H" key invokes a help screen, which shows all the available keys. +In addition esxDOS supports an NMI browser that loads when the NMI is activated (`F5` is pressed). This enables you to browse the microSD card and easily load files (`TAP`, `Z80`, `TRD` and so on). In the default NMI browser, pressing the `H` key invokes a help screen that shows all available key commands. [NOTE] ==== -The esxdos manager shows file and directory entries in the order stored in the internal FAT table, and not alphabetically. If you want to see them ordered, you have to reorder the microSD card structure with a utility like Fat Sorter for Windows, https://fatsort.sourceforge.io/[FATsort] for Linux and MacOS, https://www.luisrios.eti.br/public/en_us/projects/yafs/[YAFS], http://www.trustfm.net/software/utilities/SDSorter.phpp[SDSorter] or other. +The NMI browser shows file and folder entries in the order stored in the internal FAT table and not alphabetically. If you want to see them ordered you must reorder the microSD card structure with a utility such as https://fatsort.sourceforge.io/[FATsort], https://www.luisrios.eti.br/public/en_us/projects/yafs/[YAFS], http://www.trustfm.net/software/utilities/SDSorter.phpp[SDSorter] or another application. ==== [CAUTION] ==== -Ïf the card is also being used with a PC XT core, **do not use any FAT reordering utility** as it may stop DOS from booting. +**Don't use any FAT reordering utility** if the microSD card is also being used with a PC XT core because it may stop DOS from booting. ==== <<< ==== ZXTRES Commands -As explained in the installation part, there are a series of commands that are exclusive to ZXTRES: +As noted in the installation section, there are a several "dot" commands that are exclusive to the ZXTRES: -- `back16m`: Dumps to a `FLASH.ZX1` file, in the root directory of the microSD card, the contents of a 16 Meg SPI Flash memory. It must be run while using a "root" mode ROM. After finishing, it is necessary to execute the command `.ls` so that the cache is written to the card -- `backzx2` or `backzxd`: Creates a `FLASH_32.ZX2` o `FLASH_32.ZXD` file, in the root directory of the microSD card, with the contents of a 32 Meg SPI Flash memory. It must be run while using a "root" mode ROM.After finishing its execution, you must execute the command `.ls` to finish recording the cache on the microSD card. If not, the length of the file will be wrongly set to 0 -- `corebios`: To upddate simultaneously ZX Spectrum core and BIOS -- `dmaplayw`: Plays .WAV file, which has to be 8 bits, unsigned and sampled at 15625 Hz -- `esprst`: Resets the WiFi ESP8266(ESP-12) module -- `iwconfig`: To configure the WiFi module -- `joyconf`: Configuration and tests for keyboard and DB joysticks -- `keymap`: Used to load a different keyboard map definition -- `loadpzx`: To load a .PZX tape file -- `loadtap`: To load a .TAP file, using the .PZX integration -- `playmid`: Plays .MID music files using the MIDI addon -- `playrmov`: Plays <<#_making_rdm_radastan_movie_files,radastanian format video files `.RDM`)>>. This command does not work on 48K mode. -- `romsback`: Dumps to a RomPack File named `ROMS.ZX1`, in the root directory of the microSD card, all ZX Spectrum core ROMS which are stored in SPI flash memory. It must be run while using a "root" mode ROM. Only works correctly on ZX-Uno and ZXDOS (do not use on ZXTRES, ZXDOS+ or similar devices). -- `romsupgr`: Load from a RomPack filel named `ROMS.ZX1`, in the root directory of the microSD card, all ZX Spectrum core ROMS into SPI flash memory. It must be run while using a "root" mode ROM -- `upgr16m`: Load the content of a `FLASH.ZX1` file, in the root directory of the microSD card, to a 16 Meg SPI Flash memory. It must be run while using a "root" mode ROM -- `upgrzx2` or `upgrzxd`: Write the content of a `FLASH_32.ZX2` or `FLASH_32.ZXD` file, in the root directory of the microSD card, to a 32 Meg SPI Flash memory. It must be run while using a "root" mode ROM. -- `zxuc`: Utility to configure al options of BIOS, which also can be stored in the microSD in configuration files that can be loaded later -- `zxunocfg`: Configuration utillity for certain features of ZX-Uno such as timings, contention, keyboard type, CPU speed, video type or vertical frequency +- `back16m`: Dumps to a `FLASH.ZX1` file in the root folder of the microSD card the contents of a 16 Meg SPI Flash memory. After the command is done, you must enter `.ls` so that the cache is written to the microSD card. Otherwise the length of the file is wrongly set to 0. +- `backzx2` or `backzxd`: Creates a `FLASH_32.ZX2` or `FLASH_32.ZXD` file in the root folder of the microSD card with the contents of a 32 Meg SPI Flash memory. After the command is done, you must enter `.ls` so that the cache is wrtten to the microSD card. Otherwise the length of the file is wrongly set to 0. +- `corebios`: Simultaneously update the ZX Spectrum core and BIOS. +- `dmaplayw`: Play a `WAV` file that is 8-bits unsigned and sampled at 15625 Hz. +- `esprst`: Reset the WiFi ESP8266(ESP-12) module. +- `iwconfig`: Configure the WiFi module. +- `joyconf`: Configure and test for keyboard and DE9 joysticks. +- `keymap`: Load a different keyboard map definition. +- `loadpzx`: Load a `PZX` tape file. +- `loadtap`: Load a `TAP` file using the `PZX` integration. +- `playmid`: Play a `MID` music files using the MIDI addon. +- `playrmov`: Play <<#_making_rdm_radastan_movie_files,radastanian format video files `RDM`)>>. This command doesn't work in 48K mode. +- `romsupgr`: Load from a RomPack filel called `ROMS.ZX1` in the root folder of the microSD card all ZX Spectrum core ROMS into SPI flash memory. +- `upgr16m`: Load the content of a `FLASH.ZX1` file in the root folder of the microSD card to a 16 Meg SPI Flash memory. +- `upgrzx2` or `upgrzxd`: Write the content of a `FLASH_32.ZX2` or `FLASH_32.ZXD` file in the root folder of the microSD card to a 32 Meg SPI Flash memory. +- `zxuc`: Configure all options of BIOS that also can be stored in the microSD in configuration files that can be loaded later. +- `zxunocfg`: Configurae certain features such as timings contention keyboard type CPU speed video type or vertical frequency. + +[CAUTION] +==== +The `romsback` command is designed for the ZX-Uno and ZX-Dos and must not be used with the ZXTRES. +==== <<< -=== Making RDM (RaDastan Movie) files +=== Creating RaDastanian movie files -The `PLAYRMOV` "DOT" command plays radastanian format video files. To convert your own videos, you need `makevideoradas`, a utility that is available at https://svn.zxuno.com/svn/zxuno/software/modo_radastan/videos_radastanianos/[SVN repository]. +The `playrmov` "dot" command plays Radastanian format (`RDM`) video files. To convert your own videos you need `makevideoradas`, a utility that's available at this https://svn.zxuno.com/svn/zxuno/software/modo_radastan/videos_radastanianos/[SVN repository]. -If using Windows, there is already an executable file (`makevideoras.exe`). For Linux or MacOS, you must have installed command line developer utilities in order to compile an executable +If you're using Windows there's already an executable file (`makevideoras.exe`). For Linux or macOS you must have the command line developer utilities installed to compile an executable. [source,shell] ---- gcc makevideoradas.c -o makevideoradas ---- -Apart from `makevdideoradas`, you need another two tools: https://ffmpeg.org[`ffmpeg`] and https://imagemagick.org/index.php[`imagemagick`]. These can be installed with a package manager (`apt`, `yum`, `pacmam`, `brew`, etc.) or downloading the source code and compiling. +Apart from `makevdideoradas` you need another two tools: https://ffmpeg.org[`ffmpeg`] and https://imagemagick.org/index.php[`imagemagick`]. These can be installed with a package manager (`apt` `yum` `pacmam` `brew` and so on) or downloading the source code and compiling. -Now, the first step to convert our video (for example `myvideo.mp4`), is exporting the frames as 128x96 pixel BMP image files. We create a temporary file (`img` for this example), to store them. +The first step to convert your video (for example `myvideo.mp4`) is exporting the frames as 128x96 pixel BMP image files. You can create a temporary file (`img` for this example) to store them. [source,shell] ---- @@ -1131,14 +1165,14 @@ mkdir img (...)/ffmpeg -i myvideo.mp4 -vf "scale=128:96,fps=25" -start_number 0 img/output%05d.bmp ---- -Now we transform the `BMP` files to 16 colours (v3) `BMP` files. +Now you can transform the `BMP` files to 16 colours (v3) `BMP` files. [source,shell] ---- -(...)/magick mogrify -colors 16 -format bmp -define bmp:format=bmp3 img/*.bmp +(...)/magick mogrify -colours 16 -format bmp -define bmp:format=bmp3 img/*.bmp ---- -Finally, we assemble the `.RDM` file (in this example `myvideo.rdm`) and cleanup the temporary files and directory. +Last you can assemble the `RDM` file (in this example `myvideo.rdm`) and cleanup the temporary files and folder. [source,shell] ---- @@ -1147,7 +1181,7 @@ mv img/output.rdm ../myvideo.rdm rm -rf img ---- -There is more information about all this process at https://www.zonadepruebas.com/viewtopic.php?t=4796&start=110[this thread in Zona de Pruebas forums]. +For more information about this process refer to https://www.zonadepruebas.com/viewtopic.php?t=4796&start=110[this thread in Zona de Pruebas forums]. <<< @@ -1155,116 +1189,101 @@ There is more information about all this process at https://www.zonadepruebas.co === BIOS -To update the BIOS, a file named `FIRMWARE.ZX2` (for a ZXTRES with an FPGA LX16 board) or `FIRMWARE.ZXD` (for a ZXTRES with an FPGA LX25 board) must be obtained. The latest version of the firmware files can be downloaded from https://github.com/zxdos/zxuno/tree/master/firmware[the official repository] +To update the BIOS, a file called `FIRMWARE.ZX3` must be obtained. The latest version of the firmware files can be downloaded from https://github.com/zxdos/zxuno/tree/master/firmware[the official repository]. [CAUTION] ==== -Updating the firmware (BIOS) is delicate. It should not be done if it is not necessary. If doing so, ensure that the ZXTRES has uninterrupted power (such as a UPS or a laptop USB with battery). +Updating the firmware (BIOS) is delicate. It shouldn't be done if it's not necessary. When doing so, ensure that the ZXTRES has uninterrupted power (such as a UPS or a laptop USB with battery). ==== -Copy the file to the root of the MicroSD card, turn on and press `F2` to enter BIOS, select `Upgrade`, choose __"Upgrade BIOS for ZX"__, and then __"SDfile"__. The system will read the file `FIRMWARE...` and notify when finished. +Copy the file to the root of the microSD card, power on and press `F2` to enter BIOS. Select `Upgrade`. Choose __"Upgrade BIOS for ZX"__ and then __"SDfile"__. The system reads the file `FIRMWARE...` and notifies you when it's done. === ROMs -The flash memory of a ZXTRES has reserved 64 slots, 16K each, to store ZX Spectrum ROM images. Thus, an original ZX Spectrum ROM (16K) will take one slot, a ZX Spectrum 128K ROM (32K) will be two slots, and a ZX Spectrum +2A ROM (64K) will need 4 slots. +The flash memory of a ZXTRES has 64 reserved slots of 16K each to store ZX Spectrum core ROM images. Thus an original ZX Spectrum ROM (16K) uses one slot, a ZX Spectrum 128 ROM (32K) uses two slots and a ZX Spectrum +3 ROM (64K) uses four slots. -You can add a new ROM pressing the key `N` at the BIOS <<#_roms,ROMs screen>>, connecting an audio cable to the board, and playing a ROM audio tape. ROM audio tapes can be made from a `.tap` file built with the `GenRom` utility, available at https://github.com/zxdos/zxuno/tree/master/modflash[ZX-Uno Code Repository]. +You can add a new ROM pressing the key `N` at the BIOS <<#_roms,ROMs screen>>, connecting an audio cable to the board and loading a ROM from an audio player. ROM audio tapes can be made from a `TAP` file built with the `GenRom` utility available at the https://github.com/zxdos/zxuno/tree/master/modflash[ZX-Uno Code Repository]. -To update at once all the ROMs installed for ZX Spectrum, a RomPack file named `ROMS.ZX1` must be obtained, which must be copied to the MicroSD card. Boot the ZXTRES using a "rooted" ROM, and then just enter the command `.romsupgr`. This will burn all the ROMs, which will be available for use. +To update all ROMs installed for the ZX Spectrum core in one go, a RomPack file called `ROMS.ZX1` must be obtained that must be copied to the microSD card. Boot the ZXTRES and then enter `.romsupgr`. This overwrites the existing set of ROMs with those contained in the file. [WARNING] ==== -At this moment, `romsupgr`, only works correctly with RomPack files using a maximum of 35 slots. +Currently, `romsupgr` only works correctly with RomPack files containing a maximum of 35 slots. ==== -[NOTE] -==== -Remember that if the ZXTRES is started by pressing the `/` key (on the numeric keyboard), then the default ROM of the ZX Spectrum core will be loaded in" root "mode. -==== - -To do the opposite process (save the ROMs in a RomPack file named `ROMS.ZX1`), you can use the` .romsback` command. - -[NOTE] -==== -At this moment, `romsback`, only stores correctly the first 35 used slots. -==== - -RomPack files can be easily edited with the http: // guest: zxuno@svn.zxuno.comsvn/zxuno/software/ZX1RomPack/[ZX1RomPack] utility. Although it is a Windows program, it works perfectly, for example using https://www.winehq.org[Wine] or similar programs, either on MacOS or Linux. +RomPack files can be easily edited with the http://guest:zxuno@svn.zxuno.comsvn/zxuno/software/ZX1RomPack/[ZX1RomPack] utility. Although it's a Windows program it works perfectly for example using https://www.winehq.org[Wine] or similar programs either on Linux and macOS versions with 32-bit Intel support.. === Cores -A core is a file with the information needed for the FPGA to behave like a system to implement (ZX Spectrum, etc.). In ZXTRES, this file can be loaded possible from several different places: the SPI Flash memory, a microSD card, or from an external device (PC, etc.) using a special cable. +A core is a file with the information needed to configure the FPGA to behave like a specific system (ZX Spectrum and so on). In the ZXTRES this file can be loaded from several different places: the SPI Flash memory, a microSD card or from an external device (PC and so on) using a special cable. ==== microSD card ===== Loading from the ZX Spectrum core -From the main ZX Spectrum core it is possible to load other cores. +From the main ZX Spectrum core it's possible to load other cores. -====== Bob Fossil Browser +====== Bob Fossil NMI browser -In order to use the Bob Fossil browser to load cores, you need the following: +To use the Bob Fossil NMI browser to load cores you need: -- The latest stable version (http://www.thefossilrecord.co.uk/wp-content/uploads/zx/BROWSE_latest.zip) -- The ZX3 plugin which can load Cores in ZX3 format https://github.com/zxdos/zxuno/blob/master/SD/BIN/BPLUGINS/ZX3 +- The latest stable version (http://www.thefossilrecord.co.uk/wp-content/uploads/zx/BROWSE_latest.zip). +- The ZX3 plugin that can load Cores in ZX3 format https://github.com/zxdos/zxuno/blob/master/SD/BIN/BPLUGINS/ZX3. -Copy the corresponding `.ZX3` file to the desired location of the microSD card, as well as the appropriate ZX3 plugin (in the folder `BIN\BPLUGINS`). +Copy the corresponding `ZX3` file to the desired location of the microSD card as well as the appropriate ZX3 plugin (in the folder `BIN\BPLUGINS`). -. Start the ZXTRES Spectrum Core in root mode (by pressing `/` during BIOS boot until the border turns red). -. Press `F5` to open Bob Fossil's browser and get to the location of the Core with extension `.ZX3`, select it and press ENTER. +Press `F5` to open Bob Fossil's NMI browser and get to the location of the Core with extension `ZX3`, select it and press `Enter`. -If all goes well, the bottom of the screen will indicate the flashing progress (it is recorded in a temporary slot of the flash memory). - -In case you didn't boot in root mode, just reboot (ctrl+alt+backspace) while pressing "/" and try again. +If everything worked correctly, the bottom of the screen indicates the flashing progress (it's recorded in a temporary slot of the flash memory). <<< ==== SPI Flash Memory -There 27 spaces where you can store cores, with the first spaces being reserved for the main ZX Spectrum (this does not prevent having more ZX Spectrum cores in other spaces as well of the first ones). +There are 27 spaces where you can store cores, with the first spaces being reserved for the main ZX Spectrum (this doesn't prevent having more ZX Spectrum cores in other spaces as well of the first ones). Official cores are https://github.com/zxtres/cores[available to download] from GitHub repository. To update or install a new core in the SPI Flash there are several possibilities. -The first options is to obtain the latest version of the files that define the core. If the space used is greater than 1179648 bytes, it has to be split accordingly into several files. Each of this pieces will be a file that must be named `COREXXy.ZX3`, where `XX` is _always_ a two digit number. The `y` part of the name is ignored, so you can use longer and more descriptive names (for example `CORE04_example_part1.ZX3`). +The first options is to obtain the latest version of the files that define the core. If the space used is greater than 1179648 bytes it must be split accordingly into several files. Each of these pieces must be a file called `COREXXy.ZX3` where `XX` is _always_ a two digit number. The `y` part of the name is ignored so you can use longer and more descriptive names (for example `CORE04_example_part1.ZX3`). -Copy the files to the root of the microSD card, turn on and press `F2` to enter BIOS. Choose `Upgrade`, select the row corresponding to the chosen core space (for example, 4), press enter and then __" SD file "__. The system will read the file `COREnn ..` and notify when it is updated, although first it will ask for the name (to be shown in the list to choose from at startup and in the BIOS list). Usually, for cores using more than one space, the name of the core is only used for the first space and the remaining spaces are registered with some text warning not to use them. Once it is installed, you can use the core on boot, choosing always the first space used by the core. +Copy the files to the root of the microSD card, power on and press `F2` to enter the BIOS. Choose `Upgrade`, select the row corresponding to the chosen core space (for example 4), press enter and then __" SD file "__. The system reads the file `COREnn ..` and notifies you when it's updated. However, first it asks for the name (to be shown in the list to choose from at startup and in the BIOS list). For cores using more than one space, typically the name of the core is only used for the first space and the remaining spaces are registered with some text warning not to use them. After it's installed you can use the core on boot by choosing the first space used by the core. [WARNING] ==== -The main ZX Spectrum core update is exactly the same as other cores, but, for the firsta part instead of the name `CORE1.ZXX` it has to be a file named `SPECTRUM.ZX3` and with a special format. +The main ZX Spectrum core update is exactly the same as other cores but for the first part instead of the name `CORE1.ZXX` it must be a file called `SPECTRUM.ZX3` with a special format. ==== <<< -=== esxdos +=== esxDOS -To update esxdos to a new version, the distribution must be obtained from https://www.esxdos.org[the official website]. +To update esxDOS to a new version the distribution must be obtained from https://www.esxDOS.org[the official website]. -Once downloaded and extracted, the contents of `BIN` and `SYS` directories have to be copied to the root of the card, merging the existing ones (to preserve the exclusive ZXTRES commands). +After you've downloaded and extracted the `ZIP` archive, the contents of the `BIN` and `SYS` folders must be copied to the root of the microSD card partition merging with the existing ones (to preserve the exclusive ZXTRES commands). -Copy `ESXMMC.BIN` (or `ESXMMC.ROM`, depending on version) to the root of the microSD card. +Copy `ESXMMC.BIN` (or `ESXMMC.ROM` depending on version) to the root of the microSD card. -Start ZXDOS + with the card inserted and press `F2` to access BIOS setup. Select the `Upgrade` menu and choose __"Upgrade esxdos for ZX"__. In the dialog that appears choose __"SD file"__ and, when it asks __"Load from SD"__ answer __"Yes"__ to the question __"Are you sure?"__. The content of the file `ESXDOS...` will be read, written to the flash storage and you will be notified when it is updated. +Power on the ZXTRES with the microSD card inserted and press `F2` to access BIOS setup. Select the `Upgrade` menu and choose __"Upgrade esxdos for ZX"__. In the dialog that appears choose __"SD file"__ and when it asks __"Load from SD"__ answer __"Yes"__ to the question __"Are you sure?"__. The content of the file `ESXDOS...` is read and written to the flash storage and you are notified when it's updated. -Do a Hard-reset, or turn it off and on. +Do a hard reset or power cycle the ZXTRES. -If everything has been done correctly, when you turn on the ZXTRES you will see how esxdos detects the card and loads the necessary components to work, showing the new version at the top. +If everything was done correctly, when you start the ZX Spectrum core you'll see esxDOS detect the microSD card and load the required components to work, showing the new version at the top. === Flash Memory -You also can update all the FPGA flash memory. At this moment, from the BIOS you can only use 16MiB image files. To use a 32MiB image, you must use <<#_esxdos,esxdos>> `UPGRZXD` command and a file named `FLASH.ZXD`. +You also can update all FPGA flash memory. At this moment from the BIOS you can only use 16MiB image files. To use a 32MiB image you must use <<#_esxdos,esxdos>> `UPGRZXD` command and a file called `FLASH.ZXD`. Copy the image file (16MiB) `FLASH.ZX3` to the root of the microSD card. -Turn on the ZXTRES and press the `F2` key during boot to access the BIOS setup. Select the menu `Upgrade` and then choos the option __"Upgrade flash from SD"__. Press Enter, choose `Yes`, and press Enter again to start the Flash writing process. +Power on the ZXTRES and press the `F2` key during boot to access the BIOS setup. Select the menu `Upgrade` and then choos the option __"Upgrade flash from SD"__. Press Enter choose `Yes` and press Enter again to start the Flash writing process. -Do a Hard-Reset or turn of and on again. +Do a Hard-Reset or power cycle the ZXTRES. [WARNING] ==== -This process can't be undone, and it will replace all the previously installed cores, the BIOS, the ZX Spectrum ROMs and their configuration with the data in the image file. +This process can't be undone and it replaces all previously installed cores, the BIOS, the ZX Spectrum ROMs and their configuration with the data in the image file. ==== <<< @@ -1275,132 +1294,205 @@ This process can't be undone, and it will replace all the previously installed c https://en.wikipedia.org/wiki/ColecoVision[ColecoVision] is Coleco Industries' home video-game console that was released in August 1982. -ZXTRES core is based on https://github.com/fbelavenuto/colecofpga[ZX-Uno version] by Fabio Belavenuto. +The ZXTRES core is based on https://github.com/fbelavenuto/colecofpga[ZX-Uno version] by Fabio Belavenuto. -Some features of this core are: +Some characteristics of this core are: -- BIOS ROM is loaded from microSD card -- Supports multicart ROM, also loaded from microSD -- Only works with VGA +- BIOS ROM is loaded from microSD card. +- Supports multicart ROM also loaded from microSD. +- Only works with VGA. ==== microSD card format -You need a microSD card with the first partition in FAT16 or FAT32 format to store ROM image files of the games to load and other needed files. These can be downloaded from https://github.com/fbelavenuto/colecofpga/tree/master/SD_Card[the original project in GitHub]. +To store ROM image (games) and other files, use a microSD card with the first partition in FAT16 or FAT32 format. -After copying these files to the card, you have to add also the file `MULTCART.ROM` which can be downloaded from https://t.me/zxtresfpga +They can be downloaded from https://github.com/fbelavenuto/colecofpga/tree/master/SD_Card[the original project in GitHub]. -See the <<#_cores,corresponding section>> for instructions of how to install the ColecoVision core in ZXTRES. +After copying the files to the microSD card you must add also the file `MULTCART.ROM` that can be downloaded from https://t.me/zxtresfpga. + +See the <<#_cores,corresponding section>> for instructions of how to install the ColecoVision core in the ZXTRES. ==== Keyboard ===== Special keys and buttons -While the core is running: +When the core is active: -- Cursor or `Q`, `A`, `E`, `R` or joystick 1: Directional controls for player 1 -- `Z` or joystick 1 main fire button: Fire Button 1 for player 1 -- `U`, `J`, `O`, `P` or joystick 2: Directional controls for player 2 -- `M` or joystick 2 main fire button: Fire button 1 for player 2 -- `X` or joystick 1 secondary fire button: Fire button 1 for player 1 and player 2 -- `0` to `9`: Button 0 to 9 for player 1 and player 2 -- `T`: Button '*' -- `Y`: Button '#' -- 'Esc': Soft Reset +- 'Esc': Soft reset. +- `0` to `9`: Button 0 to 9 for player 1 and player 2. +- Cursor or `Q`, `A`, `E`, `R` or joystick 1: Directional controls for player 1. +- `U`, `J`, `O`, `P` or joystick 2: Directional controls for player 2. +- `Z` or joystick button `1` main fire button: Fire Button `1` for player 1. +- `M` or joystick button `2` main fire button: Fire button `1` for player 2. +- `X` or joystick button `1` secondary fire button: Fire button `1` for player 1 and player 2. +- `T`: Button '*'. +- `Y`: Button '#'. <<< -==== Basic Guide +==== Overview -On startup, BIOS ROM is loaded from the card, and then the multicart ROM. +On startup the BIOS ROM is loaded from the microSD card and then the multicart ROM. [.text-center] image:img/coleco.jpg[scaledwidth=70%] -At multicart menu, use the directional controls to choose one ROM, and then fire button 1 to load. Pressing 'Esc' restarts the core and loads the ROM selection menu again. +From the multicart menu use the directional controls to choose a ROM and then press fire button `1` to load. Pressing 'Esc' restarts the core and reloads the ROM selection menu. <<< === Neo-Geo +https://es.wikipedia.org/wiki/Neo-Geo[Neo-Geo] is the name of a 16-bit cartridge-based system for arcade as well as home video game consoles released in 1990 by the Japanese video game company SNK. The Neo-Geo system was originally created as a platform for arcade machines (MVS or Multi Video System), but was later also available as a home game console (AES or Advanced Entertainment System). + +The ZXTRES version (by somhi) is based on the https://github.com/robinsonb5/NeoGeo_FPGA[DeMiStified version] of the https://github.com/MiSTer-devel/NeoGeo_MiSTer[original version for MiSTer FPGA]. + +Some core charactersistics are: + +- Compatible with Sega Mega Drive (Genesis) controllers. +- MVS and AES support. +- RGB output only. +- Support for ROMS (not encrypted) in https://wiki.terraonion.com/index.php/Neobuilder_Guide[`NEO` format]. +- Support for http://unibios.free.fr/download.html[Universe BIOS]. + <<< -=== Test DP +==== microSD card format -Alternative Core, whose objective is to test the VGA, RGB and DisplayPort video outputs, applying different effects. +To store the ROM image files, use a microSDcard with the first partition in FAT16 or FAT32 format. -Its main features are: +After the files have been copied to the microSD card, you need a BIOS (for example http://unibios.free.fr/download.html[Universe BIOS]), with the name `neogeo.rom`, in the root. -- DisplaPort video output -- VGA video output -- 15 kHz RGB video output (using the VGA port) -- Scanlines -- Monochrome green, amber, white and colour modes - -==== microSD Card Format - -This core does not use the microSD card. +If not already there, <<#_cores,install or run the Neo-Geo core>> on the ZXTRES. ==== Keyboard ===== Special keys and buttons -While the core is running: +When the core is active: + +- `F12` displays the core control menu. +- Cursor or a controller connected to the left port: Player 1 direction controls. +- `Right Ctrl` or button A on controller 1: Player 1's A button. +- `Right Alt` or the B button on controller 1: Player 1's B button. +- `Right Win` or button C on controller 1: Player 1's button C. +- `Righ Shift` or D button on controller 1: Player 1's D button. +- `Start`: Start button of player 1. +- `W`, `A`, `S`, `D` or a controller connected to the right port: Player 2 Directional Controls. +- `Left Ctrl` or the A button on controller 1: Player 2's A button. +- `Left Alt` or the B button on controller 1: Player 2's B button. +- `Left Win` or button C on controller 1: Player 2's button C. +- `Left Shift` or D button on controller 1: Player's D button 2. +- `Caps Lock`: Start button of player 2. + +<<< + +==== Overview + +When the correct files are present on the microSD card and the core is started, a blank screen is displayed. Press `F12` to display the menu with the different core options. + +[text-center] +image:img/neogeo.jpg[scaledwidth=70%] + +These are the main ones: + +- `Load Cart`: To load from the microSD card a .neo file. +- `Load Cart (skip ADPCM)`. +- `Load BIOS`: To load from the microSD card a BIOS file other than `neogeo.rom`. +- `Load Memory Card`. +- `Save Memory Card`. +- `Mount CD`: Currently unavailable. +- `System Type`: MVS or AES +- `CD Speed`: Currently unavailable. +- `CD Region`: Currently unavailable. +- `CD lid`: Currently unavailable. +- `Video Mode`: NTSC or PAL. +- `Scanlines`: To add a scanline effect, if desired. +- `Blend`: To activate, if desired, an image smoothing effect. +- `Swap Joystick`: To swap the controls of player 1 and player 2. +- `Input`: Currently unavailable. +- `[DIP]`: Currently unavailable. +- `Exit`: Closes the menu. + +<<< + +=== Test DP + +The purpose of this core is to test the VGA, RGB and DisplayPort video outputs by applying different effects. + +Its main characteristics are: + +- 15 kHz RGB video output (using the VGA port). +- DisplaPort video output. +- Monochrome green amber white and colour modes. +- Scanlines. +- VGA video output. + +==== microSD card format + +This core doesn't use the microSD card. + +==== Keyboard + +===== Special keys and buttons + +When the core is active: - `1`: Changes the VGA output to RGB 15 kHz. -- `2`: Turns scanlines on and off -- `3`: Toggles the display between colour, monochrome green, amber and white modes. +- `2`: Toggles scanlines on or off. +- `3`: Toggles the display between colour, monochrome, green, amber and white modes. [NOTE] ==== -The above mentioned effects with keys 2 and 3 are not visible on the original 15 kHz output. +The previously mentioned effects with keys `2` and `3` are not visible on the original 15 kHz output. ==== -==== Basic guide +==== Overview -When the core starts up, it sends the video signal via both VGA and DisplayPort. The refresh rate is about 64 Hz. +When the core is started, it sends the video signal using both VGA and DisplayPort. The refresh rate is about 64 Hz. -The three LEDs on the board have the following meaning: +The three LEDs on the ZXTRES board have these meanings: -- The one closest to the edge should be on all the time. This is the DONE LED, and it is managed by the FPGA itself, not the core. -- The middle one indicates, when lit, that there is a valid transmission link between the FPGA and the DisplayPort monitor. This means that the link is good, that the training has been successful, and that it is currently sending a video image to the monitor. If it is off, it means that the link could not be established (e.g. because the cable has been removed, or the monitor is turned off, or perhaps because the DisplayPort input is not selected on that monitor). -- The one on the other end should be blinking, at a rate of about one blink per second. This is a "heartbeat" of the pixel clock, indicating that both the VGA and DisplayPort outputs are generating an image. If this LED does not blink, no image of any kind can be seen on either VGA or DisplayPort, only RGB at 15 kHz. Under normal circumstances, whether a DisplayPort monitor is plugged in or not, this LED should be blinking. +- The one closest to the edge should be on all the time. This is the DONE LED and it's managed by the FPGA itself not the core. +- The middle one indicates when lit that there's a valid transmission link between the FPGA and the DisplayPort monitor. This means that the link is good that the training was successful and that it's currently sending a video image to the monitor. If it's off it means that the link could not be established (for example because the cable was removed or the monitor is switched off or perhaps because the DisplayPort input is not selected on that monitor). +- The one on the other end should be blinking at a rate of about one blink per second. This is a "pulse" of the pixel clock indicating that both the VGA and DisplayPort outputs are generating an image. If this LED doesn't blink no image of any kind can be seen on either VGA or DisplayPort, only RGB at 15 kHz. Under normal circumstances whether a DisplayPort monitor is plugged in or not this LED should be blinking. <<< === ZX81 -The https://en.wikipedia.org/wiki/ZX81[ZX81] was a home computer produced by Sinclair Research,designed to be a low-cost introduction to home computing for the general public. +The https://en.wikipedia.org/wiki/ZX81[ZX81] was a home computer designed by Sinclair Research to be a low-cost introduction to home computing for the general public. -The ZXTRES version has been made by avlixa, based on Grant Searle's ZX80 page. +The ZXTRES version was made by avlixa based on Grant Searle's ZX80 page. Features: -- Selectable ZX80/ZX81 (ZX80 currently working only in RGB mode) -- 16k/32k/48k RAM packs -- 8KB with CHR$128/UDG addon (not tested) -- QS CHRS (not tested) -- CHROMA81 -- Turbo in Slow mode: NoWait, x2, x8 -- YM2149 sound chip (ZON X-81 compatible) -- Joystick types: Cursor, Sinclar, ZX81, ZXpand -- PAL/NTSC timings -- Turbo loading of .o and .p files -- Load alternative ROM -- Program loading using the audio input +- 8KB with CHR$128/UDG addon (not tested). +- 16k/32k/48k RAM packs. +- Chroma 81 (colour support). +- Joystick types: Cursor, Sinclar, ZX81 and ZXpand. +- Load alternative ROMs. +- PAL/NTSC timings. +- Program loading using the audio input. +- QS CHRS (not tested). +- Turbo in Slow mode: NoWait, x2 and x8. +- Turbo loading of `O` and `P` files. +- YM2149 sound chip (ZON X-81 compatible). +- ZX80/ZX81 selectable (ZX80 currently working only in RGB mode). ==== microSD card format -You can use a microSD card with the first partition in FAT16 or FAT32 format to store ROM and tape files. +To store ROM and tape files, use a microSDcard with the first partition in FAT16 or FAT32 format. -You can copy a file named `ZX8X.ROM` (available at the https://github.com/avlixa/ZX81_MiSTer_zxdos/raw/master/roms/zx8x.rom[official repository] into folder `/zx81/roms`: it is a concatenation of ZX81 rom (8k) + ZX80 rom (4k). +You can copy a file called `ZX8X.ROM` (available at the https://github.com/avlixa/ZX81_MiSTer_zxdos/raw/master/roms/zx8x.rom[official repository] into folder `/zx81/roms`: it's a concatenation of ZX81 rom (8k) + ZX80 rom (4k). -See the <<#_cores,corresponding section>> for instructions of how to install the ZX81 core in ZXTRES. +See the <<#_cores,corresponding section>> for instructions on how to install the ZX81 core in ZXTRES. <<< ==== Keyboard -The PS/2 keyboard isn't mapped and the original machine keys layout is kept. For example, to obtain a `"` you have to type `Shift+P` or `Shift+0` to delete. +The PS/2 keyboard isn't mapped and the original machine keys layout is kept. For example to obtain a `"` you must type `Shift+P` or `Shift+0` to delete. **ZX80** @@ -1414,70 +1506,70 @@ image:img/keyboardZX81.jpg[scaledwidth=80%] ===== Special keys and buttons -During the core execution: +When the core is active: -- `F1`: Enable or disable the alternative chars -- `F5` or joystick button 2: Show or hide configuration menu -- `F9`: Disables or enables the MIC audio output, since some games make annoying sounds when enabled -- `F10`: Enables or disables playing the audio input through the audio output, to hear loading sounds while loading -- `Scroll Lock`: Switch between RGB and VGA video output -- `Ctrl+Alt+Supr`: Reset -- `Ctrl+Alt+Backspace`: Hard reset +- `F1`: Enable or switch off the alternative chararacters. +- `F5` or joystick button `2`: Show or hide configuration menu. +- `F9`: Enable or switch off the MIC audio output (some games make annoying sounds when enabled). +- `F10`: Enable or switch off playing the audio input through the audio output to hear loading sounds while loading. +- `Scroll Lock`: Switch between RGB and VGA video output. +- `Ctrl+Alt+Supr`: Soft reset. +- `Ctrl+Alt+Backspace`: Hard reset. <<< -==== Basic Guide +==== Overview -Pressing `F5` or joystick button 2 shows or hides the configuration menu. Cursor keys and `Enter` to select and choose menu options. +Press `F5` or joystick button `2` to show or hide the configuration menu. Use the cursor keys and `Enter` to select menu options. [.text-center] image:img/zx81.jpg[scaledwidth=70%] -The following options are available: +The available options are: -- Reset -- Load Tape -- Load ROM -- Configuration Options -- Exit +- Reset. +- Load Tape. +- Load ROM. +- Configuration Options. +- Exit. <<< [.text-center] image:img/zx81_2.jpg[scaledwidth=70%] -- Computer Model: ZX80/ZX81 -- Main RAM: 16K/32K -- Low RAM: Off/8KB -- Joystick: Cursor/Sinclair/ZX81 -- QS CHRS: Disabled/Enabled -- CHR$128/UDG: 128 chars/64 chars/Disabled -- Chroma81: Disabled/Enabled -- Inverse Video: Off/On -- Black Border: Off/On -- Slow mode speed: Original/No Wait/x2 -- Video frequency: 50Hz/60Hz +- Computer Model: ZX80, ZX81. +- Main RAM: 16K, 32K. +- Low RAM: Off, 8KB. +- Joystick: Cursor, Sinclair, ZX81. +- QS CHRS: Enabled, Disabled. +- CHR$128/UDG: 128 chars, 64 chars, Disabled. +- Chroma81: Enabled, Disabled. +- Inverse Video: Off, On. +- Black Border: Off, On. +- Slow mode speed: Original, No Wait, x2. +- Video frequency: 50Hz, 60Hz. -You can load a tape file selecting it from the menu, then enter the command `LOAD""` and `Enter` +You can load a tape file selecting it from the menu then enter the command `LOAD""` and `Enter`. [TIP] ==== -Some monitors stop playing audio if the video signal is lost. It's recommended to plug headphones or a external speaker if you want to hear the sound while loading a tape. +Some monitors stop playing audio if the video signal is lost. You should connect headphones or a external speaker if you want to hear the sound while loading a tape. ==== -`.p` files with colorization and char are supported. +`.p` files with colourization and char are supported. -For colorization to work, CHROMA81 should be enabled before loading. For alternate chars, QS CHRS should be enabled before loading. +For colourization to work CHROMA81 should be enabled before loading. For alternate chars QS CHRS should be enabled before loading. [TIP] ==== The recommended options for most games are: -Main RAM: 16KB -Low RAM: 8KB -CHR$128: 128 chars -QS CHRS: enabled -CHROMA81: enabled +Main RAM: 16KB. +Low RAM: 8KB. +CHR$128: 128 chars. +QS CHRS: Enabled. +CHROMA81: Enabled. ==== <<< @@ -1486,53 +1578,53 @@ CHROMA81: enabled <<< -== Other Hardware +== Other hardware === Loading from tape -Some cores can load, as the original machines could, from a external audio device like a cassette player or something else simulating it. +Some cores can load from an external device such as a cassette tape player, just like the original machines. -Besides the card, you have to plug an appropriate audio cable to <<#_ports_and_connectors,ZXTRES audio input>>. It must have a 3.5 mm stero jack on one side, and two mono outputs on the other side (one for each audio channel). The right audio mono is connected to the audio player (this is not necessary with a miniduino, since it already uses only the right audio channel when playing). +Besides the microSD card you must connect an appropriate audio cable into the <<#_ports_and_connectors,ZXTRES audio input>>. It must have a 3.5mm stero jack on one side and two mono outputs on the other side (one for each audio channel). The right audio is connected to the audio player (this is not necessary with a miniduino because it already uses only the right audio channel when playing). -==== Cassette Player +==== Cassette tape player -The use is exactly the same as when using the original computers: +This works exactly the same way as when using it with the original computers: -. Plug the audio cable -. Type on the computer or select the tape loading option. For examle, for ZX Spectrum 48K, typing `J`, then, twice, `"` and then `Enter` to do the classic `LOAD "" + Enter` -. Start playing the tape (you may have to try several times adjusting the player volume) +. Connect the audio cable. +. Type on the computer or select the tape loading option. For examle, for ZX Spectrum 48K press `J` (`LOAD`), `""` and `Enter` to start loading. +. Start playing the tape (you may need to try several times, adjusting the player volume). ==== Computer -Depending on the operating system (Windows, MacOS, Linux) there are several programs that can either play a tape file (`TAP`, `TZX`, `PZX`, etc.) and output the sound through a headphone output, or create an audio file (`WAV`, `VOC`, `AU`, etc.) that can be played using a music or audio program. +Depending on the operating system (Windows, macOS or Linux) there are several programs that can either play a tape file (`TAP` `TZX` `PZX` and so on) and output the sound through a headphone output or create an audio file (`WAV` `VOC` `AU` and so on) that can be played using a music or audio program. ===== PlayTZX -This program for Windows, MacOS or Linux, can play directly a `TZX` tape file through the audio output of the computer. +This program for Windows, macOS and Linux can directly play a `TZX` tape file through the computer's audio output. -You can download the binary file (for example), for Windows from https://worldofspectrum.net/utilities/#tzxtools[World of Spectrum Classic] and for Mac from https://github.com/kounch/playtzx/releases[this GitHub repository]) or compile the source code as <<#_compile_source_code_macos_or_linux,explained later>>. +You can download the application for Windows from https://worldofspectrum.net/utilities/#tzxtools[World of Spectrum Classic] and for Mac from https://github.com/kounch/playtzx/releases[this GitHub repository]) or compile the source code as <<#_compile_source_code_macOS_or_linux,explained later>>. -. Plug the audio cable between the computer audio output and ZXTRES audio input (remember to use only the right mono channel to the PC, Mac, etc. output) -. Type on the computer or select the tape loading option. For examle, for ZX Spectrum 48K, typing `J`, then, twice, `"` and then `Enter` to do the classic `LOAD "" + Enter` -. Start playing a tape file with this command (you may have to try several times adjusting the player volume) +. Connect the audio cable between the computer audio output and ZXTRES audio input (remember to use only the right mono channel to the PC Mac and so on output). +. Type on the computer or select the tape loading option. For examle for ZX Spectrum 48K typing `J` then twice `"` and then `Enter` to do the classic `LOAD "" + Enter`. +. Start playing a tape file with this command (you may need to try several times adjusting the player volume). [source,shell] ---- ./playtzx ---- -If everything works fine, you will see at the shell the name of the different tape data blocks, while the sound is played and the ZXTRES core loads the program. +If everything worked correctly, you'll see at the shell the name of the different tape data blocks while the sound is played and the ZXTRES core loads the program. [TIP] ==== -On Linux, the program uses as output the device `/dev/dsp`, this may require to load a module like `snd_pcm_oss` (on systems using ALSA). +On Linux the program uses as output the device `/dev/dsp` this may require you to load a module like `snd_pcm_oss` (on systems using ALSA). ==== -====== Compile source code (MacOS or Linux) +====== Compile source code (macOS and Linux) -To compile, the first thing is checking that the developer tools are installed on the system, including a C compiler (`gcc`, `clang`, command line developer tools for Mac, etc.) and https://es.wikipedia.org/wiki/GNU_build_system[GNU Autotools]. +Beofre compiling, ensure that the developer tools are installed on the system including a C compiler (`gcc` `clang` command line developer tools for Mac and so on) and https://es.wikipedia.org/wiki/GNU_build_system[GNU Autotools]. -Download the source code https://github.com/kounch/playtzx[from this repository]), extract the contents if needed and access from a terminal to the directory and type the commands: +Download the source code https://github.com/kounch/playtzx[from this repository]), extract the contents if required, in the terminal navigate to the folder and enter: [source,shell] ---- @@ -1541,30 +1633,30 @@ aclocal && autoconf && autoheader && automake --add-missing make ---- -If all goes well, a new file named `playtzx` has been created, which you can copy anywhere and then use. You can delete the compilation directory. +If everything worked correctly, a new file called `playtzx` is created that you can copy anywhere and then use. You can remove the compilation folder. -==== Mobile phone, tablet, MP3 player, etc. +==== Mobile phone tablet MP3 player and so on -There are a very few apps (or none) that can directly play a tape file on a mobile device so, in many cases, the only option is to convert it to an audio file before playing it. +There are only a few apps (or none) that can directly play a tape file on a mobile device so in many cases the only option is to convert it to an audio file before playing it. -https://play.google.com/store/apps/details?id=com.baltazarstudios.playzxtapes[PlayZX] is an App for Android which can play tape files through the headphone output. +https://play.google.com/store/apps/details?id=com.baltazarstudios.playzxtapes[PlayZX] is an app for Android that can play tape files through the headphone output. [WARNING] ==== -The latest devices with headphone output are normally designed to work with impedances of only a few ohmis. This may, sometimes, not be enouth for the ZXTRES audio input. +The latest devices with headphone output are typically designed to work with impedances of only a few ohmis. This may sometimes not be enouth for the ZXTRES audio input. -In these cases, it's recommended (if possible) to disable headphone volume limitations and/or use a headphone amplifier that can give a higher impedance. +In these cases you should (if possible) to switch off headphone volume limitations or use a headphone amplifier that can give a higher impedance. ==== ===== Audio file conversion -These are some of the many programas that exist and which can export tape files to audio files. +These are some programas that exist which can export tape files to audio files. -https://www.alessandrogrussu.it/tapir/index.html[Tapir] is a GUI program for Windows (but which can also run with Wine on Linux or Mac) that can load `TZX` and `TAP` files and export to `WAV` audio +https://www.alessandrogrussu.it/tapir/index.html[Tapir] is a GUI program for Windows (but that can also run with Wine on Linux or versions of macOS with 32-bit Intel support) that can load `TZX` and `TAP` files and export to `WAV` audio `tape2wav` from https://fuse-emulator.sourceforge.net/[Fuse Utilities] is a command line utility that can export from `TZX` `PZX` and `TAP` to `WAV`. -`pzx2wav` in http://zxds.raxoft.cz/pzx.html[PZX Tools] is another command line utility which exports to `WAV`. +`pzx2wav` in http://zxds.raxoft.cz/pzx.html[PZX Tools] is another command line utility that exports to `WAV`. <<< @@ -1578,33 +1670,33 @@ include::miniduino_en.adoc[leveloffset=+3] === Firmware images management -There are several tools with you can use to make and/or edit the contents of `ZX1`, `ZX3` files. +There are several tools that you can use to create or edit the contents of `ZX1` and `ZX3` files. ==== zx123_tool -This is a tool to analyze, extract and inject data in SPI flash image files for ZX-Uno, ZXDOS and similar devices. +This tool enables you to analyse, extract and inject data in SPI flash image files for ZX-Uno, ZXDOS, ZXTRES and similar devices. -You need to have https://www.python.org/[Python 3] to use it. Depending on the operating system you may have to https://www.python.org/downloads/[install it]. +It requires https://www.python.org/[Python 3]. Depending on the operating system you may need to https://www.python.org/downloads/[install it]. -Having Python 3, you only need to download the latest version of the tool from the official repository, following https://github.com/kounch/zx123_tool/releases/latest[this link]. +With Python 3 installed, you only need to download the latest version of the tool from the official repository following https://github.com/kounch/zx123_tool/releases/latest[this link]. -Once extracted, you have to run from a shell the main script using Python 3. This may change depending on the operating system. +After you've extracted the tool, you can run it from the command line. The command varies depending on the operating system. -For example, on Windows, it's usually: +Typically, on Windows it's: [source,shell] ---- py -3 zx123_tool.py ---- -With other operating systems it normally is like: +Otherwise, it's typically: [source,shell] ---- python3 ./zx123_tool.py ---- -You also need a SPI flash image file. This can be obtained from within the Spectrum core in "root" mode, with one of the commands `back16m`, `backzx2` or `backzxd`. Once you have obtained the exteacted file from the microSD, you can "clean" it leaving only the Spectrum core and the first Spectrum ROM with a command like this: +You also need an SPI flash image file. This can be obtained from within the ZX Spectrum core with one of the commands `back16m` `backzx2` or `backzxd`. After you've obtained the exteacted file from the microSD card you can "clean" it leaving only the ZX Spectrum core and the first Spectrum ROM: [source,shell] ---- @@ -1617,14 +1709,14 @@ Where `FLASH.ZXD` is the path to the original file and `FLASHempty.ZXD` is the p *List the contents of an image* -To see the contents of an image file named `FLASH.ZXD` (installed cores and some configuration info), you can use the command +To view the contents of an image file called `FLASH.ZXD` (installed cores and some configuration information): [source,shell] ---- ... zx123_tool.py -i FLASH.ZXD -l ---- -To show the contents of the same file, including ZX Spectrun ROMs info: +To show the contents of the same file including ZX Spectrun ROMs information: [source,shell] ---- @@ -1633,131 +1725,132 @@ To show the contents of the same file, including ZX Spectrun ROMs info: *Change the BIOS of an image* -To change the BIOS inside a file named `FLASH.ZXD`, using the BIOS file named `FIRMWARE.ZXD` +To change the BIOS inside a file called `FLASH.ZXD` using the BIOS file called `FIRMWARE.ZXD`: [source,shell] ---- ...zx123_tool.py -i FLASH.ZXD -a BIOS,FIRMWARE.ZXD ---- -You can, at the same time, modify some of the default parameters. For example, with the options; `-m` for video mode: 0 (PAL), 1 (NTSC) or 2 (VGA), `-k` for the keyboard layout: 0 (Auto), 1 (ES), 2 (EN) or 3 (Spectrum). +You can modify some parameters. For example with the options; `-m` for video mode: 0 (PAL), 1 (NTSC), or 2 (VGA), `-k` for the keyboard layout: 0 (Auto), 1 (ES), 2 (EN) or 3 (Spectrum). -This way to change the BIOS of a file named `FLASH.ZXD`, using the BIOS file `FIRMWARE.ZXD`, and also set the video mode to VGA: +To change the BIOS of a file called `FLASH.ZXD` using the BIOS file `FIRMWARE.ZXD` and also set the video mode to VGA: [source,shell] ---- ...zx123_tool.py -i FLASH.ZXD -a BIOS,FIRMWARE.ZXD -m 2 -k 3 ---- -There are also options to set the BIOS boot delay time, the default core or the default Spectrum ROM. See the https://github.com/kounch/zx123_tool/[documentation] for more info. +There are also options to set the BIOS boot delay time, the default core and the default Spectrum ROM. For more information, refer to the https://github.com/kounch/zx123_tool/[documentation]. <<< *Add a Spectrum ROM to an image* -To add a Spectrum ROM file named `48.rom`, with the name `Spec48` and using the slot number 5, you can use a command like: +To add a Spectrum ROM file called `48.ROM` with the name `Spec48` and using the slot number five: [source,shell] ---- ...zx123_tool.py -i FLASH.ZXD -a ROM,5,xdnlh17,Spec48,48.rom ---- -See the https://github.com/kounch/zx123_tool/[documentation] for all the possible options when adding a Spectrum ROM. +Refer to the https://github.com/kounch/zx123_tool/[documentation] for all possible options when adding a Spectrum ROM. -Amongst the information you give when adding a ROM, there are some flags used to tell which hardware options, etc, you want to have enabled or disabled when loading the ROM, as shown in this table: +Among the information you provide when adding a ROM there are some flags. These configure the hardware options used when loading the ROM: [align="center",width="70%",%header,cols=2*] |=== |`i` -|Keyboard issue 3 enabled (instead of issue 2) +|Keyboard issue 3 enabled (instead of issue 2). |`c` -|Disable memory contention +|Switch off memory contention. |`d` -|Enable DivMMC +|Enable divMMC. |`n` -|Enable NMI DivMMC (esxdos Menu) +|Enable NMI divMMC (esxDOS NMI browser). |`p` -|Use Pentagon Timings +|Use Pentagon timings. |`t` -|Use 128K timings +|Use 128K timings. |`s` -|Disable DivMMC and ZXMMC ports +|Switch off divMMC and ZXMMC ports. |`m` -|Enable Timex Horizontal MMU +|Enable Timex Horizontal MMU. |`h` -|Disable ROM high bit (1FFD bit 2) +|Switch off ROM high bit (1FFD bit 2). |`l` -|Disable ROM low bit (7FFD bit 4) +|Switch off ROM low bit (7FFD bit 4). |`1` -|Disable 1FFD port (+2A/3 paging) +|Switch off 1FFD port (+2A/3 paging). |`7` -|Disable 7FFD port (128K paging) +|Switch off 7FFD port (128K paging). |`2` -|Disable TurboSound (secondary AY chip) +|Switch off TurboSound (secondary AY chip). |`a` -|Disable AY chip +|Switch off AY chip. |`r` -|Disable Radastanian mode +|Switch off Radastanian mode. |`x` -|Disable Timex mode +|Switch off Timex mode. |`u` -|Disable ULAPlus +|Switch off ULAplus. |=== <<< -*Install a Core to an image* +*Install a core to an image* -For example, to install a core in space 3, from a file named `NEXT.ZXD`, with the name `Spectrum Next`, use a command like this: +To install a core in slot three from a file called `SPECNEXT.ZXD` with the name `SpecNext`: [source,shell] ---- -...zx123_tool.py -i FLASH.ZXD -a 'CORE,3,Spectrum Next,NEXT.ZXD' +...zx123_tool.py -i FLASH.ZXD -a 'CORE,3,SpecNext,SPECNEXT.ZXD' ---- -If you want also to set the core as the default, use a command like: +To also set the core as the default: [source,shell] ---- -...zx123_tool.py -i FLASH.ZXD -a 'CORE,3,Spectrum Next,NEXT.ZXD' -c 3 +...zx123_tool.py -i FLASH.ZXD -a 'CORE,3,SpecNext,SPECNEXT.ZXD' -c 3 ---- -*Change esxdos ROM of an image* +*Change esxDOS ROM from an image* -Just like the BIOS firmware, you can install a ROM esxdos file, with a command like this: +As with the BIOS firmware you can install an esxDOS ROM file: [source,shell] ---- ...zx123_tool.py -i FLASH.ZXD -a esxdos,ESXMMC.BIN ---- -*Mix several actions in one line* +*Combine several actions in one line* -Please do note that you can add several actions in one command line. For example, to "clean" an image file named `FLASH.ZXD`, creating a new one named `FLASHnew.ZXD`, installing the BIOS from the file `FIRMWARE.ZXD`, set up video mode to VGA, the keyboard in Spectrum mode, add a Spectrum ROM file `48.rom`, with the name `Spec48` while ussing slot number 5, install a core at space 3, from a file named `NEXT.ZXD`, with the name `Spectrum Next`, as default core: +You can combine several actions in one command line. For example to "clean" an image file called `FLASH.ZXD` creating a new one called `FLASHnew.ZXD` installing the BIOS from the file `FIRMWARE.ZXD` set up video mode to VGA the keyboard in Spectrum mode add a Spectrum ROM file called `48.rom` with the name `Spec48` while using slot five install a core at slot three from a file called `SPECNEXT.ZXD` with the name `SpecNext` as default core: [source,shell] ---- -... zx123_tool.py -i FLASH.ZXD -w -o FLASHnew.ZXD -a BIOS,FIRMWARE.ZXD -m 2 -k 3 -a ROM,5,xdnlh17,Spec48,48.rom -a CORE,3,SpecNext,NEXT.ZXD -c 3 +... zx123_tool.py -i FLASH.ZXD -w -o FLASHnew.ZXD -a BIOS,FIRMWARE.ZXD -m 2 -k 3 -a ROM,5,xdnlh17,Spec48,48.rom -a CORE,3,SpecNext,SPECNEXT.ZXD -c 3 ---- <<< === Firmware recovery -Sometimes (e.g. when installing an experimental core or when upgrading the ZX Spectrum Core or the BIOS) it may happen that the ZXTRES stops booting. The board LEDs are on, but there is no display, and it doesn't do anything when trying the different key combinations to access BIOS setup, etc. -When this happens, there are several recovery methods that let you install again the firmware. +Sometimes it may happen that the ZXTRES stops booting, for example when installing an experimental core or when upgrading the ZX Spectrum Core or the BIOS. The ZXTRES board LEDs are on but there's no display and it doesn't do anything when trying the different key combinations to access BIOS setup and so on. + +When this happens there are several recovery methods to enable you to restore the firmware. ==== JTAG cable connections -Later, in some of the recovery steps, when talking about jump wires or USB-Blaster connections to the ZXTRES board, you can use these images as reference. +You can use these images as a reference in some recovery steps when using jump wires or USB-Blaster connections to the ZXTRES board. [.text-center] image:img/jtagzxtres.jpg[scaledwidth=80%] [WARNING] ==== -*DO NOT* connect the 3V line +*Don't* connect the 3V line. ==== <<< @@ -1766,22 +1859,23 @@ image:img/jtagzxtres.jpg[scaledwidth=80%] *Hardware required*: -- Raspberry Pi (with SD card, keyboard, display, power supply, etc.) and with internet connection -- 5 https://en.wikipedia.org/wiki/Jump_wire[jump wires] (if possible, female on both sides) or, instead a USB-Blaster cable -- One screwdriver for ZXTRES cover screws -- SD for ZXTRES with the first partition formatted as FAT16 or FAT32 -- Keyboard and display for ZXTRES +- Raspberry Pi (with microSD card, keyboard, display, power supply and so on) and with internet connection. +- Five https://en.wikipedia.org/wiki/Jump_wire[jump wires] (if possible female on both sides) or instead a USB-Blaster cable. +- A hex key (Allen key) for the ZXTRES cover screws. +- A microSD card with the first partition formatted as FAT16 or FAT32 for the ZXTRES. +- Keyboard and display for the ZXTRES. *Software required*: -- Flash image and recovery file for ZXTRES from https://github.com/zxtres/cores/tree/main/recovery[the main Github repository]. Please take note that there is a different file for each device: +Flash image and recovery file for ZXTRES from https://github.com/zxtres/cores/tree/main/recovery[the main Github repository]. Note, there are different files for each device: + ** `recovery_a35.bit` for ZXTRES ** `recovery_a100.bit` for ZXTRES+ ** `recovery_a200.bit` for ZXTRES++ -*Instruction Steps*: +*Instruction steps*: -. Install Raspberry Pi OS (formerly known as Raspbian) to the Raspberry Pi SD card (using https://www.raspberrypi.org/downloads/raspberry-pi-os/[the official download], https://www.raspberrypi.org/downloads/noobs/[NOOBS], https://github.com/procount/pinn[PINN], etc.) +. Install Raspberry Pi OS (formerly known as Raspbian) to the Raspberry Pi microSD card (using https://www.raspberrypi.org/downloads/raspberry-pi-os/[the official download] https://www.raspberrypi.org/downloads/noobs/[NOOBS] https://github.com/procount/pinn[PINN] and so on). . Install Open OCD: [source,shell] @@ -1803,14 +1897,14 @@ rm -rf ./openocd-code <<< [start=3] -. Connect USB-Blaster or jump wires if using GPIO. In this case, open the ZXTRES case and, <<#_jtag_cable_connections,as explained before>> connect the FPGA JTAG lines (`TMS`, `TDI`, `TDO`, `TCK` and `GND`), using the wires, to the Raspberry Pi https://es.wikipedia.org/wiki/GPIO[GPIO] pins. +. Connect the USB-Blaster or jump wires if using GPIO. In this case open the ZXTRES case and <<#_jtag_cable_connections,as explained before>> connect the FPGA JTAG lines (`TMS` `TDI` `TDO` `TCK` and `GND`) using the wires to the Raspberry Pi https://es.wikipedia.org/wiki/GPIO[GPIO] pins. -Is using a GPIO connection, take note of the chosen pins, making sure that `GND` is connected with `GND`. +If using a GPIO connection, take note of the chosen pins and ensure that `GND` is connected with `GND`. [.text-center] image:img/gpio.jpg[scaledwidth=70%] -In this example, the `31`, `33`, `35`, `37` and `39` pins will be used (corresponding to `GPIO #6`, `GPIO #13`, `GPIO #19`, `GPIO #26` and `GND`), like this: +In this example the `31` `33` `35` `37` and `39` pins are used (corresponding to `GPIO #6` `GPIO #13` `GPIO #19` `GPIO #26` and `GND`): [%header,cols=3*] |=== @@ -1835,9 +1929,9 @@ In this example, the `31`, `33`, `35`, `37` and `39` pins will be used (correspo |=== [start=4] -. Copy to the Raspberry Pi the file named `recovery_axx.bit` previously downloaded from https://github.com/zxtres/cores/tree/main/recovery[the main Github repository]. For our example, it will be at `/home/pi/zxtres/unbrick/` +. Copy the file called `recovery_axx.bit` previously downloaded from https://github.com/zxtres/cores/tree/main/recovery[the main Github repository] to the Raspberry Pi. In this example it's at `/home/pi/zxtres/unbrick/` -. If using GPIO, make a copy of Open OCD configuration file, to the same directory where `recovery.bit` is. +. If using GPIO, make a copy of the Open OCD configuration file to the folder where `recovery.bit` is located. [source,shell] ---- @@ -1847,7 +1941,7 @@ cp /usr/local/share/openocd/scripts/interface/raspberrypi2-native.cfg /home/pi/z <<< [start=6] -. For GPIO connection, edit `raspberrypi2-native.cfg` copy, updating `bcm2835gpio_jtag_nums` (uncommenting, if necessary), with your JTAG and GPIO connection numbers, at the line `bcm2835gpio_jtag_nums`. For our example: +. For GPIO connection edit a copy of `raspberrypi2-native.cfg`, updating `bcm2835gpio_jtag_nums` (uncommenting if necessary) with your JTAG and GPIO connection numbers at the line `bcm2835gpio_jtag_nums`: [source] ---- @@ -1856,7 +1950,7 @@ bcm2835gpio_jtag_nums 26 6 13 19 ---- [start=7] -. Comment, if it wasn't already, the line `bcm2835gpio_swd_nums` (not necessary for USB-Blaster connection): +. Ensure the line `bcm2835gpio_swd_nums` is commented out (not necessary for USB-Blaster): [source] ---- @@ -1864,7 +1958,7 @@ bcm2835gpio_jtag_nums 26 6 13 19 ---- [start=8] -. Add, to the end of the file, the line `adapter speed 250` (again, not necessary for USB-Blaster): +. Add `adapter speed 250` to the end of the file the line (not necessary for USB-Blaster): [source] ---- @@ -1872,9 +1966,9 @@ adapter speed 250 ---- [start=9] -. Turn on the ZXTRES. +. Power on the ZXTRES. -. Make sure that, on the Raspberry Pi, we are in the directory where `recovery_axx.bit` is, and execute the command that loads the BIOS on recovery mode, using the path to the previously edited `raspberrypi2-native.cfg`. +. Ensure that on the Raspberry Pi you're in the folder where `recovery_axx.bit` is located and run the command that loads the BIOS on recovery mode using the path to the previously edited `raspberrypi2-native.cfg`. For GPIO connection: @@ -1894,42 +1988,42 @@ sudo openocd -f /usr/local/share/openocd/scripts/interface/altera-usb-blaster.cf [TIP] ==== -Remember to type the right name replacing `recovery_axx.bit` in the previous commands. +Remember to enter the correct name replacing `recovery_axx.bit` in the previous commands. ==== <<< [start=11] -. If all goes well, we will see that the FPGA LED change their state and the BIOS is shown on the display. +. If everything worked correctly, you'll see that the FPGA LED change their state and the BIOS is shown on the display. -If there is no image on the display, and you are not using DisplaPort, press `Scroll Lock`to switch between RGB and VGA modes, just in case the recovery BIOS did start in the wrong mode for our setup. +If there's no image on the display and you're not using DisplaPort, press `Scroll Lock` to switch between RGB and VGA modes in case the recovery BIOS started in the wrong mode for your setup. [.text-center] image:img/recovery.png[scaledwidth=70%] [start=12] -. Insert in the ZXTRES the SD card formatted as FAT16 o FAT32, and with the `FLASH.ZX3` file downloaded previously. +. Insert the microSD card formatted as FAT16 o FAT32 and with the `FLASH.ZX3` file downloaded previously in the ZXTRES. -. If using a USB-Blaster connection, unplug the connector. +. If using a USB-Blaster connection, disconnect the connector. <<< [start=14] -. Select the option `Upgrade Flash from SD`. Press Enter, choose `Yes`, and press Enter again to start the Flash writing process. +. Select the `Upgrade Flash from SD` opiton. Press `Enter`, choose `Yes` and press `Enter` again to start the flash writing process. [.text-center] image:img/recovery2.png[scaledwidth=70%] [WARNING] ==== -This process can't be undone, and it will replace all the previously installed cores, the BIOS, the ZX Spectrum ROMs and their configuration with the data in the image file. +This process can't be undone and replaces all previously installed cores, the BIOS, the ZX Spectrum ROMs and their configuration with the data in the image file. ==== [start=15] -. After some minutes, the process will end, and, after turning the ZXTRES off and on, it should start fine. +. After some minutes the process ends and on power cycling the ZXTRES it should start. [NOTE] ==== -If no image is shown, and you are not using DisplaPort, press again `Scroll Lock` to switch between RGB and VGA modes. In this case, you should have to enter the BIOS and change <<#_advanced, the right advanced setting>> that matches your display. +If no image is shown and you're not using DisplaPort, press `Scroll Lock` again to switch between RGB and VGA modes. In this case you must enter the BIOS and change <<#_advanced the right advanced setting>> that matches your display. ==== <<< @@ -1949,17 +2043,17 @@ https://zxuno.speccy.org/index.shtml[ZX-Uno] http://desubikado.sytes.net/zx-uno-faq-version-desubikado/[ZX-Uno FAQ] -https://docs.google.com/document/d/1NI0zgCDRk7c-5CVi-lfZEK6q8Lnpnco7PhpsEEdxD60/edit[Guía rápida del ZX-Uno] +https://docs.google.com/document/d/1NI0zgCDRk7c-5CVi-lfZEK6q8Lnpnco7PhpsEEdxD60/edit[ZX-Uno Quick Guide] -https://www.zxuno.com/wiki/index.php/ZX_Spectrum[Core ZX Spectrum] +https://www.zxuno.com/wiki/index.php/ZX_Spectrum[ZX Spectrum core] https://worldofspectrum.org/zxplus3e/index.html[The ZX Spectrum +3e Homepage] https://worldofspectrum.org/zxplus3e/sharingdisks.html[Sharing a +3e disk with PC (FAT) partitions] -https://www.zxuno.com/forum/viewtopic.php?f=37&t=208[Layouts de teclado] +https://www.zxuno.com/forum/viewtopic.php?f=37&t=208[Keyboard Layouts] -https://github.com/spark2k06/zxunops2/blob/master/Alternative/Nuevo%20firmware%20de%20teclado%20ZX-GO%2B.pdf[Firmware de teclado para ZX Go+] +https://github.com/spark2k06/zxunops2/blob/master/Alternative/Nuevo%20firmware%20de%20teclado%20ZX-GO%2B.pdf[Keyboard firmware for ZX Go+] https://github.com/zxdos/zxdos-plus/tree/master/zxunops2[zxunops2] @@ -1969,16 +2063,16 @@ https://www.va-de-retro.com/foros/viewtopic.php?t=1718&start=10#p25076[Cargando http://retrowiki.es/viewtopic.php?f=83&t=200032578&p=200075671&hilit=wifi#p200075671[WiFi (RetroWiki)] -https://www.zxuno.com/forum/viewtopic.php?f=35&t=44[WiFi en ZX-Uno] +https://www.zxuno.com/forum/viewtopic.php?f=35&t=44[WiFi on ZX-Uno] -https://svn.zxuno.com/svn/zxuno/cores/spectrum_v2_spartan6/test19_multi_uart/[Core de ZX-Uno Test UART (WiFi)] +https://svn.zxuno.com/svn/zxuno/cores/spectrum_v2_spartan6/test19_multi_uart/[ZX-Uno Core Test UART (WiFi)] https://nihirash.net/network-tools-for-zx-uno-pack/[Network tools for ZX-Uno pack] https://www.espressif.com/sites/default/files/documentation/4a-esp8266_at_instruction_set_en.pdf[ESP8266 AT Instruction Set] -https://www.zonadepruebas.com/viewtopic.php?t=4796&start=110[Vídeos Radastanianos] +https://www.zonadepruebas.com/viewtopic.php?t=4796&start=110[Radastanian Vídeos] -https://www.zxuno.com/forum/viewtopic.php?f=52&t=4074&p=28234&hilit=kyp#p28234[Nuevo core zx48] +https://www.zxuno.com/forum/viewtopic.php?f=52&t=4074&p=28234&hilit=kyp#p28234[New core zx48] -https://github.com/rcmolina/MaxDuino_BETA/blob/master/MANUAL%20por%20desUBIKado/MAXDUINO%20Gu%C3%ADa%20de%20uso.pdf[Maxduino - guía de uso] +https://github.com/rcmolina/MaxDuino_BETA/blob/master/MANUAL%20por%20desUBIKado/MAXDUINO%20Gu%C3%ADa%20de%20uso.pdf[Maxduino - user's guide] diff --git a/doc/src/miniduino_en.adoc b/doc/src/miniduino_en.adoc index 2a440c2..34d1d57 100644 --- a/doc/src/miniduino_en.adoc +++ b/doc/src/miniduino_en.adoc @@ -1,6 +1,6 @@ -https://www.antoniovillena.es/store/product/miniduino/[Miniduino] is a tape file audio player, based on a STM32F103C8T6 microcontroller or ATMega38P, and https://github.com/rcmolina/MaxDuino_BETA[Maxduino] firmware preinstalled. +https://www.antoniovillena.es/store/product/miniduino/[Miniduino] is a tape file audio player, based on an STM32F103C8T6 microcontroller or ATMega38P with the https://github.com/rcmolina/MaxDuino_BETA[Maxduino] firmware preinstalled. -Maxduino plays, in a very similar way to how https://es.wikipedia.org/wiki/Casete[cassette tape] players worked, digital tape files in format as like `TAP` and `TZX` (ZX Spectrum), `O` (ZX80), `P` (ZX81), `CDT` (Amstrad CPC), `CAS`(MSX) `TSX` (MSX, Acorn, etc). It is also possible to play AY music files as if they were tapes, in order to load the from http://www.specay.co.uk[SpecAY] in a ZX Spectrum. +Maxduino works in a similar way to https://es.wikipedia.org/wiki/Casete[cassette tape] players, using digital tape files formats such as `TAP` and `TZX` (ZX Spectrum), `O` (ZX80), `P` (ZX81), `CDT` (Amstrad CPC), `CAS`(MSX) `TSX` (MSX, Acorn, etc). It's also possible to play AY music files as if they were tapes, to load them from http://www.specay.co.uk[SpecAY] in a ZX Spectrum. == Ports and buttons @@ -30,69 +30,69 @@ image:img/MiniduinoFront.jpg[scaledwidth=50%] == Configuration -A SD is needed in order to store the tape files to play. Fast cards (Class 10 or greater) aren't recommended because there can be problems while reading the data. High capacity (SDXC or greater) cards aren't recommended too. +An SD card is required to store the tape files to play. Fast cards (Class 10 or greater) aren't recommended because there can be problems while reading the data. High capacity (SDXC or greater) cards aren't recommended either. -The card must have the first partition formatted as FAT16 or FAT32. +The SD card must have the first partition formatted as FAT16 or FAT32. -Besides the card, you have to plug an appropriate audio cable to <<#_ports_and_connectors,audio input>>. It must have a 3.5 mm stereo jack on one side, and two mono output on the other side (one for each audio channel). The right audio mono is connected to the Miniduino. +Besides the card, you must connect an appropriate audio cable to <<#_ports_and_connectors,audio input>>. It must have a 3.5mm stereo jack on one side, and two mono output on the other side (one for each audio channel). The right audio mono is connected to the Miniduino. -If you have a device that can use motor control, you can also use a cable with a 2.6 mm jack. +If you have a device that can use motor control, you can also use a cable with a 2.6mm jack. -Copy the tape files (`TAP`, `TZX`, `O`, `P`, `CAS`, `TSX`, etc) to the first partition of the SD card. They can be organized using folders or directories. +Copy the tape files (`TAP`, `TZX`, `O`, `P`, `CAS`, `TSX` and so on) to the first partition of the SD card. They can be organised using folders or directories. [TIP] ==== -The player shows file and directory entries in the order stored in the internal FAT table, and not alphabetically. If you want to see them ordered, you have to reorder the SD card structure with a utility like Fat Sorter for Windows, https://fatsort.sourceforge.io/[FATsort] for Linux and MacOS, https://www.luisrios.eti.br/public/en_us/projects/yafs/[YAFS], http://www.trustfm.net/software/utilities/SDSorter.phpp[SDSorter] or other. +The player shows file and folder entries in the order stored in the internal FAT table, not alphabetically. If you want to see them ordered you must reorder the SD card structure with a utility such as https://fatsort.sourceforge.io/[FATsort], https://www.luisrios.eti.br/public/en_us/projects/yafs/[YAFS], http://www.trustfm.net/software/utilities/SDSorter.phpp[SDSorter] or another application. ==== <<< == Use -Once the SD card with the data files is inserted, it's turned on plugging in the included USB power cable. +After the SD card with the data files is inserted, power it on by connecting the included USB power cable. [.text-center] image:img/MiniduinoLogo.jpg[scaledwidth=30%] -Pressing down the control button shows the options menu which can set the following: +To show the optional menu, hold down the control button: -- Baud Rate: Configures turbo speed baud rates when playing 4B blocks in MSX files (`CAS` and `TSX`) -- Motor Ctrl: Enable this option when a control cable is connected to a proper device (Amstrad, CPC, MSX, etc.) -- Converter (TSXCzxpUEFWS): Enables turbo loading `.CAS` and `.TSX` files, changes signal for Spectrum and Amstrad CPC files and/or change parity when playing Acorn Electron and BBC Micro `.UEF` files -- (Skip BLK)): To disable (Skip ON) or enable automatic pause when 2A blocks are found +- Baud Rate: Configures turbo speed baud rates when playing 4B blocks in MSX files (`CAS` and `TSX`). +- Motor Ctrl: Enable this option when a control cable is connected to a proper device (Amstrad, CPC, MSX and so on). +- Converter (TSXCzxpUEFWS): Enables turbo loading `CAS` and `TSX` files, changes signal for Spectrum and Amstrad CPC files or change parity when playing Acorn Electron and BBC Micro `UEF` files. +- (Skip BLK)): To switch off (Skip ON) or enable an automatic pause when 2A blocks are found. -When not inside the options menu, the control button is used as a four directional control joystick, which has two different behaviours depending whether the player is stopped or paused. +Outside the options menu, the control button is used as a four directional control joystick that has two different behaviours depending on whether the player is stopped or paused. [.text-center] image:img/MiniduinoVersion.jpg[scaledwidth=30%] When the player is stopped (file and directories browser): -- Up and Down move through the current files and directories list -- Left (Stop) goes one level up in the directory tree -- Right (Play/Pause) enters into a directory or, if the selection is a file, tries to play it +- Up and Down move through the current files and folders list. +- Left (Stop) goes one level up in the folder tree. +- Right (Play/Pause) enters a folder or, if the selection is a file, tries to play it. <<< -Once a file is being played, stop playing it with the left button (Stop) or pause using the right button (Play/Pause). +When a file is playing you can stop it with the left button (Stop) or pause using the right button (Play/Pause). [.text-center] image:img/MiniduinoPlay.jpg[scaledwidth=30%] When in pause (tape block browser: -- Up and Down mov through the tape block files already played (useful for multiload titles, to load a previous level block, for example) -- Left (Stop) cancels the player and goes back to file and directory browser mode -- Right (Play/Pause) continues playing from the selected block -- Press down the control button to enable or disable turbo mode for MSX +- Up and Down move through the tape block files already played (useful for multiload titles or to load a previous level block). +- Left (Stop) cancels the player and goes back to file and folder browser mode. +- Right (Play/Pause) continues playing from the selected block. +- Press down the control button to enable or disable turbo mode for MSX. == Making TZX or TSX files from other formats -While there are same tape file formats (Commodore, Camputers Lynx, etc.) not supported by Maxduino, there are some programs that can, more or less successfully, embed <<#_audio_file_conversion,audio data>> in a `TSX` or `TZX` file, which then can be used with Miniduino. +While some tape file formats (Commodore, Camputers Lynx and so on) are not supported by Maxduino, there are some utilities that can, more or less successfully, embed <<#_audio_file_conversion,audio data>> in a `TSX` or `TZX` file, which then can be used with Miniduino. === MakeTSX -You can use the following command with NataliaPC's https://github.com/nataliapc/makeTSX/releases[MakeTSX] to create a `TSX` file with embedded audio: +You can use this command with NataliaPC's https://github.com/nataliapc/makeTSX/releases[MakeTSX] to create a `TSX` file with embedded audio: [source,shell] ---- @@ -101,7 +101,7 @@ You can use the following command with NataliaPC's https://github.com/nataliapc/ === RetroConverter -Jorge Fuertes https://github.com/jorgefuertes/retroconverter/releases[RetroConverter] can create a `TZX` file with a command like this: +Jorge Fuertes' https://github.com/jorgefuertes/retroconverter/releases[RetroConverter] can create a `TZX` file: [source,shell] ---- @@ -112,9 +112,9 @@ Jorge Fuertes https://github.com/jorgefuertes/retroconverter/releases[RetroConve == Maxduino firmware upgrade -Maxduino firmware is periodically updated and improved. You can track the changes and improvements either at the https://www.va-de-retro.com/foros/viewtopic.php?t=5541&start=9999[Va de Retro forums] or at the https://github.com/rcmolina/MaxDuino_BETA[GitHub project page]. To take advantage of this improvements, the Miniduino flash image must be flashed with the updated firmware version. +The Maxduino firmware is periodically updated and improved. You can track the changes and improvements either at the https://www.va-de-retro.com/foros/viewtopic.php?t=5541&start=9999[Va de Retro forums] or at the https://github.com/rcmolina/MaxDuino_BETA[GitHub project page]. To take advantage of this improvements, the Miniduino flash image must be flashed with the updated firmware version. -There are two Miniduino models, one based on STM32 microcontroller, and another one based on ATMega328P. +There are two Miniduino models; one based on the STM32 microcontroller and the ther on the ATMega328P. <<< @@ -122,24 +122,23 @@ There are two Miniduino models, one based on STM32 microcontroller, and another ==== Environment setup -Firmware flashing is done from a computer (Windows, Mac, Linux) with https://www.arduino.cc/en/software[Arduino IDE] installed. +Firmware flashing is done from a computer (Windows, macOS or Linux) with https://www.arduino.cc/en/software[Arduino IDE] installed. -You have to install SDFat (1.1.4) software library selecting the menu option Program -> include library -> manage libraries +You must install SDFat (1.1.4) software library selecting the menu option Program -> include library -> manage libraries. Minidiuno microcontroller support must also be added. This is done in two steps: -First, adding ARM Cortex M3 support from menu Tools -> board -> board manager, and installing "Arduino SAM boards (Cortex-M3)" +. Add ARM Cortex M3 support from menu Tools -> board -> board manager, and installing "Arduino SAM boards (Cortex-M3)". +. Add STM32 microcontroller support; download the file available at https://github.com/rogerclarkmelbourne/Arduino_STM32/archive/master.zip[this link]. -Then, you have to add STM32 microcontroller support, downloading the file available at https://github.com/rogerclarkmelbourne/Arduino_STM32/archive/master.zip[this link]. - -Extract the contents to the current user directory in +Extract the contents to the current user folder in: [source,shell] ---- ...Arduino/hardware/Arduino_STM32 ---- -If on Windows, install the USB device controller, running (with elevated privileges: +On Windows, install the USB device controller running (with elevated privileges: [source,shell] ---- @@ -153,11 +152,11 @@ On Linux, install with root privileges the necessary `udev` rules: ...tools/linux/install.sh ---- -On MacOS, if Miniduino does not appear as USB device in Arduino ID when plugged, it may be necessary to install https://github.com/libusb/libusb/wiki[libusb]. +On macOS, if Miniduino doesn't appear as a USB device in Arduino ID when connected it may be necessary to install https://github.com/libusb/libusb/wiki[libusb]. <<< -Finally, when on Mac or Linux, the file `maple_upload` inside `Arduino_STM32` has to be changed with a text editor. Those lines do not work: +Last, on Mac or Linux, the file `maple_upload` inside `Arduino_STM32` must be edited with a text editor. Those lines do not work: [source,shell] ---- @@ -168,7 +167,7 @@ else fi ---- -And they have to be changed into this: +They must be changed to: [source,shell] ---- @@ -179,16 +178,16 @@ dfuse_addr="" ==== Upgrade -Once you have the environment ready, download the software from the https://github.com/rcmolina/MaxDuino_BETA[official repository in GitHub] +After the environment is ready, download the software from the https://github.com/rcmolina/MaxDuino_BETA[official repository in GitHub]. [NOTE] ==== -Miniduino player with STM32 microcontroller is only supported from 1.65 and up +The Miniduino player with STM32 microcontroller is only supported from version 1.65 and up. ==== Load the project file with Arduino IDE (for example `MaxDuino_v1.69.ino`). -Check in the file `userSTM32Config.h` that all logo entries are commented except for Miniduino and, if not, change them. +Ensure that all logo entries in `userSTM32Config.h` file are commented out except for Miniduino. [source,c] ---- @@ -202,21 +201,21 @@ Check in the file `userSTM32Config.h` that all logo entries are commented except ... ---- -Connect the Miniduino device to the computer using the USB cable, and find the assigned port, normally with a name like "Maple Mini" (for example: COM5 Maple Mini) +Connect the Miniduino device to the computer using the USB cable, and find the assigned port, typically called something like "Maple Mini" (for example: COM5 Maple Mini) -Set the following options in the "Tools" menu: +Fom the "Tools" menu set these options: [source] ---- -Board: Generic STM32F103C Series -Variant: STM32F103C8 (20k RAM, 64k Flash) -Upload Method: STM32duino bootloader -CPU Speed: 72Mhz (Normal) -Optimize: Smallest (default) -Port: +Board: Generic STM32F103C Series. +Variant: STM32F103C8 (20k RAM, 64k Flash). +Upload Method: STM32duino bootloader. +CPU Speed: 72Mhz (Normal). +Optimize: Smallest (default). +Port: . ---- -Finally, click on the firmware load button and wait for a few seconds while the project is compiled and loaded into the device. +Last, click on the firmware load button and wait for a few seconds while the project is compiled and loaded into the device. If everything has been done correctly the Miniduino will restart and show on the screen the new firmware version. @@ -238,11 +237,11 @@ image:img/usbasp.jpg[scaledwidth=40%] Also, firmware flashing is done from a computer (Windows, Mac, Linux) with https://www.arduino.cc/en/software[Arduino IDE] installed. -You have to install SDFat (1.1.4) software library selecting the menu option Program -> include library -> manage libraries. +You must install SDFat (1.1.4) software library selecting the menu option Program -> include library -> manage libraries. ==== Upgrade -Once you have the environment ready, download the software from the https://github.com/rcmolina/MaxDuino_BETA[official repository in GitHub] +After you have the environment ready, download the software from the https://github.com/rcmolina/MaxDuino_BETA[official repository in GitHub] Load the project file with Arduino IDE (for example `MaxDuino_v1.69.ino`). @@ -278,6 +277,6 @@ Processor: ATmega328P (5V,16 Mhz) Programmer: "USBasp" ---- -Finally, keep pressed the computer keyboard Shift key while clicking on the firmware load button and wait for a few seconds until the project is compiled and loaded into the device. +Last, hold down the 'Shift' key on the computer while clicking the firmware load button. Wait for a few seconds until the project is compiled and loaded into the device. -If everything has been done correctly the Miniduino will restart and show on the screen the new firmware version. +If everything was done correctly the Miniduino will restart and show on the screen the new firmware version.