diff --git a/doc/src/English ZXTRES Manual.adoc b/doc/src/English ZXTRES Manual.adoc new file mode 100644 index 0000000..d18bbd9 --- /dev/null +++ b/doc/src/English ZXTRES Manual.adoc @@ -0,0 +1,1984 @@ += ZXTRES, ZXTRES+ and ZXTRES++ Manual +:author: kounch +: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 +:keywords: Manual, English, ZXTRES, ZXTRES+, ZXTRES++ +:icons: font +:source-highlighter: rouge +:toc: left +:toc-title: Index +:toclevels: 4 + +<<< + +== 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. + +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. + +ZXTRES official web page is . + +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. + +=== Aknowledgements + +A lot of the content of this manual is based on information previously shared: + +- 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] + +Without the previous work of all of these people (and more), this manual wouldn't exist. + +<<< + +=== Ports and Connectors + +[.text-center] +image:img/ZXTRESfront.jpg[scaledwidth=90%] + +[align="center",width="80%",cols="1,4"] +|=== +|1 +|Left Joystick Port +|2 +|microSD Card Slot +|3 +|Right Joystick Port +|4 +|Power Socket +|5 +|Power Switch +|6 +|PS/2 Keyboard Port +|7 +|PS/2 Mouse Port +|=== + +<<< + +[.text-center] +image:img/ZXTRESback.jpg[scaledwidth=90%] + +[align="center",width="80%",cols="1,4"] +|=== +|8 +|Audio In +|9 +|Audio Out +|10 +|USB Port (Only to use with middleboard installed) +|11 +|RGB/VGA Out +|12 +|JTAG access +|13 +|Expansion Port +|14 +|DisplayPort Out +|=== + +[.text-center] +image:img/ZXTRESbottom.jpg[scaledwidth=90%] + +[align="center",width="80%",cols="1,4"] +|=== +|15 +|Reset button +|16 +|Sound selection switch (DeltaSigma or I2S) +|=== + +<<< + +=== Initial Setup + +In order to be able to set up and use a ZXTRES you need, at least, the following: + +- 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). +- PS/2 keyboard + +[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. + +[.text-center] +image:img/powerConnector.png[scaledwidth=20%] +==== + +In order to take advantage of its full potential, you may also have: + +- 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). + +<<< + +==== microSD card formatting + +This table shows special requirements of the 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]#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 +==== + +[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`). +==== + +[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. +==== + +<<< + +===== 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 other, more complex, configurations, and depending on operating system version, you may use the command line tool `diskpart` or Windows Disk Managemente 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): + +[source] +---- +select disk 6 +clean +create part primary +active +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): + +[source] +---- +select disk 6 +clean +create part primary size=4000 +set id = 06 +active +format fs=FAT label=ZXTRES quick +create part primary size=4000 +format fs=FAT label=EXTRA quick +create part primary +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): + +[source] +---- +select disk 6 +clean +create part primary size=4000 +set id = 0b +active +format fs=FAT32 label=ZXTRES unit=4k quick +create part primary +format fs=FAT32 label=EXTRA quick +exit +---- + +<<< + +===== 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. + +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): + +[source,shell] +---- +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): + +[source,shell] +---- +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): + +[source,shell] +---- +diskutil unmountDisk /dev/disk6 +diskutil partitionDisk /dev/disk6 MBR %DOS_FAT_16% ZXTRES 4G %DOS_FAT_16% EXTRA 4G "MS-DOS FAT32" DATA R +sudo newfs_msdos -F 16 -v ZXTRES -c 128 /dev/rdisk6s1 +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. +==== + +<<< + +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): + +[source,shell] +---- +diskutil unmountDisk /dev/disk6 +diskutil partitionDisk /dev/disk6 MBR "MS-DOS FAT32" ZXTRES 4G "MS-DOS FAT32" EXTRA R +---- + +[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: + +[source,shell] +---- +diskutil unmountDisk /dev/disk6 +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`): + +[source,shell] +---- +mdutil -i off /Volumes/ZXTRES +cd /Volumes/ZXTRES +rm -rf .{,_.}{fseventsd,Spotlight-V*,Trashes} +mkdir .fseventsd +touch .fseventsd/no_log .metadata_never_index .Trashes +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. + +For example, to format a card, shown as `sdc`, with only one FAT16 partition (if the card size is less than 4GB): + +[source,shell] +---- +sudo fdisk --compatibility=dos /dev/sdc +---- + +[source] +---- +(...) +Command (m for help): n +Partition type + p primary (0 primary, 0 extended, 4 free) + e extended (container for logical partitions) +Select (default p): p +Partition number (1-4, default 1): 1 +First sector (62-31116288, default 62): +Last sector, +/-sectors or +/-size{K,M,G,T,P} (128-31116288, default 31116288): +Created a new partition 1 of type 'Linux' + +Command (m for help): t +Selected partition 1 +Hex code (type L to list all codes): 6 +Changed type of partition 'Linux' to 'FAT16'. + +Command (m for help): a +Partition number (1, default 1): 1 +The bootable flag on partition 1 is enabled now. + +Command (m for help): p +Disk /dev/sdc +Disklabel type: dos +Disk identifier + +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) + +[source,shell] +---- +sudo mkfs.fat -F 16 -n ZXTRES -s 128 /dev/sdc1 +---- + +<<< + +=== Keyboard + +==== 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). + +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. + +For the map to be preserved after a master reset, it has to 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]. + +==== Spanish + +[.text-center] +image:./img/keyboardEsp.png[scaledwidth=70%] + +==== English + +[.text-center] +image:./img/keyboardEng.png[scaledwidth=70%] + +==== Spectrum + +[.text-center] +image:./img/keyboardAV.png[scaledwidth=70%] + +<<< + +==== Special keys and buttons + +Special keys which 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>> + +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 + +<<< + +=== 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. + +For it to work, it is 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]. + +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. + +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. + +[.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: + + back16m + backzx2 + backzxd + corebios + dmaplayw + esprst + iwconfig + joyconf + keymap + loadpzx + loadtap + playmid + playrmov + romsback + romsupgr + upgr16m + upgrzx2 + upgrzxd + zxuc + zxunocfg + +<<#_zxtres_commands,It is explained later> what each of them does. + +<<< + +=== BIOS + +[.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. + +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. + +Other special keys which 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>> + +<<< + +==== Main + +[.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: + +- 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) + +More technical information can be found on https://www.zxuno.com/wiki/index.php/ZX_Spectrum[de 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 ). + +==== 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). + +<<< + +==== Boot + +[.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. + +<<< + +==== Advanced + +[.text-center] +image:img/bios5_zxtres.png[scaledwidth=70%] + +The Advanced configuration screen is used to edit the following settings: + +- 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 + +<<< + +==== Exit + +[.text-center] +image:img/bios6.png[scaledwidth=70%] + +Finally, from the last 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 + +== 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. + +These are some of its main characteristics: + +- 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. +- 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. +- 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 + +<<< + +=== 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. + +See the <<#_roms_3,updates section>> for more information on how to expand or modify the ROMs stored in flash memory. + +==== 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. + +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>>: + +[align="center",width="60%",%header,cols=2*] +|=== +|Flag +|Meaning +|`d` +|Enable DivMMC +|`n` +|Enable NMI DivMMC (esxdos Menu) +|`t` +|Use 128K timings +|=== + +<<< + +==== 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. + +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: + +- 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 + +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): + +[align="center",width="60%",%header,cols=2*] +|=== +|Flag +|Meaning +|`d` +|Enable DivMMC +|`h` +|Disable ROM high bit (1FFD bit 2) +|`l` +|Disable ROM low bit (7FFD bit 4) +|`x` +|Disable 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 + +<<< + +===== 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. + +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]. + +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: + +[source,shell] +---- +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. + +Thus, to make a `WAV` file with an ultrafast loading tape from the file `Valley.tap`, with loading speed 5, you could type: + +[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). + +[WARNING] +==== +Due to hardware limitations, `TZX` files made with `CgLeches` do not 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. + +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]. + +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 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. + +While it shares a common code base with many versions of Sinclair BASIC (the TS1000 ROM), it differs from them in significant ways: + +- 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. + +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. +- Automatic data typing. + +You can find much more information, including the user manual, etc. at https://github.com/cheveron/sebasic4/wiki[the official wiki page]. + +<<< + +==== Other ROMs + +Here are flag settings which work when <<#_zx123_tool,adding to the SPI flash>> some other known custom ROMs: + +[align="center",width="60%",%header,cols=2*] +|=== +|ROM Name +|Flags +|Gosh Wonderful ROM v1.33 +|dnhl17x +|Looking Glass 1.07 +|dnhl17x +|ZX82 by Daniel A. Nagy +|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. + ++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. + +[IMPORTANT] +==== +The following partition scheme can only be used with 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. +==== + +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). + +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 + +. Create a new extended partition, using the desired space for IDEDOS + +. Create a primary partition, 4GB in size, and format as FAT16 + +. Optionally, create another primary partition using the remaining space and format as FAT32 + +<<< + +==== MacOS + +You will have 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: + +[source] +---- +(...) +/dev/disk6 (external, physical): + #: TYPE NAME SIZE IDENTIFIER + 0: FDisk_partition_scheme *15.9 GB disk6 + 1: DOS_FAT_32 UNKNOWN 15.9 GB disk6s1 +---- + +Instruction steps: + +. Unmount the disk and edit the partition sceme (the second step requires admin privileges): + +[source,shell] +---- +diskutil unmountDisk /dev/disk6 +sudo fdisk -e /dev/rdisk6 +---- + +[source] +---- +fdisk: could not open MBR file /usr/standalone/i386/boot0: No such file or directory +Enter 'help' for information +fdisk: 1> erase +fdisk:*1> edit 1 +Partition id ('0' to disable) [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 +Do you wish to edit in CHS mode? [n] +Partition offset [0 - 31116288]: [2017280] +Partition size [1 - 29099135]: [29099135] 7812504 + +fdisk:*1> flag 2 +---- + +[source] +---- +fdisk:*1> edit 3 +Partition id ('0' to disable) [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] + +fdisk:*1> print + Starting Ending + #: id cyl hd sec - cyl hd sec [ start - size] +------------------------------------------------------------------------ + 1: 7F 1023 254 63 - 1023 254 63 [ 128 - 2017152] + 2: 06 1023 254 63 - 1023 254 63 [ 2017280 - 7812504] DOS > 32MB + 3: 0B 1023 254 63 - 1023 254 63 [ 9829784 - 21286504] Win95 FAT-32 + 4: 00 0 0 0 - 0 0 0 [ 0 - 0] unused + +fdisk:*1> write +fdisk: 1> quit +---- + +[start=2] +. Format the FAT partitions (admin privileges required) + +[source,shell] +---- +diskutil unmountDisk /dev/disk6 +sudo newfs_msdos -F 16 -v ZXTRES -c 128 /dev/rdisk6s2 +sudo newfs_msdos -F 32 -v EXTRA -c 128 /dev/rdisk6s3 +---- + +[start=3] +. Confirm that the new partition scheme has been applied: + +[source,shell] +---- +diskutil list +---- + +[source] +---- +(...) +/dev/disk6 (external, physical): + #: TYPE NAME SIZE IDENTIFIER + 0: FDisk_partition_scheme *15.9 GB disk6 + 1: 0x7F 1.0 GB disk6s1 + 2: DOS_FAT_16 ZXTRES 4.0 GB disk6s2 + 3: DOS_FAT_32 EXTRA 10.9 GB disk6s3 +---- + +<<< + +==== Linux + +You can use the command line. First, find out the device to erase: + +[source,shell] +---- +lsblk +---- + +For this example, it will be `sdc`: + +[source] +---- +NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT +(..) +sdc 179:0 0 15,8G 0 disk +└─sdc1 179:1 0 15,8G 0 part +---- + +Instructions: + +. Verify that the disk isn't mounted and edit the partition scheme (this step requires root privileges): + +[source,shell] +---- +sudo fdisk --compatibility=dos /dev/sdc +---- + +[source] +---- +Welcome to fdisk +Changes will remain in memory only, until you decide to write them. +Be careful before using the write command. + +Command (m for help): n +Partition type + p primary (0 primary, 0 extended, 4 free) + e extended (container for logical partitions) +Select (default p): p +Partition number (1-4, default 1): 1 +First sector (62-31116288, default 62): 128 +Last sector, +/-sectors or +/-size{K,M,G,T,P} (128-31116288, default 31116288): 2017152 + +Created a new partition 1 of type 'Linux' + +Command (m for help): t +Selected partition 1 +Hex code (type L to list all codes): 7f +Changed type of partition 'Linux' to 'unknown'. + +Command (m for help): n +Partition type + p primary (1 primary, 0 extended, 3 free) + e extended (container for logical partitions) +Select (default p): p +Partition number (2-4, default 2): +First sector (45-31116288, default 45): 2017280 . +Last sector, +/-sectors or +/-size{K,M,G,T,P} (2017153-31116288, default 31116288): 7812504 + +Created a new partition 2 of type 'Linux' + +Command (m for help): t +Partition number (1,2, default 2): 2 +Hex code (type L to list all codes): 6 + +Changed type of partition 'Linux' to 'FAT16'. + +Command (m for help): a +Partition number (1,2, default 2): 2 + +The bootable flag on partition 2 is enabled now. + +Command (m for help): n +Partition type + p primary (2 primary, 0 extended, 2 free) + e extended (container for logical partitions) +Select (default p): p +Partition number (3-4, default 3): 3 +First sector (45-31116288, default 45): 9829784 . +Last sector, +/-sectors or +/-size{K,M,G,T,P} (2017153-31116288, default 31116288): 31116288 + +Created a new partition 3 of type 'Linux' + +Command (m for help): t +Partition number (1-4, default 3): 3 +Hex code (type L to list all codes): b + +Changed type of partition 'Linux' to 'W95 FAT32'. + +Command (m for help): p +Disk /dev/sdc +Disklabel type: dos +Disk identifier + +Device Boot Start End Sectors Size Id Type +/dev/sdc1 128 2017152 2017025 984,9M 7f unknown +/dev/sdc2 * 2017280 7626751 7812504 2,7G b FAT16 +/dev/sdc3 9829784 7626751 21286504 21G b W95 FAT32 +---- + +[start=2] +. Format both FAT partitions (requires root privileges) + +[source,shell] +---- +sudo mkfs.fat -F 16 -n ZXTRES -s 128 /dev/sdc2 +sudo mkfs.fat -F 32 -n EXTRA -s 128 /dev/sdc3 +---- + +<<< + +[start=3] +. Confirm that the partition scheme has been changed: + +[source,shell] +---- +lsblk +---- + +[source] +---- +NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT +(...) +sda 179:0 0 15,8G 0 disk +├─sda1 179:1 0 1G 0 part +├─sda2 179:2 0 4G 0 part +├─sda3 179:3 0 10,8G 0 part +---- + +==== +3e + +Once the microSD card is ready to use, you can start 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: + +[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]. + +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: + +[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. + +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: + +[source,basic] +---- +NEW DATA "Software",16 +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]. + +<<< + +=== esxdos commands + +==== Basic Guide + +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. + +The main "DOT" commands are the following: + +- `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`) + +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 + +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. + +[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. +==== + +[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. +==== + +<<< + +==== ZXTRES Commands + +As explained in the installation part, there are a series of commands that are exclusive to 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 + +<<< + +=== Making RDM (RaDastan 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]. + +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 + +[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. + +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. + +[source,shell] +---- +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. + +[source,shell] +---- +(...)/magick mogrify -colors 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. + +[source,shell] +---- +(...)/makevideoradas img/output +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]. + +<<< + +== Upgrade + +=== 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] + +[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). +==== + +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. + +=== 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. + +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]. + +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. + +[WARNING] +==== +At this moment, `romsupgr`, only works correctly with RomPack files using 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. + +=== 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. + +==== microSD card + +===== Loading from the ZX Spectrum core + +From the main ZX Spectrum core it is possible to load other cores. + +====== Bob Fossil Browser + +In order to use the Bob Fossil browser to load cores, you need the following: + +- 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 + +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. + +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. + +<<< + +==== 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). + +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`). + +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. + +[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. +==== + +<<< + +=== esxdos + +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). + +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. + +Do a Hard-reset, or turn it off and on. + +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. + +=== 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`. + +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. + +Do a Hard-Reset or turn of and on again. + +[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. +==== + +<<< + +== Other cores + +=== ColecoVision + +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. + +Some features of this core are: + +- 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]. + +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 + +See the <<#_cores,corresponding section>> for instructions of how to install the ColecoVision core in ZXTRES. + +==== Keyboard + +===== Special keys and buttons + +While the core is running: + +- 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 + +<<< + +==== Basic Guide + +On startup, BIOS ROM is loaded from the 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. + +<<< + +=== Neo-Geo + +<<< + +=== Test DP + +Alternative Core, whose objective is to test the VGA, RGB and DisplayPort video outputs, applying different effects. + +Its main features are: + +- 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. + +==== Keyboard + +===== Special keys and buttons + +While the core is running: + +- `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. + +[NOTE] +==== +The above mentioned effects with keys 2 and 3 are not visible on the original 15 kHz output. +==== + +==== Basic guide + +When the core starts up, it sends the video signal via both VGA and DisplayPort. The refresh rate is about 64 Hz. + +The three LEDs on the board have the following meaning: + +- 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. + +<<< + +=== 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 ZXTRES version has been 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 + +==== microSD card format + +You can use a microSD card with the first partition in FAT16 or FAT32 format to store ROM and tape files. + +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). + +See the <<#_cores,corresponding section>> for instructions of 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. + +**ZX80** + +[.text-center] +image:img/keyboardZX80.jpg[scaledwidth=80%] + +**ZX81** + +[.text-center] +image:img/keyboardZX81.jpg[scaledwidth=80%] + +===== Special keys and buttons + +During the core execution: + +- `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 + +<<< + +==== Basic Guide + +Pressing `F5` or joystick button 2 shows or hides the configuration menu. Cursor keys and `Enter` to select and choose menu options. + +[.text-center] +image:img/zx81.jpg[scaledwidth=70%] + +The following options are available: + +- 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 + +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. +==== + +`.p` files with colorization and char are supported. + +For colorization 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 +==== + +<<< + +=== zxsp + +<<< + +== 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. + +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). + +==== Cassette Player + +The use is exactly the same as when using 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) + +==== 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. + +===== PlayTZX + +This program for Windows, MacOS or Linux, can play directly a `TZX` tape file through the audio output of the computer. + +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>>. + +. 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) + +[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. + +[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). +==== + +====== Compile source code (MacOS or 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]. + +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: + +[source,shell] +---- +aclocal && autoconf && autoheader && automake --add-missing +./configure +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. + +==== Mobile phone, tablet, MP3 player, etc. + +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. + +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. + +[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. + +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. +==== + +===== Audio file conversion + +These are some of the many programas that exist and 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 + +`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`. + +<<< + +==== Miniduino + +include::miniduino_en.adoc[leveloffset=+3] + +<<< + +== Troubleshooting + +=== Firmware images management + +There are several tools with you can use to make and/or edit the contents of `ZX1`, `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. + +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]. + +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]. + +Once extracted, you have to run from a shell the main script using Python 3. This may change depending on the operating system. + +For example, on Windows, it's usually: + +[source,shell] +---- +py -3 zx123_tool.py +---- + +With other operating systems it normally is like: + +[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: + +[source,shell] +---- +... zx123_tool.py -i FLASH.ZXD -w -o FLASHempty.ZXD +---- + +Where `FLASH.ZXD` is the path to the original file and `FLASHempty.ZXD` is the path to the new "clean" file. + +<<< + +*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 + +[source,shell] +---- +... zx123_tool.py -i FLASH.ZXD -l +---- + +To show the contents of the same file, including ZX Spectrun ROMs info: + +[source,shell] +---- +... zx123_tool.py -i FLASH.ZXD -l -r +---- + +*Change the BIOS of an image* + +To change the BIOS inside a file named `FLASH.ZXD`, using the BIOS file named `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). + +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: + +[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. + +<<< + +*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: + +[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. + +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: + +[align="center",width="70%",%header,cols=2*] +|=== +|`i` +|Keyboard issue 3 enabled (instead of issue 2) +|`c` +|Disable memory contention +|`d` +|Enable DivMMC +|`n` +|Enable NMI DivMMC (esxdos Menu) +|`p` +|Use Pentagon Timings +|`t` +|Use 128K timings +|`s` +|Disable DivMMC and ZXMMC ports +|`m` +|Enable Timex Horizontal MMU +|`h` +|Disable ROM high bit (1FFD bit 2) +|`l` +|Disable ROM low bit (7FFD bit 4) +|`1` +|Disable 1FFD port (+2A/3 paging) +|`7` +|Disable 7FFD port (128K paging) +|`2` +|Disable TurboSound (secondary AY chip) +|`a` +|Disable AY chip +|`r` +|Disable Radastanian mode +|`x` +|Disable Timex mode +|`u` +|Disable ULAPlus +|=== + +<<< + +*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: + +[source,shell] +---- +...zx123_tool.py -i FLASH.ZXD -a 'CORE,3,Spectrum Next,NEXT.ZXD' +---- + +If you want also to set the core as the default, use a command like: + +[source,shell] +---- +...zx123_tool.py -i FLASH.ZXD -a 'CORE,3,Spectrum Next,NEXT.ZXD' -c 3 +---- + +*Change esxdos ROM of an image* + +Just like the BIOS firmware, you can install a ROM esxdos file, with a command like this: + +[source,shell] +---- +...zx123_tool.py -i FLASH.ZXD -a esxdos,ESXMMC.BIN +---- + +*Mix 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: + +[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 +---- + +<<< + +=== 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. + +==== 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. + +[.text-center] +image:img/jtagzxtres.jpg[scaledwidth=80%] + +[WARNING] +==== +*DO NOT* connect the 3V line +==== + +<<< + +==== Recovery using a Raspberry Pi + +*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 + +*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: +** `recovery_a35.bit` for ZXTRES +** `recovery_a100.bit` for ZXTRES+ +** `recovery_a200.bit` for ZXTRES++ + +*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 Open OCD: + +[source,shell] +---- +sudo apt-get update +sudo apt-get install git autoconf libtool make pkg-config +sudo apt-get install libusb-1.0-0 libusb-1.0-0-dev telnet +sudo apt-get install libusb-dev libftdi-dev +git clone git://git.code.sf.net/p/openocd/code openocd-code +cd openocd-code/ +./bootstrap +./configure --enable-usb_blaster --enable-sysfsgpio --enable-bcm2835gpio +make +sudo make install +cd .. +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. + +Is using a GPIO connection, take note of the chosen pins, making sure 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: + +[%header,cols=3*] +|=== +|ZXTRES JTAG +|GPIO +|Raspberry Pi Pin +|`TMS` +|GPIO#6 +|`31` +|`TDI` +|GPIO#13 +|`33` +|`TDO` +|GPIO#19 +|`35` +|`TCK` +|GPIO#26 +|`37` +|`GND` +|GND +|`39` +|=== + +[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/` + +. If using GPIO, make a copy of Open OCD configuration file, to the same directory where `recovery.bit` is. + +[source,shell] +---- +cp /usr/local/share/openocd/scripts/interface/raspberrypi2-native.cfg /home/pi/zxtres/unbrick/ +---- + +<<< + +[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: + +[source] +---- +# Header pin numbers: 37 31 33 35 +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): + +[source] +---- +#bcm2835gpio_swd_nums 11 25 +---- + +[start=8] +. Add, to the end of the file, the line `adapter speed 250` (again, not necessary for USB-Blaster): + +[source] +---- +adapter speed 250 +---- + +[start=9] +. Turn 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`. + +For GPIO connection: + +[source,shell] +---- +cd /home/pi/zxtres/unbrick +sudo openocd -f /home/pi/zxtres/unbrick/raspberrypi2-native.cfg -f /home/pi/zxtres/unbrick/xilinx-xc7.cfg -c "init; pld load 0 recovery_axx.bit; shutdown" +---- + +For USB-Blaster connection: + +[source,shell] +---- +cd /home/pi/zxtres/unbrick +sudo openocd -f /usr/local/share/openocd/scripts/interface/altera-usb-blaster.cfg -f /home/pi/zxtres/unbrick/xilinx-xc7.cfg -c "init; pld load 0 recovery_axx.bit; shutdown" +---- + +[TIP] +==== +Remember to type the right 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 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. + +[.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. + +. If using a USB-Blaster connection, unplug 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. + +[.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. +==== + +[start=15] +. After some minutes, the process will end, and, after turning the ZXTRES off and on, it should start fine. + +[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. +==== + +<<< + +== References + +=== Scan Codes + +[.text-center] +image:img/scancodes.png[scaledwidth=80%] + +<<< + +=== Links + +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://www.zxuno.com/wiki/index.php/ZX_Spectrum[Core ZX Spectrum] + +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://github.com/spark2k06/zxunops2/blob/master/Alternative/Nuevo%20firmware%20de%20teclado%20ZX-GO%2B.pdf[Firmware de teclado para ZX Go+] + +https://github.com/zxdos/zxdos-plus/tree/master/zxunops2[zxunops2] + +https://docs.google.com/spreadsheets/d/17-ifpHcy932_AP7SAv9uBLxg-2ZptcdgTvQ8ILXQLM4/htmlview[Almost (In-) Complete List of esxDOS DOT-Commands] + +https://www.va-de-retro.com/foros/viewtopic.php?t=1718&start=10#p25076[Cargando Leches 2.0] + +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://svn.zxuno.com/svn/zxuno/cores/spectrum_v2_spartan6/test19_multi_uart/[Core de ZX-Uno 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.zxuno.com/forum/viewtopic.php?f=52&t=4074&p=28234&hilit=kyp#p28234[Nuevo 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] diff --git a/doc/src/Manual de ZXTRES.adoc b/doc/src/Manual de ZXTRES.adoc new file mode 100644 index 0000000..37211ee --- /dev/null +++ b/doc/src/Manual de ZXTRES.adoc @@ -0,0 +1,1993 @@ += Manual de ZXTRES, ZXTRES+ y ZXTRES++ +:author: kounch +: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: Manual en castellano de ZXTRES +:keywords: Manual, Castellano, ZXTRES, ZXTRES+. ZXTRES++ +:icons: font +:source-highlighter: rouge +:toc: left +:toc-title: Índice +:toclevels: 4 + +<<< + +== Introducción + +ZXTRES, ZXTRES+ y ZXTRES++ son la continuación de https://zxuno.speccy.org[ZX-Uno] un proyecto de hardware y software basado en una placa FPGA programada para trabajar como un ordenador ZX Spectrum, y creado por el equipo de ZX-Uno: Superfo, AVillena, McLeod, Quest y Hark0. + +Con el paso del tiempo, el proyecto ha ido creciendo, de forma que es posible usar distintas configuraciones de software (cores) y que trabajan como otros sistemas distintos del ZX Spectrum, pudiendo elegir arrancar el ZXTRES con la configuración que se desee de entre varias disponibles. + +La página oficial de la familia ZXTRES es . + +La mayoría de las funciones y características de ZXTRES, ZXTRES+ y ZXTRES++ son las mismas, así que, en este documento, se hablará, en general, de ZXTRES, indicando las diferencias con los demás donde sea necesario. + +=== Agradecimientos + +Gran parte del contenido de este documento se basa en información compartida anteriormente: + +- En https://www.forofpga.es/[foroFPGA] +- En el https://www.zxuno.com/forum/[foro de ZX-Uno] +- En los varios FAQ existentes, principalmente la versión original https://uto.speccy.org/zxunofaq.html[de @uto_dev], y la versión más moderna http://desubikado.sytes.net/zx-uno-faq-version-desubikado/[de @desUBIKado] +- En los canales oficiales de Telegram de https://t.me/zxuno[ZX-Uno], https://t.me/zxdosfpga[ZXDOS] y https://t.me/zxtresfpga[ZXTRES] +- En la https://github.com/zxtres/wiki/wiki[wiki oficial de ZXTRES] + +Sin el trabajo previo de todas estas personas (y más), ese manual no podría existir. + +<<< + +=== Puertos y Conectores + +[.text-center] +image:img/ZXTRESfront.jpg[scaledwidth=90%] + +[align="center",width="80%",cols="1,4"] +|=== +|1 +|Puerto de Joystick Izquierdo +|2 +|Ranura microSD +|3 +|Puerto de Joystick Derecho +|4 +|Enchufe de Alimentación +|5 +|Interruptor +|6 +|Puerto de Teclado PS/2 +|7 +|Puerto de Ratón PS/2 +|=== + +<<< + +[.text-center] +image:img/ZXTRESback.jpg[scaledwidth=90%] + +[align="center",width="80%",cols="1,4"] +|=== +|8 +|Entrada de Sonido +|9 +|Salida de Sonido +|10 +|Puerto USB (Sólo utilizable con middleboard instalada) +|11 +|Salida RGB/VGA +|12 +|Acceso a JTAG +|13 +|Puerto de expansión +|14 +|Salida DisplayPort +|=== + +[.text-center] +image:img/ZXTRESbottom.jpg[scaledwidth=90%] + +[align="center",width="80%",cols="1,4"] +|=== +|15 +|Botón de reset +|16 +|Interruptor selector de sonido (DeltaSigma o I2S) +|=== + +<<< + +=== Configuración Inicial + +Para poder poner en marcha un ZXTRES hace falta, al menos, lo siguiente: + +- Un cargador USB, una TV u otro dispositivo que ofrezca alimentación USB (5VDC y, al menos, 1A). El conector es un jack de barril de 5,5mm en el exterior y 2,1mm en el interior, con polaridad positiva (el exterior positivo y el interior negativo) +- Un cable y un monitor o TV con DisplayPort, VGA o RGB (la conexión RGB también se puede utilizar con un adaptador VGA a SCART y conectarse a TV compatibles) +- Un teclado PS/2 + +[TIP] +==== +Es importante que la fuente tenga un voltaje estable y suficiente intensidad, o es posible que ocurran comportamientos erráticos (fallo del teclado, DisplayPort, etc.). Algunos teclados y periféricos podrían requerir el uso de una fuente de alimentación similar pero que ofrezca 2 amperios o más. + +[.text-center] +image:img/powerConnector.png[scaledwidth=20%] +==== + +Para poder aprovechar todo su potencial, es útil tener también: + +- Una tarjeta microSD, de 32GB de capacidad o menos +- Unos altavoces de PC para conectar a la salida de audio, o un cable jack-stereo a dos conectores RCA rojo/blanco para conectar a la TV +- Al menos un joystick norma Atari, como por ejemplo, un gamepad DB9 de Megadrive +- Un ratón PS/2 +- Un cable con un jack estéreo de 3,5 mm en un extremo y los dos canales de sonido divididos en dos salidas mono en el otro, si se quiere usar algún dispositivo de reproducción y/o grabación de audio, como por ejemplo un Miniduino (<<#_miniduino,ver la sección correspondiente más adelante>>), un PC/Mac/Raspberry PI, etc. o un reproductor/grabador de https://es.wikipedia.org/wiki/Casete[cassette]. El canal derecho se utiliza como entrada (EAR) y el canal izquierdo se puede usar como salida de grabación (MIC). + +<<< + +==== Formato de la tarjeta microSD + +La siguiente tabla resume los requisitos particulares de los distintos cores que utilizan la tarjeta microSD. + +[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]#Tipo de Partición Primaria#|[.small]#Particiones Extra#|[.small]#Tipo de Acceso#|[.small]#Notas# +|[.small]#ZX Spectrum EXP#|[.small]#Sí#|[.small]#Sí#|[.small]#Sí#|[.small]#Cualquiera#|[.small]#Sí#|[.small]#Completo#|[.small]#Utiliza esxdos de SPI Flash# +|[.small]#ColecoVision#|[.small]#Sí#|[.small]#Sí#|[.small]#No#|[.small]#Cualquiera#|[.small]#No#|[.small]#Sólo ROMs (`.ROM`)#| +|[.small]#Neo-Geo#|[.small]#Sí#|[.small]#Sí#|[.small]#No#|[.small]#Cualquiera#|[.small]#No#|[.small]#Sólo imágenes (`.neo`)#|Necesita BIOS +|[.small]#ZX81#|[.small]#Sí#|[.small]#Sí#|[.small]#No#|[.small]#Cualquiera#|[.small]#No#|[.small]#Sólo imágenes (`.o` y `.p`)#| +|[.small]#zxsp#|[.small]#Sí#|[.small]#Sí#|[.small]#Si#|[.small]#Cualquiera#|[.small]#No#|[.small]#Imágenes de disco (`.vhd`)#|Necesita ROM +|=== + +[NOTE] +==== +El tamaño máximo de una partición FAT16 son 4GB +==== + +[CAUTION] +==== +A la hora de poner el nombre a una partición que se vaya a utilizar con esxdos, es importante no utilizar el mismo que el de cualquiera de los directorios dentro, o se producirá un error de acceso a ese directorio. (Ej: No llamar a la partición `BIN`, `SYS` o `TMP`). +==== + +[TIP] +==== +Para el core de Spectrum, tambén es posible tener <<#_formato_avanzado_de_la_tarjeta_microsd_3e,una primera partición en formato +3DOS y luego otra(s) en formato FAT16 o FAT32>>, para su uso con una ROM de +3e. +==== + +<<< + +===== Windows + +Para configuraciones sencillas, y tarjetas del tamaño adecuado (menos de 2GB para FAT16 o menos de 32GB para FAT32), se puede utilizar https://www.sdcard.org/downloads/formatter/[la herramienta de formato oficial de la SD Association]. + +Para otras configuraciones, y según la versión de sistema operativo de que se disponga, se podrá utilizar la herramienta de línea de comandos `diskpart` o bien la interfaz gráfica de administración de discos del sistema. + +Por ejemplo, en Windows, para formatear una tarjeta con una única partición FAT16 (si la tarjeta es de 4GB o menos de tamaño), que figura como disco 6 al ejecutar `list disk` desde `diskpart`: + +[source] +---- +select disk 6 +clean +create part primary +active +format FS=FAT label=ZXTRES +exit +---- + +Para crear dos primeras particiones FAT16 de 4GB (por ejemplo, para usar con el core de MSX) y usar el resto del espacio con otra más en formato FAT32 (para tarjetas de más de 8GB): + +[source] +---- +select disk 6 +clean +create part primary size=4000 +set id = 06 +active +format fs=FAT label=ZXTRES quick +create part primary size=4000 +format fs=FAT label=EXTRA quick +create part primary +format fs=FAT32 label=DATA quick +exit +---- + +Para crear una partición FAT32 de 4GB (por ejemplo, para usar con el core de Amstrad CPC 6128) y usar el resto del espacio con otra más en formato FAT32 (para tarjetas de más de 4GB de tamaño): + +[source] +---- +select disk 6 +clean +create part primary size=4000 +set id = 0b +active +format fs=FAT32 label=ZXTRES unit=4k quick +create part primary +format fs=FAT32 label=EXTRA quick +exit +---- + +<<< + +===== MacOS + +Para configuraciones sencillas, y tarjetas del tamaño adecuado (menos de 2GB para FAT16 o menos de 32GB para FAT32), se puede utilizar https://www.sdcard.org/downloads/formatter/[la herramienta de formato oficial de la SD Association] o la Utilidad de Discos incluida con el sistema operativo. + +Para configuraciones más complejas, será necesario utilizar la línea de comandos. + +Por ejemplo, en MacOS, para formatear una tarjeta con una única partición FAT16 (si la tarjeta es de 2GB o menos de tamaño), que figura como `disk6` en la lista de dispositivos: + +[source,shell] +---- +diskutil unmountDisk /dev/disk6 +diskutil partitionDisk /dev/disk6 MBR "MS-DOS FAT16" ZXTRES R +---- + +Para dividirla en dos particiones iguales (si la tarjeta es de 4GB o menos de tamaño): + +[source,shell] +---- +diskutil unmountDisk /dev/disk6 +diskutil partitionDisk /dev/disk6 MBR "MS-DOS FAT16" ZXTRES 50% "MS-DOS FAT16" EXTRA 50% +---- + +Para crear dos primeras particiones FAT16 de 4GB (por ejemplo, para usar con el core de MSX) y usar el resto del espacio con otra más en formato FAT32 (para tarjetas de más de 8GB): + +[source,shell] +---- +diskutil unmountDisk /dev/disk6 +diskutil partitionDisk /dev/disk6 MBR %DOS_FAT_16% ZXTRES 4G %DOS_FAT_16% EXTRA 4G "MS-DOS FAT32" DATA R +sudo newfs_msdos -F 16 -v ZXTRES -c 128 /dev/rdisk6s1 +sudo newfs_msdos -F 16 -v EXTRA -c 128 /dev/rdisk6s2 +---- + +[NOTE] +==== +El comando `diskutil` no permite crear particiones FAT16 de más de 2G de tamaño y formatearlas a la vez. Por eso, en el último caso, se crean primero las particiones y luego se formatean en FAT16. +==== + +<<< + +Para crear una partición FAT32 de 4GB (por ejemplo, para usar con el core de Amstrad CPC 6128) y usar el resto del espacio con otra más en formato FAT32 (para tarjetas de más de 4GB de tamaño): + +[source,shell] +---- +diskutil unmountDisk /dev/disk6 +diskutil partitionDisk /dev/disk6 MBR "MS-DOS FAT32" ZXTRES 4G "MS-DOS FAT32" EXTRA R +---- + +[NOTE] +==== +Para el core de Amstrad CPC, en este caso, al elegir exactamente un tamaño de partición de 4G, MacOS elegirá por defecto un tamaño de cluster de 4096. Para un tamaño inferior, podría ser necesario volver a formatear la primera partición con unos comandos similares a estos: + +[source,shell] +---- +diskutil unmountDisk /dev/disk6 +newfs_msdos -F 32 -v ZXTRES -b 4096 /dev/rdisk6s1 +---- +==== + +[TIP] +==== +Por defecto, MacOS indexa y guarda información extra en archivos de los discos externos. Esto se puede minimizar usando estos comandos (suponiendo que la partición de la microSD se llama `ZXTRES`): + +[source,shell] +---- +mdutil -i off /Volumes/ZXTRES +cd /Volumes/ZXTRES +rm -rf .{,_.}{fseventsd,Spotlight-V*,Trashes} +mkdir .fseventsd +touch .fseventsd/no_log .metadata_never_index .Trashes +cd - +---- +==== + +<<< + +===== Linux + +Existen multitud de herramientas en Linux que permiten formatear y particionar el contenido de una tarjeta microSD (como `fdisk`, `parted`, `cfdisk`, `sfdisk` o `GParted`). Sólo se ha de tener en cuenta que el esquema de particiones a utilizar siempre ha de ser MBR, y la primera partición (la que se utilizará para esxdos) ha de ser primaria. + +Por ejemplo, para formatear una tarjeta con una única partición FAT16 (si la tarjeta es de 4GB o menos de tamaño), que figura como `sdc` en la lista de dispositivos: + +[source,shell] +---- +sudo fdisk --compatibility=dos /dev/sdc +---- + +[source] +---- +(...) +Command (m for help): n +Partition type + p primary (0 primary, 0 extended, 4 free) + e extended (container for logical partitions) +Select (default p): p +Partition number (1-4, default 1): 1 +First sector (62-31116288, default 62): +Last sector, +/-sectors or +/-size{K,M,G,T,P} (128-31116288, default 31116288): +Created a new partition 1 of type 'Linux' + +Command (m for help): t +Selected partition 1 +Hex code (type L to list all codes): 6 +Changed type of partition 'Linux' to 'FAT16'. + +Command (m for help): a +Partition number (1, default 1): 1 +The bootable flag on partition 1 is enabled now. + +Command (m for help): p +Disk /dev/sdc +Disklabel type: dos +Disk identifier + +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) + +[source,shell] +---- +sudo mkfs.fat -F 16 -n ZXTRES -s 128 /dev/sdc1 +---- + +<<< + +=== Teclado + +==== Teclado PS/2 + +El mapa de un teclado conectado al puerto PS/2 (asignación de las teclas físicas del teclado con las pulsaciones que se presentan a los distintos cores) se cambia desde el menú `Advanced` de la BIOS. Existen tres mapas distintos a elegir: Español (por defecto), inglés, y Spectrum (avanzado). + +También se puede cambiar con la utilidad `keymap`. Dentro de `/bin` hay que crear un directorio llamado `keymaps` y ahí copiar los mapas de teclado se desee usar. Por ejemplo, para cambiar al mapa US hay que escribir `.keymap us` desde esxdos. + +Para que el mapa se conserve después de un master reset, hay que tener seleccionado `Default` en la configuración de BIOS. + +Para más información, consultar https://www.zxuno.com/forum/viewtopic.php?f=37&t=208[este mensaje en el foro de ZX-Uno]. + +*Español* + +[.text-center] +image:./img/keyboardEsp.png[scaledwidth=70%] + +*Inglés* + +[.text-center] +image:./img/keyboardEng.png[scaledwidth=70%] + +*Spectrum* + +[.text-center] +image:./img/keyboardAV.png[scaledwidth=70%] + +<<< + +==== Teclas especiales y botones + +Teclas especiales durante el arranque: + +- `F2` Entrar en la BIOS +- `Bloq. Mayús` o `Cursor abajo` o, si hay un joystick conectado, pulsar la dirección hacia abajo: Menú de selección de cores +- `Esc` o, si hay un joystick de dos o más botones conectado, pulsar el botón de disparo 2: Menú de selección de ROMS del core de ZX Spectrum +- `R`: Carga la rom del core de ZX Spectrum en modo "real" deshabilitando esxdos, nuevos modos gráficos, etc. +- `/` (del teclado numérico): Carga la ROM por defecto del core de ZX Spectrum en modo "root" +- Número del `1` al `9`: Cargar el core en la ubicación de la Flash correspondiente a dicho número. En las versiones más recientes de BIOS, la tecla `9` carga el core del slot temporal utilizado por el <<#_navegador_de_bob_fossil,plugin ZX3>>. + +Teclas especiales que se pueden utilizar durante la ejecución del core principal (ZX Spectrum): + +- `Esc`: BREAK +- `F2`: Edit +- `F5`: NMI +- `F7`: Reproducir o Pausa en la reproducción de archivos .PZX +- `F8`: Rebobinar el archivo .PZX hasta la marca anterior +- `F10`: Graph +- `F12`: Turbo Boost. Pone a la CPU a 28MHz +- `Ctrl+Alt+Backspace`: Hard reset. Backspace es la tecla de borrar hacia atrás, encima de `Enter` +- `Ctrl+Alt+Supr`: Soft reset +- `Bloq. Despl.`: cambia de modo vídeo RGB a VGA y viceversa (DisplayPort está siempre activo) +- `Inicio`: Alterna entre los distintos modos de gestión del desentrelazado en DisplayPort (Blend, Off, Auto y On). Esta opción sólo está disponible en los cores para ZXTRES+ y ZXTRES++ +- `Fin`: Activa los distintos modos de color monocromo + +<<< + +=== esxdos + +https://esxdos.org/index.html[esxdos] es un firmware para la interfaz the DivIDE/DivMMC, que el ZXTRES implementa, y que permite el acceso a dispositivos de almacenamiento como la tarjeta microSD. Incluye comandos similares a los de UNIX, aunque para usarlos hay que precederlos con un punto, por ejemplo `.ls`, `.cd`, `.mv`, etc. + +Para poder utilizarlo es necesario incluir los ficheros correspondientes en la primera partición de la tarjeta microSD. + +En el momento de escribir este documento, la versión incluida con ZXTRES es la 0.8.9, y se puede descargar desde la página oficial https://www.esxdos.org/files/esxdos086.zip[en este enlace]. + +Una vez descargado y descomprimido, se han de copiar, a la raíz de la tarjeta, los directorios `BIN`, `SYS` y `TMP` con todo su contenido. + +Si todo se ha hecho correctamente, al encender el core Spectrum de ZXTRES se verá cómo esxdos detecta la tarjeta y carga los componentes necesarios para funcionar. + +[.text-center] +image:./img/esxdos.png[scaledwidth=70%] + +<<< + +Es recomendable, además, añadir los comandos esxdos específicos para ZXTRES. Estos se pueden obtener en la página con el código fuente del proyecto (https://github.com/zxdos/zxuno/tree/master/SD[aquí], https://github.com/zxdos/zxuno/tree/master/[aquí] y https://guest:zxuno@svn.zxuno.com/svn/zxuno/software/upgrade[aquí]), y son los siguientes: + + back16m + backzx2 + backzxd + corebios + dmaplayw + esprst + iwconfig + joyconf + keymap + loadpzx + loadtap + playmid + playrmov + romsback + romsupgr + upgr16m + upgrzx2 + upgrzxd + zxuc + zxunocfg + +<<#_comandos_para_zxtres,Más adelante>> se explica lo que hace cada uno de ellos. + +<<< + +=== BIOS + +[.text-center] +image:./img/boot_zxtres.png[scaledwidth=80%] + +Si se pulsa la tecla `F2` durante el arranque, se tendrá acceso a la configuración de BIOS. El firmware de BIOS es el primer programa que se ejecuta cuando se enciende el ZXTRES. El propósito fundamental del software de BIOS es iniciar y probar el hardware y cargar uno de los cores instalados. + +Usando las teclas de cursor izquierda y derecha, se puede navegar por las pantallas de configuración de la BIOS. Con las teclas arriba y abajo se pueden elegir los distintos elementos de cada pantalla y, con la tecla `Enter`, es posible activar y elegir las opciones de cada una de estas. La tecla `Esc` sirve para cerrar las ventanas de opciones abiertas sin aplicar ninguna acción. + +Otras teclas que se pueden pulsar durante el arranque de la BIOS son: + +- `Bloq. Mayús` o `Cursor abajo`, o `Caps Shif+6` o `Caps Shift+2` o, si hay un joystick conectado, pulsar la dirección hacia abajo: Menú de selección de cores +- `Esc` o `Caps Shift+Espacio`, o si hay un joystick de dos o más botones conectado, pulsar el botón de disparo 2: Menú de selección de ROMS del core de ZX Spectrum +- `R`: Carga la rom del core de ZX Spectrum en modo "real" deshabilitando esxdos, nuevos modos gráficos, etc. (combinado con `Esc` a continuación permite elegir otra ROM distinta) +- `/` (del teclado numérico) o `Symbol Shift+V`: Carga la ROM por defecto del core de ZX Spectrum en modo "root" (combinado con `Esc` a continuación permite elegir otra ROM distinta) +- Número del `1` al `9`: Cargar el core en la ubicación de la Flash correspondiente a dicho número. En las versiones más recientes de BIOS, la tecla `9` carga el core del slot temporal utilizado por el <<#_navegador_de_bob_fossil,plugin ZX3>>. + +<<< + +==== Main + +[.text-center] +image:img/bios.png[scaledwidth=70%] + +En la primera pantalla de configuración, además de poder ejecutar distintas pruebas, se puede definir el comportamiento por defecto para lo siguiente: + +- Espera en el arranque (Boot Timer): Indica el tiempo que está la pantalla de arranque disponible (o la oculta por completo) +- Comprobar CRC de las ROMs (Check CRC): Para comprobar la integridad de las ROMs al cargarlas (más seguro) u omitirla (más rápido) +- Tipo de teclado (Keyboard) +- Timing: Para definir el comportamiento de la ULA (Modo 48K, Modo 128K, Modo Pentagon) +- Contención de memoria (Contended) +- DivMMC +- Soporte NMI para DivMMC +- Soporte para nuevos modos gráficos (ULAPlus, Timex, Radastan) + +Se puede consultar información más tecnica en https://www.zxuno.com/wiki/index.php/ZX_Spectrum[la Wiki de ZX-Uno]. + +<<< + +==== ROMs + +[.text-center] +image:img/bios2.png[scaledwidth=70%] + +La segunda pantalla muestra las ROMs de ZX Spectrum instaladas y permite reordenar (Move Up, Move Down), renombrar (Rename) o borrar (Delete) cada una de ellas, así como elegir la que se cargará por defecto en el arranque (Set Active). + +==== Upgrade + +[.text-center] +image:img/bios3_zxtres.png[scaledwidth=70%] + +La pantalla _Upgrade_ se utiliza para realizar las distintas actualizaciones del contenido de la memoria Flash: esxdos, BIOS, Cores, etc. (véase <<#_actualizaciones,el apartado correspondiente a actualizaciones>> para más información). + +==== Boot + +[.text-center] +image:img/bios4_zxtres.png[scaledwidth=70%] + +En la pantalla _Boot_ se puede elegir qué core de los instalados se desea que cargue por defecto en el arranque. + +<<< + +==== Advanced + +[.text-center] +image:img/bios5_zxtres.png[scaledwidth=70%] + +La pantalla de configuración avanzada sirve para modificar los siguientes ajustes: + +- Distribución del teclado (Keyb Layout): Ver <<#_teclado,el apartado correspondiente >> para más información) +- Comportamiento de un joystick conectado al puerto de joystick derecho, y también del joystick emulado con el teclado numérico (Joy Keypad): Kempston, Sinclair Joystick 1, Sinclair Joystick 2, Protek, Fuller o simular las teclas `Q`, `A`, `O`, `P`, `Espacio` y `M` +- Comportamiento de un joystick conectado al puerto de joystick izquierdo (Joy DB9): Kempston, Sinclair Joystick 1, Sinclair Joystick 2, Protek, Fuller o simular las teclas `Q`, `A`, `O`, `P`, `Espacio` y `M` +- Salida de vídeo (Video): PAL, NTSC o VGA (DisplayPort está siempre activo) +- Simulación de línea de exploración (Scanlines): Activas (Enabled) o inactivas (Disabled) +- Frecuencia horizontal de VGA (Frequency): 50, 51, etc. +- Velocidad de la CPU: Normal (1x) o acelerada (2X, 3X, etc.) +- Csync: Spectrum o PAL + +<<< + +==== Exit + +[.text-center] +image:img/bios6.png[scaledwidth=70%] + +Finalmente, desde la última pantalla se puede: + +- Salir de la configuración de BIOS guardando los cambios (Save Changes & Exit) +- Descartar los cambios y salir (Discard Changes & Exit) +- Guardar los cambios sin salir (Save Changes) +- Descartar los cambios (Discard Changes) + +== ZX Spectrum + +El core principal es el que implementa un ordenador ZX Spectrum. Este core es especial, y no se puede sustibuir por otro que no sea de ZX Spectrum, ya que el ZXTRES lo utiliza para su funcionamiento. + +Estas son algunas de sus principales características: + +- Implementación ZX Spectrum 48K, 128K, Pentagon y Chloe 280SE +- ULA con modos ULAplus, Timex y modo Radastan (incluyendo scroll por hardware y grupo de paleta seleccionable) +- Posibilidad de desactivar la contención de memoria (para compatibilidad con Pentagon 128) +- Posibilidad de elegir el comportamiento del teclado (issue 2 o issue 3) +- Posibilidad de elegir el timing de la ULA (48K, 128K o Pentagon) +- Control del encuadre de pantalla configurable para tipo de timing, y posibilidad de elegir entre sincronismos originales de Spectrum o sincronismos estándar PAL progresivo. +- Soporte de la MMU horizontal del Timex con bancos HOME, DOC y EXT en RAM. +- Interrupción ráster programable en número de línea, para cualquier linea de TV. +- Posibilidad de activar/desactivar los registros de manejo de bancos de memoria, para mejor compatibilidad con cada modelo implementado +- Posibilidad de activar/desactivar los dispositivos incorporados al core para mejorar la compatibilidad con ciertos programas +- Soporte ZXMMC y DIVMMC para para +3e, esxdos y firmwares compatibles +- Soporte Turbo Sound +- Soporte de SpecDrum +- Cada canal A,B,C de los dos chips AY-3-8912, beeper y SpecDrum pueden dirigirse a las salidas izquierda, derecha, ambas o ninguna, permitiendo la implementación de configuraciones tales como ACB, ABC, etc. +- Soporte de joystick real y joystick en teclado con protocolo Kempston, Sinclair 1 y 2, Cursor, Fuller y QAOPSpcM. +- Soporte de modo turbo a 7MHz, 14MHz, 28MHz +- Soporte de teclado con protocolo PS/2 y mapeado configurable desde el propio Spectrum. +- Soporte de ratón PS/2 emulando el protocolo Kempston Mouse. +- Posibilidad de salida de vídeo en modo RGB 15kHz, VGA y DisplayPort +- Frecuencia de refresco vertical seleccionable para la compatibilidad con monitores VGA +- Soporte de arranque multicore: desde el Spectrum se puede seleccionar una dirección de la SPI Flash y la FPGA cargará un core desde ahí +- Modos de color incluyendo monocromo o fósforo verde/naranja +- Salida de audio I^2^S y DeltaSigma +- Soporte Wi-Fi (UART) +- Soporte MIDI (General MIDI) vía middleboard +- Carga de ficheros `PZX` desde la SD simulando carga de cinta +- Varios modos de gestión del desentrelazado en la salida DisplayPort incluyendo una opción para mezclar (blend) los colres. Esto sólo está disponible en los cores para ZXTRES+ y ZXTRES++ + +<<< + +=== ROMs + +El core de ZX Spectrum tiene la capacidad de inicializar utilizando diferentes versiones de ROM (48K, 128K, Plus 2, etc.). Estas se almacenan en la memoria flash del ZXTRES, y se puede elegir cuál cargar, pulsando la tecla `Esc` durante el arranque. También es posible definir desde la configuración de BIOS, cuál es la ROM que se desea que se cargue por defecto. + +Véase el <<#_roms_3,apartado de actualizaciones>> para más información sobre cómo ampliar o modificar las ROMs almacenadas en la memoria flash. + +==== DerbyPro + +https://www.facebook.com/groups/DerbyPro[DerbyPro o Derby{pp}] es una ROM mejorada para el ZX Spectrum, basada en la versión 1.4 de la ROM de desarrollo Derby. El Spectrum 128 (nombre en código "Derby") fue una máquina española, encargada por Investronica y lanzada en 1985. Incluía un teclado aparte que añadía varias teclas de edición extra. En 1986 se lanzó la versión para Reino Unido con una versión simplificada de 128 BASIC y sin teclado extra. Derby++ se basa en la ROM española para incluir lo mejor de las dos versiones, sin sus inconvenientes, y con soporte para nuevo hardware. + +Se puede descargar la ROM, un manual de usuario y otos ficheros del https://www.facebook.com/groups/DerbyPro[grupo púbilco oficial de Facebook]. + +Esta ROM de 64K tiene soporte para nuevo hardware, incluyendo el uso de comandos de esxdos desde 128 BASIC, así que se pueden usar estas opciones al <<#_zx123_tool,añadirla a la SPI flash>>: + +[%header,cols=2*] +|=== +|Ajuste +|Significado +|`d` +|Habilitar DivMMC +|`n` +|Habilitar NMI DivMMC (menú de esxdos) +|`t` +|Usar timings de 128K +|=== + +<<< + +==== CargandoLeches + +https://github.com/antoniovillena/CargandoLeches[CargandoLeches] es un conjunto de ROMs de ZX Spectrum originalmente pensadas para cargar juegos a una velocidad de 15 a 20 veces superior a lo normal. En lugar de una cinta se requiere una fuente de audio digital como un ordenador, un dispositivo móvil, un reproductor MP3, etc. También tiene una rutina que detecta el método de carga y si no se trata de una carga ultrarápida, ejecuta el código de la ROM original. En cargas que no sean CargandoLeches no se nota por tanto la diferencia entre usar esta ROM y la ROM original. + +Desde la versión 2.0, el proyecto pasó de ser una única ROM a varias, cada una con distintas opciones. Así, es posible elegir diferentes combinaciones que pueden incluir: + +- Carga ultrarrápida +- Reset & Play (es decir, que al hacer un reset automáticamente se ponga en modo carga de cinta) +- Introducción de POKEs +- Desactivar o activar la expansión de tokens (palabras clave) de Sinclair BASIC + +El conjunto completo de ROMs está disponible para descargar desde el repositorio en GitHub https://github.com/antoniovillena/CargandoLeches/tree/master/binaries[aquí]. + +Dependiendo de la ROM elegida, los ajustes a indicar cuando se <<#_zx123_tool,añada a la SPI flash>> pueden variar. Por ejemplo, para la ROM `48le_ea_re_po` (que tiene habilitadas todas las opciones), se pueden usar estos ajustes (no hay que habilitar NMI DivMMC porque el editor de POKEs ya lo utiliza): + +[%header,cols=2*] +|=== +|Ajuste +|Significado +|`d` +|Habilitar DivMMC +|`h` +|Deshabilitar bit alto de ROM (bitd 2 de 1FFD) +|`l` +|Deshabilitar bit bajo de ROM (bit 4 de 7FFD) +|`x` +|Deshabilitar modo Timex +|=== + +===== POKEs + +En el caso de usar una ROM con la opción de introducir POKEs, se hace de la siguiente manera: + +. Una vez el juego ha cargado, pulsando NMI (`F5`), aparecerá un campo en la parte superior izquierda de la pantlla +. Escribir la dirección del POKE a introducir y pulsar `Enter` +. Escribir el valor del POKE y pulsar `Enter` +. Repetir los pasos 2. y 3. todas las veces que se desee. Para terminar y volver al juego, pulsar `Enter` dos veces seguidas + +<<< + +===== Preparación de cintas de carga ultrarrápida + +Las ROMs con la opción de carga ultrarrápida necesitan archivos de cinta especiales que se generan desde ficheros `TAP` de carga normal, de juegos que no tengan protección de carga o modo turbo. + +Para crear una cinta de carga ultrarrápida se necesitan las utilidates de línea de comandos `leches` y `CgLeches`. Estas se pueden conseguir, para Windows, https://github.com/antoniovillena/CargandoLeches/tree/master/binaries[en el repositorio oficial]. Para MacOS es posible descargar una versión no oficial https://github.com/kounch/CargandoLeches/tree/master/binaries/MacOS[en este otro repositorio]. + +En otro caso, es posible compilar desde https://github.com/antoniovillena/CargandoLeches[el código fuente disponible en el repositorio oficial]. Por ejemplo, para compilar en Linux usando `gcc` basta con usar estos comandos: + +[source,shell] +---- +gcc leches.c -o leches +gcc CgLeches.c -o CgLeches +---- + +Para generar una cinta de carga ultarrápida se ha de invocar desde una consola al comando `CgLeches` indicando, al menos, el fichero `TAP` de origen, y el fichero (`WAV` o `TZX`) de destino. Existen otros parámetros como el nivel de velocidad de la carga, entre 0 y 7 (donde 0 es la más rápida pero posiblemente más incompatible), si se desea un fichero mono, estéreo, etc. (en el caso de `WAV`) y más. + +Así, para producir un fichero `WAV` de audio con una cinta de carga ultrarrápida desde el fichero de cinta `Valley.tap` con velocidad de carga 5, se haría así: + +[source,shell] +---- +(...) CgLeches Valley.tap Valley.wav 5 +---- + +Ahora el fichero `Valley.wav` se puede reproducir desde un ordenador u otro dispositivo y cargarlo usando la ROM (véase la sección dedicada a la <<#_carga_desde_cinta,carga desde cinta>> para más detalles). + +[WARNING] +==== +Debido a limitaciones en el hardware, los ficheros `TZX` generados con `CgLeches` no funcionan correctamente con <<#_miniduino,Miniduino>>, aunque sí que suelen funcionar con <<#_playtzx,`PlayTZX`>>. +==== + +<<< + +==== SE Basic IV + +https://github.com/cheveron/sebasic4[SE Basic IV] es un intérprete de Microsoft BASIC, gratuito y de código abierto. SE Basic IV se ha diseñado para funcionar en un https://www.patreon.com/chloe280se[Chloe 280SE] pero también lo hace en ZX-Uno y similares. + +SE Basic se pensó en sus orígenes como un nuevo firmware para el https://sinclair.wiki.zxnet.co.uk/wiki/ZX_Spectrum_SE[ZX Spectrum SE]. Las primeras versiones eran modificaciones aplicadas sobre la ROM original del ZX Spectrurm, pero posteriormente se ha reescrito basándose en la https://groups.google.com/g/comp.sys.sinclair/c/F90HbKTDkRk[ROM mejorada y de código abierto TS1000 / ZX81]. + +La versión 3, también conocida como https://zxdesign.itch.io/opense[OpenSE BASIC], todavía se mantiene como un firmware de código abierto para el Spectrum. Se incluye, por ejemplo, en el https://tracker.debian.org/pkg/opense-basic[repositorio principal de Debian] para su uso en emuladores. + +La versión IV es una nueva rama de la versión anterior, creada principalmente porque no quedaba espacio para añadir nuevas características a la ROM de 16K. La primera versión (4.0 Anya) añadió una segunda ROM de 16K con soporte para el modo hi-res de Timex. La sintaxis era aún bastante compatible con Sinclair BASIC. La versión 4.2 fue reconstruida específicamente para el Chloe 280SE, eliminó el soporte para dispositivos antiguos como las cintas, añadió soporte integrado y compatibilidad total con el kernel de esxdos, y migró a la sintaxis de Microsoft BASIC. + +Aunque guarda una base común de código con muchas versiones de Sinclair BASIC (la ROM TS1000), hay varias diferencias significativas: + +- Soporte para páginas de códigos(8-bit ASCII). +- Traducción de los mensajes de error. +- 38 tokens nuevos. +- Presentación en una terminal estándar (80 x 24). +- Introducción de caracteres de terminal (CTRL, META). +- Buffer de teclado. +- Soporte para teclados completos. +- Soporte completo de las características adicionales del core de Spectrum de ZX-Uno + +Las principales diferencias con Microsoft BASIC son: + +- Abreviación de tokens. +- Comprobación de sintaxis en cada entrada. +- Normalmente los paréntesis son opcionales. +- Introducción de número con el estilo Motorola: + % – binario + @ – octal + $ – hexadecimal +- Evaluación de expresiones siempre activa. +- Operadores lógicos y bit a bit separados. +- Tipado automático de datos. + +Se puede encontrar mucha más información, incluyendo el manual de usuario, etc. en https://github.com/cheveron/sebasic4/wiki[la wiki oficial]. + +<<< + +==== Otras ROMs + +Estos son algunos ajustes válidos para <<#_zx123_tool,añadir a la SPI flash>> algunas otras ROM personalizadas: + +[%header,cols=2*] +|=== +|Nombre de la ROM +|Ajustes +|Gosh Wonderful ROM v1.33 +|dnhl17x +|Looking Glass 1.07 +|dnhl17x +|ZX82 by Daniel A. Nagy +|dnhl17 +|ZX85 by Daniel A. Nagy +|dntmh1 +|Arcade Game Designer 0.1 +|thl17x +|=== + +<<< + +=== Formato avanzado de la tarjeta microSD (+3e) + +Una de las ROM que se pueden cargar con el core de ZX Spectrum es la de ZX Spectrum +3e, que es una versión mejorada del Sinclair ZX Spectrum +3, y que soporta el uso de discos duros o tarjetas de memoria. + +El +3e usa su propio esquema de particionado (llamado IDEDOS) para dividir el disco duro en diferentes particiones donde se pueden almacenar datos. Se necesita una version 1.28 o superior de la ROM para poder compartir particiones IDEDOS con particiones MBR. En otro caso, se ha dedicar la tarjeta completa al particionado IDEDOS. + +[IMPORTANT] +==== +El esquema de particionado que se presentará a continuación sólo se podrá utilizar con el core de Spectrum. Otros cores que necesiten acceso a la tarjeta SD posiblemente fallen o no se inicien correctamente, si se encuentra insertada una SD con este formato. +==== + +[TIP] +==== +En IDEDOS, cada partición puede tener un tamaño entre 1 y 16 Megabytes (16 millones de bytes), y cada disco puede tener entre 1 y 65535 particiones. Por tanto, lo máximo que se puede ocupar de una tarjeta será alrededor de 1 TB de espacio. +==== + +A continuación se explica una forma de dividir una tarjeta en dos o tres partes, con la primera partición IDEDOS (1GB de tamaño), la segunda FAT16 (4GB) y la tercera FAT32 (resto del espacio de la tarjeta). + +En la segunda particion se puede instalar, tal y como se explicó anteriormente <<#_esxdos,exsdos>> y otros programas. + +==== Windows + +Se puede utilizar el administrador de discos de Windows. Los pasos a seguir serían: + +. Eliminar todas las particiones de la tarjeta + +. Crear una partición extendida, del tamaño que se quiera utilizar para IDEDOS + +. Crear una partición primaria de 4GB y formatear como FAT16 + +. Opcionalmente, crear otra partición primaria ocupando el resto del espacio y formatear como FAT32 + +<<< + +==== MacOS + +Será necesario utilizar la línea de comandos. Lo primero es determinar el disco a formatear: + +[source,shell] +---- +diskutil list +---- + +En este ejemplo sería el disco 6: + +[source] +---- +(...) +/dev/disk6 (external, physical): + #: TYPE NAME SIZE IDENTIFIER + 0: FDisk_partition_scheme *15.9 GB disk6 + 1: DOS_FAT_32 UNKNOWN 15.9 GB disk6s1 +---- + +Pasos a seguir: + +. Expulsar el disco y editar el esquema de particiones (el segundo paso requiere permisos de administrador): + +[source,shell] +---- +diskutil unmountDisk /dev/disk6 +sudo fdisk -e /dev/rdisk6 +---- + +[source] +---- +fdisk: could not open MBR file /usr/standalone/i386/boot0: No such file or directory +Enter 'help' for information +fdisk: 1> erase +fdisk:*1> edit 1 +Partition id ('0' to disable) [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 +Do you wish to edit in CHS mode? [n] +Partition offset [0 - 31116288]: [2017280] +Partition size [1 - 29099135]: [29099135] 7812504 + +fdisk:*1> flag 2 +---- + +[source] +---- +fdisk:*1> edit 3 +Partition id ('0' to disable) [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] + +fdisk:*1> print + Starting Ending + #: id cyl hd sec - cyl hd sec [ start - size] +------------------------------------------------------------------------ + 1: 7F 1023 254 63 - 1023 254 63 [ 128 - 2017152] + 2: 06 1023 254 63 - 1023 254 63 [ 2017280 - 7812504] DOS > 32MB + 3: 0B 1023 254 63 - 1023 254 63 [ 9829784 - 21286504] Win95 FAT-32 + 4: 00 0 0 0 - 0 0 0 [ 0 - 0] unused + +fdisk:*1> write +fdisk: 1> quit +---- + +[start=2] +. Formatear las particiones FAT (requiere permisos de administrador) + +[source,shell] +---- +diskutil unmountDisk /dev/disk6 +sudo newfs_msdos -F 16 -v ZXTRES -c 128 /dev/rdisk6s2 +sudo newfs_msdos -F 32 -v EXTRA -b 4096 -c 128 /dev/rdisk6s3 +---- + +[start=3] +. Comprobar cómo el esquema de particiones ha cambiado y ya es el que se deseaba: + +[source,shell] +---- +diskutil list +---- + +[source] +---- +(...) +/dev/disk6 (external, physical): + #: TYPE NAME SIZE IDENTIFIER + 0: FDisk_partition_scheme *15.9 GB disk6 + 1: 0x7F 1.0 GB disk6s1 + 2: DOS_FAT_16 ZXTRES 4.0 GB disk6s2 + 3: DOS_FAT_32 EXTRA 10.9 GB disk6s3 +---- + +<<< + +==== Linux + +Será necesario utilizar la línea de comandos. Lo primero es determinar el disco a formatear: + +[source,shell] +---- +lsblk +---- + +En este ejemplo sería `sdc`: + +[source] +---- +NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT +(..) +sdc 179:0 0 15,8G 0 disk +└─sdc1 179:1 0 15,8G 0 part +---- + +Pasos a seguir: + +. Comprobar que no está montado y editar el esquema de particiones (este paso requiere permisos de root): + +[source,shell] +---- +sudo fdisk --compatibility=dos /dev/sdc +---- + +[source] +---- +Welcome to fdisk +Changes will remain in memory only, until you decide to write them. +Be careful before using the write command. + +Command (m for help): n +Partition type + p primary (0 primary, 0 extended, 4 free) + e extended (container for logical partitions) +Select (default p): p +Partition number (1-4, default 1): 1 +First sector (62-31116288, default 62): 128 +Last sector, +/-sectors or +/-size{K,M,G,T,P} (128-31116288, default 31116288): 2017152 + +Created a new partition 1 of type 'Linux' + +Command (m for help): t +Selected partition 1 +Hex code (type L to list all codes): 7f +Changed type of partition 'Linux' to 'unknown'. + +Command (m for help): n +Partition type + p primary (1 primary, 0 extended, 3 free) + e extended (container for logical partitions) +Select (default p): p +Partition number (2-4, default 2): +First sector (45-31116288, default 45): 2017280 . +Last sector, +/-sectors or +/-size{K,M,G,T,P} (2017153-31116288, default 31116288): 7812504 + +Created a new partition 2 of type 'Linux' + +Command (m for help): t +Partition number (1,2, default 2): 2 +Hex code (type L to list all codes): 6 + +Changed type of partition 'Linux' to 'FAT16'. + +Command (m for help): a +Partition number (1,2, default 2): 2 + +The bootable flag on partition 2 is enabled now. + +Command (m for help): n +Partition type + p primary (2 primary, 0 extended, 2 free) + e extended (container for logical partitions) +Select (default p): p +Partition number (3-4, default 3): 3 +First sector (45-31116288, default 45): 9829784 . +Last sector, +/-sectors or +/-size{K,M,G,T,P} (2017153-31116288, default 31116288): 31116288 + +Created a new partition 3 of type 'Linux' + +Command (m for help): t +Partition number (1-4, default 3): 3 +Hex code (type L to list all codes): b + +Changed type of partition 'Linux' to 'W95 FAT32'. + +Command (m for help): p +Disk /dev/sdc +Disklabel type: dos +Disk identifier + +Device Boot Start End Sectors Size Id Type +/dev/sdc1 128 2017152 2017025 984,9M 7f unknown +/dev/sdc2 * 2017280 7626751 7812504 2,7G b FAT16 +/dev/sdc3 9829784 7626751 21286504 21G b W95 FAT32 +---- + +[start=2] +. Formatear las particiones FAT (requiere permisos de root) + +[source,shell] +---- +sudo mkfs.fat -F 16 -n ZXTRES -s 128 /dev/sdc2 +sudo mkfs.fat -F 32 -n EXTRA -s 128 /dev/sdc3 +---- + +[start=3] +. Verificar que el esquema de particiones ha cambiado y ya es el que se quería: + +[source,shell] +---- +lsblk +---- + +[source] +---- +NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT +(...) +sda 179:0 0 15,8G 0 disk +├─sda1 179:1 0 1G 0 part +├─sda2 179:2 0 4G 0 part +├─sda3 179:3 0 10,8G 0 part +---- + +<<< + +==== +3e + +Una vez preparada la tarjeta para su uso, se puede arrancar el core de Spectrum con una ROM de +3e, y formatear la parte de IDEDOS según se desee. + +El primer paso consiste en determinar la geometría de la microSD. Con la tarjeta insertada en el ZXTRES, desde el core de Spectrum con la ROM de +3e, ejecutar el comando: + +[source,basic] +---- +CAT TAB +---- + +Esto devoverá un resultado indicando el número de https://es.wikipedia.org/wiki/Cilindro-Cabezal-Sector[cilindros, cabezales y sectores]. + +Teniendo esto en cuenta, calculamos el espacio que ocupa nuestra partición, en cilindros. Por ejemplo, si el número de cilindros obtenido es de 32768, y queremos utilizar 1GB de una tarjeta de 16GB, el número de cilindros que se necesitarían son 32768/16=2048. Por tanto, podemos formatear la partición IDEDOS usando ese número: + +[source,basic] +---- +FORMAT TO 0,100,2048 +---- + +El primer valor (`0`) indica el disco a utilizar (el primero), el segundo valor es el número máximo de particiones IDEDOS que se podrán usar, y el tercer valor es el número de cilindros a utilizar. + +Una vez hecho el formato, ya será posible crear nuevas particiones. Por ejemplo, para crear una partición llamada "Software" de 16MB, una llamada "Swap1", de 4MB (para usar como espacio swap) y otra llamada "Utils" de 8MB: + +[source,basic] +---- +NEW DATA "Software",16 +NEW EXP "Swap1",4 +NEW DATA "Utils",8 +---- + +Para más información sobre el uso de los distintos comandos de +3e para acceso al disco, se puede visitar https://worldofspectrum.org/zxplus3e/espanol/index.html[esta página en World of Spectrum]. + +<<< + +=== Comandos de esxdos + +==== Guía básica + +Existen dos tipos diferentes de comandos de esxdos, los llamados comandos "DOT", que, como su nombre indica, comienzan por un punto, y las extensiones de la funcionalidad de comandos existentes en BASIC. + +Los principales comandos "DOT" commands son los siguientes: + +- `128`: Para pasar al modo 128K desde el modo 48K. +- `cd`: Cambiar el directorio actual de trabajo. +- `chmod`: cambiar los atributos de los ficheros de la tarjeta microSD. +- `cp`: Copiar un archivo. +- `divideo`: Reproduce un archivo de vídeo Divideo (.DVO). +- `drives`: Mostrar las unidades disponibles. +- `dskprobe`: Utilidad para ver el contenido a bajo nivel de un dispositivo de almacenamiento. +- `dumpmem`: Permite volcar contenido de la memoria RAM a un fichero. +- `file`: Intenta determinar el tipo de un fichero por su contenido (como el comando de UNIX). +- `gramon`: Monitor para buscar gráficos, sprites, fuentes de texto, etc. en la memoria RAM. +- `hexdump`: Muestra el contenido de un fichero usando notación hexadecimal. +- `hexview`: Permite ver y navegar por el contenido de un fichero usando notación hexadecimal. +- `launcher`: Crea un atajo (launcher) para abrir directamente un fichero TAP. +- `ls`: Ver el contenido de un directorio. +- `lstap`: Ver el contenido de un fichero .TAP +- `mkdir`: Crear un directorio. +- `mktrd`: Crear un fichero imagen de disquete .TRD +- `more`: Ver el contenido de un archivo de texto. +- `mv`: Mover un archivo. +- `partinfo`: Muestra información sobre las particiones de un dispositivo de almacenamiento. +- `playpt3`: Reproducir un archivo musical .PT3. +- `playsqt`: Reproducir un archivo musical .SQT. +- `playstc`: Reproducir un archivo musical .STC. +- `playtfm`: Reproducir un archivo musical .TFC. +- `playwav`: Reproducir un archivo de audio .WAV. +- `rm`: Borrar un archivo o directorio. +- `snapload`: Carga ficheros snapshot. +- `speakcz`: Reproduces texto usando pronunciación checa. +- `tapein`: Montar un archivo .TAP para poder ser utilizado luego desde BASIC con la sentencia LOAD +- `tapeout`: Montar un archivo .TAP para poder ser utilizado luego desde BASIC con la sentencia SAVE +- `vdisk`: Monta una unidad de disquete .TRD para usar en el entorno TR-DOS (Una vez montadas todas las unidades deseadas, se puede entrar en el emulador de TR-DOS escribiendo: `RANDOMIZE USR 15616`) + +Algunos comandos extendidos de BASIC son: + +- `GO TO` para cambiar de unidad y/o directorio (ej: `GO TO hd1` o `GO TO hd0"juegos"`) +- `CAT` para mostrar el contenido de una unidad +- `LOAD` para cargar un fichero desde una unidad (programa en BASIC, pantalla, código, etc. por ejemplo `LOAD *"Pantalla.scr" SCREEN$`) +- `SAVE` para guardar datos en un fichero (Ej: `SAVE *"Programa.bas"`) +- `ERASE` para borrar un fichero + +Además, esxdos incluye un gestor NMI, es decir, una aplicación que se carga cuando se pulsa NMI (F5) y que facilita la navegación por la tarjeta microSD y la carga de algunos tipos de archivo (TAP, Z80, TRD, etc.). Pulsando la tecla "H" se accede a una pantalla de ayuda, en la que se indican todas las teclas disponibles. + +[NOTE] +==== +El gestor de esxdos muestra las entradas de archivos y directorios en el orden de la tabla FAT interna, y no de manera alfabética. Si se desea ver esta información ordenada, se debe reorganizar la estructura de la tarjeta con una utilidad como FAT Sorter para Windows, https://fatsort.sourceforge.io/[FATsort] para Linux y MacOS, https://www.luisrios.eti.br/public/en_us/projects/yafs/[YAFS], http://www.trustfm.net/software/utilities/SDSorter.phpp[SDSorter] u otros. +==== + +[CAUTION] +==== +En el caso de utilizarse también la tarjeta con un core de PC XT, **no se debe utilizar ninguna utilidad de reordenación de FAT** ya que esto puede provocar que deje de arrancar correctamente DOS en dicho core. +==== + +<<< + +==== Comandos para ZXTRES + +Tal y como se ha explicado en la parte de instalación, existe una serie de comandos que son exclusivos para ZXTRES, y que se describen a continuación: + +- `back16m`: Copia a un fichero `FLASH.ZX1` en el directorio raíz de la tarjeta microSD el contenido de una memoria SPI Flash de 16 megas. Se debe ejecutar desde una ROM en modo "root". Tras terminar su ejecución hay que ejecutar el comando `.ls` para que se termine de grabar la cache en la tarjeta. +- `backzx2` o `backzxd`: Genera un fichero `FLASH_32.ZX2` o `FLASH_32.ZXD` en el directorio raíz de la tarjeta microSD el contenido de una memoria SPI Flash de 32 megas. Se debe ejecutar desde una ROM en modo "root". Cuando termine hay que ejecutar el comando `.ls` para que se termine de grabar la cache en la tarjeta microSD. Si no se hace, la longitud del archivo se quedará en 0 de forma errónea. +- `corebios`: Para hacer una actualización conjunta del core de ZX Spectrum y de la BIOS. +- `dmaplayw`: Reproduce un archivo de audio .WAV, que debe ser de 8 bits, sin signo y muestreado a 15625 Hz. +- `esprst`: Resetea el módulo WiFi ESP8266(ESP-12). +- `iwconfig`: Configura el módulo WiFi. +- `joyconf`: Configura y prueba los joysticks de teclado y DB9. +- `keymap`: Sirve para cargar una definición de teclado diferente. +- `loadpzx`: Para cargar un archivo de imagen de cinta .PZX. +- `loadtap`: Para cargar un archivo de imagen de cinta usando la integración con .PZX. +- `playmid`: Reproduce archivos musicales .MID en el addon MIDI. +- `playrmov`: Reproduce vídeos en <<#_creación_de_vídeos_rdm_radastan_movie,formato radastaniano (ficheros `.RDM`)>>. Este comando no funciona en modo 48K. +- `romsback`: Copia a un fichero RomPack, llamado `ROMS.ZX1`, en el directorio raíz de la tarjeta microSD todas las ROMS del core ZX Spectrum almacenadas en la memoria SPI Flash. Sólo funciona correctamente en ZX-Uno y ZXDOS (no utilizar en ZXDOS+, ZXTRES o similares). Se debe ejecutar desde una ROM en modo "root". +- `romsupgr`: Copia el contenido de un fichero RomPack, llamado `ROMS.ZX1`, en el directorio raíz de la tarjeta microSD con todas las ROMS para el core ZX Spectrum a la memoria SPI Flash. Se debe ejecutar desde una ROM en modo "root". +- `upgr16m`: Copia el contenido de un fichero `FLASH.ZX1` en el directorio raíz de la tarjeta microSD a una memoria SPI Flash de 16 megas. Se debe ejecutar desde una ROM en modo "root". +- `upgrzx2` o `upgrzxd`: Copia el contenido de un fichero `FLASH_32.ZX2` o `FLASH_32.ZXD` a una memoria SPI Flash de 32 megas.Versión del comando upgrade exclusivo para memorias SPI Flash de 32 Megas. Se debe ejecutar desde una ROM en modo "root". +- `zxuc`: Configura todas las opciones de la BIOS, permitiendo grabar en la microSD las opciones seleccionadas en archivos de configuración que pueden posteriormente ser cargados. +- `zxunocfg`: Configura determinados aspectos del funcionamiento del ZX-Uno como los timings, la contención, el tipo de teclado, la velocidad de la CPU, el tipo y frecuencia vertical del vídeo. + +<<< + +=== Creación de vídeos RDM (RaDastan Movie) + +El comando `PLAYRMOV` reproduce vídeos en formato radastaniano. Para poder convertir nuestros propios vídeos, se debe obtener la utilidad `makevideoradas` desde el https://svn.zxuno.com/svn/zxuno/software/modo_radastan/videos_radastanianos/[Repositorio SVN]. + +En el caso de Windows, en el propio repositorio hay un ejecutable (`makevideoras.exe`) ya preparado. Para Linux o MacOS, será necesario tener las herramientas de desarrollo correspondientes y compilarlo. + +[source,shell] +---- +gcc makevideoradas.c -o makevideoradas +---- + +Una vez dispongamos de `makevideoradas`, necesitaremos otras dos herramientas: https://ffmpeg.org[`ffmpeg`] e https://imagemagick.org/index.php[`imagemagick`]. Estas se pueden instalar con el gestor de paquetes corespondiente (`apt`, `yum`, `pacmam`, `brew`, etc.) o descargando el código fuente y compilándolo también. + +Ahora, el primer paso para convertir nuestro vídeo (por ejemplo, `mivideo.mp4`), es exportar los fotogramas como imágenes BMP de 128x96 píxeles de tamaño. Crearemos un directorio temporal (`img` en este ejemplo), donde guardar dichas imágenes. + +[source,shell] +---- +mkdir img +(...)/ffmpeg -i mivideo.mp4 -vf "scale=128:96,fps=25" -sws_flags lanczos -sws_dither ed -pix_fmt rgb4 -start_number 0 img/output%05d.bmp +---- + +Ahora transformaremos los ficheros `BMP` a `BMP` (v3) de 16 colores. + +[source,shell] +---- +(...)/magick mogrify -colors 16 -format bmp -define bmp:format=bmp3 img/*.bmp +---- + +Finalmente, creamos el fichero `.RDM` (en este ejemplo `mivideo.rdm`) y borramos las imágenes y el directorio temporal. + +[source,shell] +---- +(...)/makevideoradas img/output +mv img/output.rdm ../mivideo.rdm +rm -rf img +---- + +En https://www.zonadepruebas.com/viewtopic.php?t=4796&start=110[este hilo del foro Zona de Pruebas] hay más información sobre todo este proceso. + +<<< + +== Actualizaciones + +=== BIOS + +Para actualizar BIOS se ha de obtener un fichero llamado `FIRMWARE.ZX3`. La última versión de los ficheros de firmware se puede descargar desde https://github.com/zxdos/zxuno/tree/master/firmware[el repositorio oficial] + +[CAUTION] +==== +Actualizar el firmware (BIOS) es delicado, no se debe hacer si no es necesario. En el caso de hacerlo, procurar que el ZXTRES tenga alimentación ininterumpida (como un SAI o un USB de portatil con batería). +==== + +Copiar el fichero en la raíz de la tarjeta MicroSD, encender y pulsar `F2` para entrar en la BIOS, seleccionar `Upgrade`, elegir __"Upgrade BIOS for ZX"__, y luego __"SDfile"__. El sistema leerá el fichero `FIRMWARE...` y avisará cuando esté actualizado. + +=== ROMs + +La memoria flash del ZXTRES dispone de 64 "slots", de 16K cada uno, para almacenar imágenes ROM de ZX Spectrum y compatibles. Así, la ROM del ZX Spectrum original (16K) ocuparía un slot del almacenamiento, la del ZX Spectrum 128K (32K) ocuparía dos slots, y la del ZX Spectrum +2A (64K) ocuparía 4 slots. + +Se puede añadir una nueva ROM desde <<#_roms,la pantalla ROMs>> de la BIOS, pulsando la tecla `N`, conectando un cable de audio a la entrada de sonido de la placa, y reproduciendo una cinta de carga de ROM. Las cintas de carga de ROM se pueden crear desde un archivo `.tap` generado con la utilidad `GenRom`, disponible en el https://github.com/zxdos/zxuno/tree/master/modflash[repositorio de código de ZX-Uno]. + +Para actualizar las ROM instaladas para ZX Spectrum de forma masiva, se ha de obtener un fichero RomPack con el nombre `ROMS.ZX1`, y se tiene que copiar en la tarjeta MicroSD. Arrancar el ZXTRES usando una ROM en modo "root", y entonces bastará con introducir el comando `.romsupgr`. Esto grabará todas las ROM, que quedarán disponibles para su uso. + +[NOTE] +==== +Recordar que, si se inicia el ZXTRES pulsando la tecla `/` (del teclado numérico), entonces se cargará la ROM por defecto del core de ZX Spectrum en modo "root". +==== + +Para hacer el proceso contrario (guardar las ROMs en un fichero RomPack llamado `ROMS.ZX1`), se puede usar el comando `.romsback`. + +[NOTE] +==== +La versión actual de `romsback`, en ZXTRES, sólo almacena correctamente en RomPack los primeros 35 slots de ROM ocupados. +==== + +Los ficheros RomPack se pueden editar fácilmente con la utilidad https://guest:zxuno@svn.zxuno.com/svn/zxuno/software/ZX1RomPack/[ZX1RomPack]. Aunque es un programa de Windows, funciona perfectamente, por ejemplo, usando https://www.winehq.org[Wine] o programas similares, tanto en MacOS como en Linux. + +=== Cores + +Un core consiste en un fichero con la información necesaria para que la FPGA se comporte como el sistema a implementar (ZX Spectrum, etc.). En ZXTRES, este fichero es posible cargarlo desde varios lugares distintos: la memorria SPI Flash, una tarjeta microSD, o desde algún dispositivo externo (PC, etc.) utilizando un cable especial. + +==== Tarjeta microSD + +===== Carga desde el core de ZX Spectrum + +Desde el core principal de ZX Spectrum es posible cargar otros cores + +====== Navegador de Bob Fossil + +Para poder utilizar el navegador de Bob Fossil para cargar cores, se necesita lo siguiente: + +- La última versión estable (http://www.thefossilrecord.co.uk/wp-content/uploads/zx/BROWSE_latest.zip) +- El plugin ZX3 para poder cargar Cores en formato ZX3 https://github.com/zxdos/zxuno/blob/master/SD/BIN/BPLUGINS/ZX3 + +Se ha de copiar el fichero `.ZX3` correspondiente en el lugar que se desee de la tarjeta microSD, así como el plugin ZX3 adecuado (en la carpeta `BIN\BPLUGINS``). + +. Iniciar el core Spectrum de ZXTRES en modo root (pulsando `/` durante el arranque de la BIOS hasta que se ponga el borde rojo). +. Pulsar `F5` para abrir el navegador de Bob Fossil y navegar hasta la ubicación del Core con extensión `.ZX3`, seleccionarlo y pulsar ENTER. + +Si todo va bien, en la parte inferior de la pantalla se indicará el progreso de grabación en la SPI Flash (se graba en un slot temporal). + +En el caso de que no se hubiese arrancado en modo root bastará con reiniciar (ctrl+alt+backspace) dejando pulsado "/" y probar de nuevo. + +<<< + +==== Memoria SPI Flash + +Hay 27 espacios de 1MB disponibles para almacenar cores, estando reservados los primeros espacios para el de ZX Spectrum principal (esto no impide tener más cores de ZX Spectrum en otros espacios además de los primeros). + +Los cores oficiales están https://github.com/zxtres/cores[disponibles para descargar] en el repositorio en GitHub. + +Para actualizar o instalar un nuevo core en la SPI Flash hay varias alternativas. + +La primera forma consiste en obtener la última versión de los ficheros que lo definen. Si el tamaño que ocupa es superior a 1179648 bytes, se tendrá que trocear adecuadamente. Cada uno de los trozos será ahora un fichero que hay que llamar `COREXXy.ZX3`, donde XX _siempre_ es un número de dos digitos. La parte `y` del nombre se ignora, así que se pueden usar nombres más largos y descriptivos (como, por ejemplo, `CORE04_ejemplo_parte1.ZX3`). + +Copiar los ficheros en la raíz de la tarjeta microSD, encender y pulsar `F2` para entrar en la BIOS. Elegir `Upgrade`, seleccionar la fila correspondiente al número de espacio elegido (por ejemplo, la 4), pulsar enter y luego __"SD file"__. El sistema leerá el fichero `COREnn...` y avisará cuando esté actualizado, aunque antes preguntará el nombre (con el que se verá en la lista para elegir en el arranque y en el listado de la BIOS). Habitualmente, en el caso de cores que ocupan varios espacios se reserva el nombre de core para la primera parte y el resto de partes se registran con un mensaje recordando que no se deben utilizar. Una vez instalado, se podrá utilizar al arrancar, seleccionando siempre el primero de los espacios que use el core. + +[WARNING] +==== +La actualización del core principal de ZX Spectrum es exactamente igual que los otros cores, pero en lugar del fichero `CORE1.ZX3`, ha de ser un fichero llamado `SPECTRUM.ZX3` con un formato especial para la primera parte. +==== + +<<< + +=== esxdos + +Para actualizar esxdos a una nueva versión, se ha de obtener la distribución desde https://www.esxdos.org[la página oficial]. + +Una vez descargado y descomprimido, se ha de copiar, a la raíz de la tarjeta, el contenido de los directorios `BIN` y `SYS` sobreescribiendo los existentes (para preservar los comandos exclusivos de ZXTRES). + +Copiar `ESXMMC.BIN` (o `ESXMMC.ROM`, según la versión) en la raíz de la tarjeta microSD. + +Iniciar el ZXTRES con la tarjeta insertada y pulsar F2 para acceder a la configuración de BIOS. Seleccionar el menú `Upgrade` y elegir __"Upgrade esxdos for ZX"__. En el diálogo que aparece elegir __"SD file"__ y, cuando pregunte __"Load from SD"__ contestar __"Yes"__ a la pregunta __"Are you sure?"__. Se leerá el contenido del fichero `ESXDOS...`, se grabará en la flash y avisará cuando esté actualizado. + +Realizar un Hard-reset, o apagar y encender. + +Si todo se ha hecho correctamente, al encender el ZXTRES se verá cómo esxdos detecta la tarjeta y carga los componentes necesarios para funcionar, mostrando la nueva versión en la parte superior. + +=== Memoria Flash + +También es posible actualizar la memoria flash de la FPGA. Por el momento desde el menú de la BIOS sólo es posible utilizar imágenes de 16MiB. Para poder usar una imagen de 32MiB, se ha de usar el comando `UPGRZXD` de <<#_esxdos,esxdos>> y un fichero con el nombre `FLASH.ZXD`. + +Copiar el archivo de imagen (de 16MiB) `FLASH.ZX3` en la raíz de la tarjeta microSD. + +Iniciar el ZXTRES con la tarjeta insertada y pulsar F2 para acceder a la configuración de BIOS. Seleccionar el menú `Upgrade` y elegir __"Upgrade flash from SD"__. En el diálogo que pregunta __"Load from SD"__ contestar __"Yes"__ a la pregunta __"Are you sure?"__. Se leerá el contenido del fichero `FLASH...`, . + +Realizar un Hard-reset, o apagar y encender. + +[WARNING] +==== +Este proceso sustituye todos los cores instalados, la BIOS, así como las ROMs de ZX Spectrum y la configuración por lo que haya en la imagen, y no se puede deshacer. +==== + +<<< + +== Otros cores + +=== ColecoVision + +https://es.wikipedia.org/wiki/ColecoVision[ColecoVision] es una consola de videojuegos lanzada al mercado por la empresa Coleco. + +La versión para ZXTRES está basada en la https://github.com/fbelavenuto/colecofpga[versión para ZX-Uno] de Fabio Belavenuto. + +Algunas de las características del core son: + +- La ROM de la BIOS se carga desde la tarjeta microSD +- Soporta ROM multicartucho, que también se carga desde la microSD +- Sólo funciona en VGA + +==== Formato de Tarjeta microSD + +Se debe de utilizar una tarjeta microSD, con la primera partición en formato FAT16 o FAT32, para almacenar los ficheros con las imágenes ROM y otros archivos necesarios. Los archivos se pueden descargar desde la https://github.com/fbelavenuto/colecofpga/tree/master/SD_Card[web del proyecto original en GitHub]. + +Una vez copiados los ficheros en la tarjeta, se necesita además el fichero `MULTCART.ROM` que se puede obtener en https://t.me/zxtresfpga + +Si no estuviera ya, <<#_cores,instalar el core de ColecoVision>> en el ZXTRES. + +==== Teclado + +===== Teclas especiales y botones + +Durante la ejecución del core: + +- Cursor o `Q`, `A`, `E`, `R` o el joystick 1: Controles de dirección del jugador 1 +- `Z` o el botón de joystick 1: Botón de disparo 1 del jugador 1 +- `U`, `J`, `O`, `P` o el joystick 2: Controles de dirección del jugador 2 +- `M` o el botón de joystick 2: Botón de disparo 1 del jugador 2 +- `X` o el botón secundario de joystick 1: Botón de disparo 2 del jugador 1 y del jugador 2 +- `0` a `9`: Botones del 0 al 9 del jugador 1 y el jugador 2 +- `T`: Botón '*' +- `Y`: Botón '#' +- 'Esc': Soft Reset + +<<< + +==== Guía básica + +Al iniciar, la ROM de la BIOS se carga desde la tarjeta microSD, así como la ROM multicartucho. + +[.text-center] +image:img/coleco.jpg[scaledwidth=70%] + +En el menú multicartucho, usar los controles de dirección para elegir la ROM a cargar, y luego el botón de disparo 1 para cargar la ROM elegida. Pulsando `Esc` se reinicia el core y se vuelve a cargar el menú de selección de ROM. + +<<< + +=== Neo-Geo + +<<< + +=== Test DP + +Core alternativo, cuyo objetivo es probar el funcionamiento correcto de las salidas de vídeo VGA, RGB y DisplayPort, aplicando distintos efectos. + +Sus características principales son: + +- Salida de vídeo DisplaPort +- Salida de vídeo VGA +- Salida de vídeo RGB a 15 kHz (utilizando el puerto VGA) +- Scanlines +- Modos de color fósforo verde, fósforo ambar, escala de grises y color + +==== Formato de Tarjeta microSD + +Este core no utiliza la tarjeta microSD. + +==== Teclado + +===== Teclas especiales y botones + +Durante la ejecución del core: + +- `1`: Hace que la salida VGA cambia a RGB 15 kHz +- `2`: Activa y desactiva scanlines +- `3`: Cambia la pantalla entres los modos de color, fósforo verde, fósforo ambar y escala de grises + +[NOTE] +==== +Los efectos antes mencionados con las teclas 2 y 3 no se ven en la salida original de 15 kHz. +==== + +==== Guía básica + +Cuando arranca el core, envia señal tanto por VGA como por DisplayPort. La frecuencia de refresco es de unos 64 Hz. + +Los tres leds de la placa tienen el siguiente significado: + +- El que esta más cerca del borde debe lucir encendido todo el rato. Es el led de DONE, y lo maneja la propia FPGA, no el core. +- El de en medio indica, cuando esta encendido, que hay enlace de transmision valido entre la FPGA y el monitor DisplayPort. Esto significa que el enlace está bien, que el entrenamiento ha sido exitoso, y que en este momento está enviando ya imagen de video al monitor. Si está apagado, significa que no se ha podido establecer el enlace (por ejemplo porque se ha quitado el cable, o está apagado el monitor, o quizás porque no está la entrada DisplayPort seleccionada en dicho monitor). +- El del otro extremo debe lucir parpadeando, a razón de un parpadeo por segundo mas o menos. Es un "latido" del reloj de pixel que indica que tanto la salida VGA como la DisplayPort estan generando imagen. Si este led no parpadea, no se podrá ver imagen de ningun tipo ni por VGA ni por DisplayPort, tan sólo por RGB a 15 kHz. En circunstancias normales, tanto si hay enchufado un monitor DisplayPort como si no, este led debería estar parpadeando. + +<<< + +=== ZX81 + +El computador personal https://es.wikipedia.org/wiki/ZX81[Sinclair ZX81], lanzado por Sinclair Research en 1981, fue el de menor precio de la época. + +La versión para ZXTRES ha sido creada por avlixa, basada en la página de Grant Searle's sobre el ZX80 + +Características: + +- Se puede elegir entre ZX80 y ZX81 (ZX80 sólo con salida RGB por el momento) +- 16k/32k/48k RAM packs +- 8KB con addon CHR$128/UDG (sin probar) +- QS CHRS (sin probar) +- CHROMA81 +- Turbo en modo lento: NoWait, x2, x8 +- Chip de sonido YM2149 (compatible con ZON X-81) +- Múltiples joysticks (Cursor, Sinclar, ZX81, ZXpand) +- Timings PAL y NTSC +- Turbo carga de ficheros .o y .p +- Carga de ROM alternativa +- Carga de programas a través de la entrada de audio + +==== Formato de Tarjeta microSD + +Se debe de utilizar una tarjeta microSD, con la primera partición en formato FAT16 o FAT32, para almacenar los ficheros con archivos de cinta o ROM que se deseen cargar. + +Se puede copiar, si se desea, un fichero `ZX8X.ROM` (disponible the https://github.com/avlixa/ZX81_MiSTer_zxdos/raw/master/roms/zx8x.rom[repositorio oficial] en el directorio `/zx81/roms`: se trata de los ficheros ZX81 rom (8k) + ZX80 rom (4k) concatenados. + +Si no estuviera ya, <<#_cores,instalar el core de ZX81>> en el ZXTRES. + +<<< + +==== Teclado + +El teclado no está mapeado a la distribución PS/2 estándar, y mantiene la distribución de la máquina original. Así, por ejemplo, para obtener `"` se ha de pulsar `Mayús+P` o para borrar, `Mayús+0`. + +**ZX80** + +[.text-center] +image:img/keyboardZX80.jpg[scaledwidth=80%] + +**ZX81** + +[.text-center] +image:img/keyboardZX81.jpg[scaledwidth=80%] + +===== Teclas especiales y botones + +Durante la ejecución del core: + +- `F1`: Habilitar o deshabilitar los caracteres alternativos +- `F5` o el botón 2 del joystick para mostrar u ocultar el menú. +- `F9`: Deshabilita o habilita la salida MIC al conector de audio, porque algunos juegos generan un ruido molesto +- `F10`: Habilita o deshabilita sonido de entrada por la salida de audio, para escuchar la cinta si se carga por audio +- `Bloq. Despl.`: para cambiar entre modo de vídeo RGB y VGA +- `Ctrl+Alt+Supr`: Reset +- `Ctrl+Alt+Backspace`: Hard reset. + +<<< + +==== Guía básica + +Pulsando `F5` o el botón 2 del joystick se muestra el menú de configuración. Se usan las teclas de cursor y `Enter` para elegir y seleccionar opciones del menú. + +[.text-center] +image:img/zx81.jpg[scaledwidth=70%] + +En él se pueden activar, desactivar o configurar las siguientes opciones: + +- Reiniciar el core (Reset) +- Cargar un archivo de cinta (Load Tape) +- Cargar una ROM alternativa (Load ROM) +- Configurar opciones (Configuration Options) +- Salir del menú (Exit) + +<<< + +[.text-center] +image:img/zx81_2.jpg[scaledwidth=70%] + +- Elegir el modelo de computador (Computer Model): ZX80/ZX81 +- Tamaño de RAM (Main RAM): 16K/32K +- RAM baja (Low RAM): Off/8KB +- Joystick: Cursor/Sinclair/ZX81 +- Habilitar o deshabilitar QS CHRS +- Configuración de CHR$128/UDG: 128 chars/64 chars/Disabled +- Habilitar o deshabilitar Chroma81: Disabled/Enabled +- Vídeo inverso (Inverse Video): Off/On +- Borde negro (Black Border): Off/On +- Modo de velocidad (Slow mode speed): Original/No Wait/x2 +- Frecuencia de vídeo (Video frequency): 50Hz/60Hz + +Desde BASIC, se puede cargar desde un fichero cinta, que se haya seleccionado desde el menú, con el comando `LOAD""` y pulsando `Enter`. + +[TIP] +==== +Algunos monitores dejan de reproducir la entrada de audio si se desactiva la señal de vídeo. Se recomienda conectar unos auriculares o altavoces externos para poder oir el sonido durante la carga de una cinta. +==== + +Se pueden cargar archivos `.p` con color y caracteres alternativos. + +Para que funcione el coloreado, se debe activar CHROMA81 antes de la carga. Igualmente, para los caracteres alternativos, QS CHRS debería estar activo antes de cargar. + +[TIP] +==== +Las opciones recomendadas para la mayoría de los juegos son: + +Main RAM: 16KB +Low RAM: 8KB +CHR$128: 128 chars +QS CHRS: enabled +CHROMA81: enabled +==== + +<<< + +=== zxsp + +<<< + +== Otro Hardware + +=== Carga desde cinta + +Para algunos cores como, por ejemplo, el de Spectrum o el de MSX, es posible cargar, igual que se hacía en las máquinas originales, desde un dispositivo externo de audio como un reproductor de cassette u otro que lo simule. + +Normalmente, se debe utilizar un cable adecuado para la <<#_puertos_y_conectores,entrada de sonido del ZXTRES>>, concretamente, ha de ser un cable con un jack estéreo de 3,5 mm en un extremo dos salidas mono en el otro (una para cada canal de audio), conectando el extremo del canal mono derecho al dispositivo de reproducción de cintas (esto no es necesario en Miniduino, ya que este automáticamente utiliza sólo el canal derecho de sonido al reproducir). + +==== Reproductor de cassette + +El funcionamiento es exactamente igual que se hacía con los equipos originales: + +. Conectar el cable de audio +. Ejecutar en el equipo o elegir la opción correspondiente a la carga desde cinta. Por ejemplo, en ZX Spectrum 48K, pulsando `J`, a continuación, dos veces, `"` y luego `Enter` para ejecutar el clásico `LOAD "" + Enter` +. Iniciar la reproducción de la cinta (es posible que haya que hacer distintos intentos ajustando el volumen del reproductor) + +==== Ordenador + +Según el sistema operativo (Windows, MacOS, Linux) existen múltiples alternativas de programas que pueden, o bien reproducir directamente un archivo de cinta (`TAP`, `TZX`, `PZX`, etc.) y emitir el sonido por la salida de auriculares, o bien crear un fichero de sonido (`WAV`, `VOC`, `AU`, etc.) que se puede reproducir también con programas de música o sonido. + +===== PlayTZX + +Este programa para Windows, MacOS o Linux, permite reproducir un fichero de cinta `TZX` a través de la salida de sonido del ordenador. + +Se puede descargar el fichero binario (por ejemplo, para Windows desde https://worldofspectrum.net/utilities/#tzxtools[World of Spectrum Classic] y para Mac desde https://github.com/kounch/playtzx/releases[este repositorio de GitHub]) o compilar el código fuente como se explica <<#_compilar_código_fuente_macos_o_linux,a continuación>>. + +. Conectar el cable de audio entre la salida del ordenador y la entrada de audio del ZXTRES (recordar conectar únicamente el extremo del canal mono derecho al extremo del PC/Mac, etc.) +. Ejecutar en el equipo o elegir la opción correspondiente a la carga desde cinta. Por ejemplo, en ZX Spectrum 48K pulsando `J` a continuación, dos veces, `"` y luego `Enter` para ejecutar el clásico `LOAD "" + Enter` + +<<< + +[start=3] +. Iniciar la reproducción de un fichero de cinta con el siguiente comando (es posible que haya que hacer distintos intentos ajustando el volumen de salida del equipo) + +[source,shell] +---- +./playtzx +---- + +Si todo va bien, se irá viendo en la consola los distintos bloque de carga de la cinta, mientras el sonido se produce y el core del ZXTRES carga el programa. + +[TIP] +==== +En Linux, el programa utiliza como salida el dispositivo `/dev/dsp`, así que, en versiones más modernas, es posible, por ejemplo, que haya que cargar módulos como `snd_pcm_oss` (en el caso de sistemas que utilicen ALSA), para que funcione correctamente. +==== + +====== Compilar código fuente (MacOS o Linux) + +Verificar que están instaladas las herramientas de desarrollo, incluyendo un compilador de C (`gcc`, `clang` herramientas de desarrollaor de línea de comandos en Mac, etc.) y https://es.wikipedia.org/wiki/GNU_build_system[GNU Autotools]. + +Descargar el código fuente https://github.com/kounch/playtzx[desde este repositorio]), descomprimirlo y acceder en una consola al directorio, y ejecutar los comandos: + +[source,shell] +---- +aclocal && autoconf && autoheader && automake --add-missing +./configure +make +---- + +Si todo se ha hecho correctamente, se habrá generado el fichero `playtzx` que se puede copiar a donde se desee en el disco duro y utilizar. Se puede borrar el directorio descomprimido donde se compiló. + +==== Teléfono móvil, tableta, reproductor de sonido MP3, etc. + +En general, existen muy pocas alternativas (o ninguna) alternativas de programas que puedan reproducir directamente un archivo de cinta en un dispositivo móvil, así que, normalmente, será necesario convertir a un fichero de audio el contenido de la cinta antes de intentar cargarla con uno de estos aparatos. + +https://github.com/semack/zx_tape_player[ZX Tape Player] es una App para sistemas iOS y Android que es capaz de reproducir directamente a través de la salida de auriculares + +https://play.google.com/store/apps/details?id=com.baltazarstudios.playzxtapes[PlayZX] es otra App similar, pero sólo para sistemas Android. + +[WARNING] +==== +Los dispositivos con salida de auriculares modernos, suelen estar pensados para manejar impedancias el orden de unas pocas decenas de ohmios. Esto, a veces, puede ser insuficiente para la entrada del ZXTRES. + +En esos casos, se recomienda (si es posible) desactivar las limitaciones de volumen máximo de auriculares y/o utilizar un dispositivo amplificador de auriculares, que eleve la impedancia. +==== + +Los pasos a seguir en este caso son: + +. Conectar el cable de audio entre la salida del dispositivo móvil y la entrada de audio del ZXTRES (recordar conectar únicamente el extremo del canal mono derecho al extremo del PC/Mac, etc.) +. Ejecutar en el equipo o elegir la opción correspondiente a la carga desde cinta. Por ejemplo, en ZX Spectrum 48K pulsando `J` a continuación, dos veces, `"` y luego `Enter` para ejecutar el clásico `LOAD "" + Enter` +. Iniciar la reproducción del fichero de audio (o del fichero de cinta en el caso de PlayZX). Es posible que haya que hacer distintos intentos ajustando el volumen del reproductor/amplificador. + +===== Conversión a fichero de audio + +A continuación se indican algunos de los muchos programas que existen para distintos sistemas operativos, y que pueden exportar ficheros de cinta a ficheros de audio. + +https://www.alessandrogrussu.it/tapir/index.html[Tapir] es un programa con interfaz gráfica para Windows (pero que se puede usar también con Wine en Linux o Mac) que permite cargar ficheros `TZX` y `TAP` y exportarlos como `WAV` de audio + +`tape2wav` de https://fuse-emulator.sourceforge.net/[Fuse Utilities] es una utilidad de línea de comandos que exporta desde ficheros `TZX` `PZX` y `TAP` a `WAV`. Disponibles para muchos sistemas operativos distintos. + +`pzx2wav` en http://zxds.raxoft.cz/pzx.html[PZX Tools] es otra utilidad de comandos que exporta desde ficheros `PZX` a `WAV`. Disponible como ejecutable para Windows, y con el código fuente disponible para compilar en otros sistemas. + +<<< + +==== Miniduino + +include::miniduino_es.adoc[leveloffset=+3] + +<<< + +== Solución de problemas + +=== Gestión de imágenes de firmware + +Existen distintas herramientas que permiten generar y/o editar el contenido de los ficheros `ZX1`, `ZX3`. + +==== zx123_tool + +Esta es una herramienta que analiza, extrae o añade datos en ficheros de imagen de SPI flash de ZX-Uno, ZXDOS, ZXTRES y otros dispostivos similares. + +Para poder utilizarla se necesita https://www.python.org/[Python 3]. Según el sistema operativo que se utilice puede que sea necesario https://www.python.org/downloads/[instalarlo]. + +Teniendo Python 3, basta con descargar la última versión de la herramienta desde su repositorio oficial, https://github.com/kounch/zx123_tool/releases/latest[en este enlace]. + +Una vez descomprimido, se debe invocar desde una consola el script principal usando Python 3. Esto puede variar según el sistema operativo. + +Por ejemplo, en Windows, suele ser: + +[source,shell] +---- +py -3 zx123_tool.py +---- + +Mientras que en otros sistemas operativos debería bastar con algo parecido a: + +[source,shell] +---- +python3 ./zx123_tool.py +---- + +También hará falta un archivo de imagen flash. Este se puede obtener desde el core de Spectrum, en modo "root", con alguno de los comandos `back16m`, `backzx2` o `backzxd`. Tras obtener el fichero generado en la microSD, se puede "limpiar" dejando sólo el core de Spectrum y la primera ROM de Spectrum con un comando similar a este: + +[source,shell] +---- +... zx123_tool.py -i FLASH.ZXD -w -o FLASHempty.ZXD +---- + +Donde `FLASH.ZXD` es la ruta al fichero obtenido desde el core de Spectrum, y `FLASHempty.ZXD` es la ruta al nuevo fichero "limpio". + +<<< + +*Mostrar contenido de una imagen* + +Para ver el contenido de una imagen llamada `FLASH.ZXD` (cores instalados y algunos datos de configuración), se puede usar el comando + +[source,shell] +---- +... zx123_tool.py -i FLASH.ZXD -l +---- + +Para mostrar contenido de esa misma imagen, incluyendo datos de ROMs de ZX Spectrum: + +[source,shell] +---- +... zx123_tool.py -i FLASH.ZXD -l -r +---- + +*Modificar la BIOS de una imagen* + +Para modificar la BIOS de un fichero llamado `FLASH.ZXD`, usando la BIOS en otro fichero llamado `FIRMWARE.ZXD` + +[source,shell] +---- +...zx123_tool.py -i FLASH.ZXD -a BIOS,FIRMWARE.ZXD +---- + +Además de instalar la BIOS, se pueden modificar algunos de los valores por defecto. Por ejemplo, con las opciones; `-m` para el modo de vídeo: 0 (PAL), 1 (NTSC) ó 2 (VGA), `-k` para la distribución del teclado: 0 (Auto), 1 (ES), 2 (EN) ó 3 (Spectrum). + +Así, para modificar la BIOS de un fichero llamado `FLASH.ZXD`, usando la BIOS en otro fichero llamado `FIRMWARE.ZXD`, y además configurar el modo de vídeo en VGA: + +[source,shell] +---- +...zx123_tool.py -i FLASH.ZXD -a BIOS,FIRMWARE.ZXD -m 2 -k 3 +---- + +Existen también opciones para ajustar el tiempo de espera inicial de la BIOS, el core a ejecutar por defecto, o la ROM de Spectrum a utilizar por defecto. Véase la https://github.com/kounch/zx123_tool/#castellano[documentación de la herramienta] para más información. + +<<< + +*Añadir una ROM de Spectrum a una imagen* + +Para añadir una ROM de Spectrum llamada `48.rom`, poniendo el nombre `Spec48` y ocupando el slot 5, se puede usar un comando como: + +[source,shell] +---- +...zx123_tool.py -i FLASH.ZXD -a ROM,5,xdnlh17,Spec48,48.rom +---- + +Véase la https://github.com/kounch/zx123_tool/#castellano[documentación de la herramienta] para ver todas las posibles opciones a la hora de añadir una ROM de Spectrum. + +Entre los datos que se indican al añadir una ROM, hay una serie de indicadores para definir qué opciones de hardware, etc. se desean habilitar o deshabilitar al cargar esa ROM en concreto, según se puede ver en esta tabla: + +[align="center",width="70%",%header,cols=2*] +|=== +|`i` +|Habilitar teclado issue 3 (en vez de issue 2) +|`c` +|Deshabilitar la contención de memoria +|`d` +|Habilitar DivMMC +|`n` +|Habilitar NMI DivMMC (menú de esxdos) +|`p` +|Usar timings de Pentagon +|`t` +|Usar timings de 128K +|`s` +|Deshabilitar puertos de DivMMC y ZXMMC +|`m` +|Habilitar MMU horizontal de Timex +|`h` +|Deshabilitar bit alto de ROM (bitd 2 de 1FFD) +|`l` +|Deshabilitar bit bajo de ROM (bit 4 de 7FFD) +|`1` +|Deshabilitar puerto 1FFD (paginado de +2A/3) +|`7` +|Deshabilitar puerto 7FFD (paginado de 128K) +|`2` +|Deshabilitar TurboSound (chip AY secundario) +|`a` +|Deshabilitar chip AY +|`r` +|Deshabilitar modo Radastaniano +|`x` +|Deshabilitar modo Timex +|`u` +|Deshabilitar ULAPlus +|=== + +<<< + +*Instalar un Core en una imagen* + +Para instalar un core en la posición 3, desde un fichero llamado `NEXT.ZXD`, llamándolo `Spectrum Next`, usar un comando como este: + +[source,shell] +---- +...zx123_tool.py -i FLASH.ZXD -a 'CORE,3,Spectrum Next,NEXT.ZXD' +---- + +Si además se quiere configurar como el core por defecto, se puede indicar también con un comando como: + +[source,shell] +---- +...zx123_tool.py -i FLASH.ZXD -a 'CORE,3,Spectrum Next,NEXT.ZXD' -c 3 +---- + +*Modificar la ROM de esxdos de una imagen* + +De forma similar a como se instala el firmware de la BIOS, se puede instalar directamente un fichero con la ROM de esxdos, con un comando como: + +[source,shell] +---- +...zx123_tool.py -i FLASH.ZXD -a esxdos,ESXMMC.BIN +---- + +*Combinar varias órdenes en una única línea* + +Notar que se pueden acumular varias órdenes en una única línea de comandos. Por ejemplo, para "limpiar" un archivo de imagen llamado `FLASH.ZXD`, creando uno nuevo llamado `FLASHnew.ZXD`, instalar la BIOS desde el fichero `FIRMWARE.ZXD`, configurar el modo de vídeo en VGA, añadir una ROM de Spectrum llamada `48.rom`, poniendo el nombre `Spec48` y ocupando el slot 5, instalar un core en la posición 3, desde un fichero llamado `NEXT.ZXD`, llamándolo `Spectrum Next`, configurado como el core por defecto, usar un comando como este: + +[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,Spectrum Next,NEXT.ZXD' -c 3 +---- + +<<< + +<<< + +=== Recuperación del firmware + +En algunos casos (por ejemplo al instalar un core experimental o hacer una actualización del core de ZX Spectrum o la BIOS) puede suceder que el ZXTRES deje de arrancar. Se encienden los LEDs pero no hay imagen ni responde a las distintas combinaciones de teclado para acceder a la BIOS, etc. + +En esta situación, existen diferentes métodos de recuperación que permiten volver a instalar el firmware. + +==== Preparación del cableado + +En los siguientes pasos de recuperación se habla de conectar cables puente o USB-Blaster a la placa de ZXTRES. Para ello, usar la siguiente imagen como referencia. + +[.text-center] +image:img/jtagzxtres.jpg[scaledwidth=80%] + +[WARNING] +==== +*NO* se ha de conectar la línea de 3V +==== + +<<< + +==== Recuperación usando una Raspberry Pi + +*Material necesario*: + +- Raspberry Pi (con tarjeta SD, teclado, monitor, fuente de alimentación, etc.) y con conexión a internet +- 5 https://es.wikipedia.org/wiki/Cable_puente[cables puente para prototipos] (idealmente, hembra en los dos extremos) y, opcionalmente, un adaptador USB-Blaster +- Un destornillador de estrella adecuado +- Tarjeta SD para el ZXTRES con la primera partición en formato FAT16 o FAT32 +- Teclado y monitor para conectar el ZXTRES + +*Software necesario*: + +- Imagen Flash y recovery para ZXTRES, del https://github.com/zxtres/cores/tree/main/recovery[repositorio principal de Github]. Notar que existe un fichero distinto para cada tipo de dispositivo: +** `recovery_a35.bit` para ZXTRES +** `recovery_a100.bit` para ZXTRES+ +** `recovery_a200.bit` para ZXTRES++ + +*Pasos a seguir*: + +. Si no estuviera ya, instalar Raspberry Pi OS (antes llamado Raspbian) en la Raspberry Pi (usando https://www.raspberrypi.org/downloads/raspberry-pi-os/[la descarga oficial], https://www.raspberrypi.org/downloads/noobs/[NOOBS], https://github.com/procount/pinn[PINN], etc.) +. Instalar Open OCD en la Raspberry Pi: + +[source,shell] +---- +sudo apt-get update +**sudo apt-get install git autoconf libtool make pkg-config +sudo apt-get install libusb-1.0-0 libusb-1.0-0-dev telnet +sudo apt-get install libusb-dev libftdi-dev +git clone git://git.code.sf.net/p/openocd/code openocd-code +cd openocd-code/ +./bootstrap +./configure --enable-usb_blaster --enable-sysfsgpio --enable-bcm2835gpio +make +sudo make install +cd .. +rm -rf ./openocd-code +---- + +<<< + +[start=3] +. Conectar el USB-Blaster o los cables puente para GPIO <<#_preparación_del_cableado,tal y como se explica anteriormente>>. Si se va a hacer la conexión usando GPIO, abrir la carcasa del ZXTRES y conectar las líneas de JTAG de la FPGA (`TMS`, `TDI`, `TDO`, `TCK` y `GND`), con los cables, a los pines https://es.wikipedia.org/wiki/GPIO[GPIO] de la Raspberry Pi. + +Si se hace conexión vía GPIO, tomar nota de los pines elegidos, teniendo cuidado de conectar `GND` con `GND`. + +[.text-center] +image:img/gpio.jpg[scaledwidth=70%] + +En este ejemplo, se utilizarán los pines `31`, `33`, `35`, `37` y `39` (correspondientes a `GPIO #6`, `GPIO #13`, `GPIO #19`, `GPIO #26` y `GND`), de la siguiente manera: + +[%header,cols=3*] +|=== +|JTAG ZXTRES +|GPIO +|Pin Raspberry Pi +|`TMS` +|GPIO#6 +|`31` +|`TDI` +|GPIO#13 +|`33` +|`TDO` +|GPIO#19 +|`35` +|`TCK` +|GPIO#26 +|`37` +|`GND` +|GND +|`39` +|=== + +[start=4] +. Copiar en la Raspberry Pi el fichero `recovery_axx.bit` obtenido anteriormente del https://github.com/zxtres/cores/tree/main/recovery[repositorio principal de Github]. En nuestro ejemplo, se dejará en `/home/pi/zxtres/unbrick/` + +<<< + +[start=5] +. Para la conexión usando GPIO, realizar una copia del archivo de configuración de Open OCD, en el mismo lugar donde está `recovery.bit`. Este paso no es necesario si se usa USB-Blaster. + +[source,shell] +---- +cp /usr/local/share/openocd/scripts/interface/raspberrypi2-native.cfg /home/pi/zxtres/unbrick/ +---- + +[start=6] +. Para la conexión vía GPIO, editar la copia de `raspberrypi2-native.cfg` actualizando `bcm2835gpio_jtag_nums` (y descomentando, si fuera necesario), según como se haya hecho la conexión entre JTAG y GPIO en la línea `bcm2835gpio_jtag_nums`. En nuestro ejemplo: + +[source] +---- +# Header pin numbers: 37 31 33 35 +bcm2835gpio_jtag_nums 26 6 13 19 +---- + +[start=7] +. Comentar, si no lo está, la línea `bcm2835gpio_swd_nums` (de nuevo, no necesario si la conexión es con USB-Blaster): + +[source] +---- +#bcm2835gpio_swd_nums 11 25 +---- + +[start=8] +. Añadir, al final, la línea `adapter speed 250` (no necesario para uso con USB-Blaster): + +[source] +---- +adapter speed 250 +---- + +[start=9] +. Encender el ZXTRES + +. Asegurarnos de que estamos en el directorio donde se encuentra el archivo `recovery_axx.bit`, y lanzar el comando que carga la BIOS en modo recuperación, indicando, si fuera necesario, la ruta al archivo `raspberrypi2-native.cfg` que habíamos editado anteriormente + +Para conexión vía GPIO: + +[source,shell] +---- +cd /home/pi/zxtres/unbrick +sudo openocd -f /home/pi/zxtres/unbrick/raspberrypi2-native.cfg -f /home/pi/zxtres/unbrick/xilinx-xc7.cfg -c "init; pld load 0 recovery_axx.bit; shutdown" +---- + +Con USB-Blaster: + +[source,shell] +---- +cd /home/pi/zxtres/unbrick +sudo openocd -f /usr/local/share/openocd/scripts/interface/altera-usb-blaster.cfg -f /home/pi/zxtres/unbrick/xilinx-xc7.cfg -c "init; pld load 0 recovery_axx.bit; shutdown" +---- + +[TIP] +==== +Recordar reemplazar en los comandos anteriores `recovery_axx.bit` por el nombre del fichero adecuado para la placa a recuperar. +==== + +[start=11] +. Si todo va bien, veremos cómo cambia el estado de los LED de la FPGA y veremos la imagen de la BIOS en el monitor. + +En el caso de que no se vea imagen, y si no se está utilizando DisplayPort, pulsar `Bloq. Despl.`: para cambiar entre modo de video compuesto y VGA, por si acaso la BIOS ha arrancado en un modo que no corresponde a la conexión del monitor. + +[.text-center] +image:img/recovery.png[scaledwidth=70%] + +[start=12] +. Insertar en el ZXTRES la tarjeta SD con la primera partición en formato FAT16 o FAT32, y en la que habremos copiado el fichero `FLASH.ZX3` descargado anteriormente. + +. Si se está utilizando USB-Blaster, desconectar el cable. + +<<< + +[start=14] +. Elegir la opción `Upgrade Flash from SD`. Pulsar Enter, elegir `Yes`, y pulsar Enter de nuevo para comenzar el proceso que graba de nuevo la Flash. + +[.text-center] +image:img/recovery2.png[scaledwidth=70%] + +[WARNING] +==== +Este proceso sustituirá todos los cores instalados, la BIOS, así como las ROMs de ZX Spectrum y la configuración por lo que haya en la imagen, y no se puede deshacer. +==== + +[start=15] +. Tras unos minutos, el proceso finalizará, y podremos comprobar como, al apagar y encender, el ZXTRES vuelve a arrancar correctamente. + +[NOTE] +==== +Si no se obtiene imagen, y no se está utilizando DisplayPort, pulsar de nuevo `Bloq. Despl.` para cambiar entre modo de video compuesto y VGA. En este caso, sería necesario acceder a la BIOS y cambiar el <<#_advanced, ajuste avanzado correspondiente>> para indicar la configuración de nuestro monitor. +==== + +<<< + +== Referencias + +=== Scan Codes + +[.text-center] +image:img/scancodes.png[scaledwidth=80%] + +<<< + +=== Enlaces + +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://www.zxuno.com/wiki/index.php/ZX_Spectrum[Core ZX Spectrum] + +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://github.com/spark2k06/zxunops2/blob/master/Alternative/Nuevo%20firmware%20de%20teclado%20ZX-GO%2B.pdf[Firmware de teclado para ZX Go+] + +https://github.com/zxdos/zxdos-plus/tree/master/zxunops2[zxunops2] + +https://docs.google.com/spreadsheets/d/17-ifpHcy932_AP7SAv9uBLxg-2ZptcdgTvQ8ILXQLM4/htmlview[Almost (In-) Complete List of esxDOS DOT-Commands] + +https://www.va-de-retro.com/foros/viewtopic.php?t=1718&start=10#p25076[Cargando Leches 2.0] + +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://svn.zxuno.com/svn/zxuno/cores/spectrum_v2_spartan6/test19_multi_uart/[Core de ZX-Uno 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.zxuno.com/forum/viewtopic.php?f=52&t=4074&p=28234&hilit=kyp#p28234[Nuevo 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] diff --git a/doc/src/img/ZXTRESback.jpg b/doc/src/img/ZXTRESback.jpg new file mode 100644 index 0000000..560bace Binary files /dev/null and b/doc/src/img/ZXTRESback.jpg differ diff --git a/doc/src/img/ZXTRESbottom.jpg b/doc/src/img/ZXTRESbottom.jpg new file mode 100644 index 0000000..dc473ee Binary files /dev/null and b/doc/src/img/ZXTRESbottom.jpg differ diff --git a/doc/src/img/ZXTRESfront.jpg b/doc/src/img/ZXTRESfront.jpg new file mode 100644 index 0000000..98d4504 Binary files /dev/null and b/doc/src/img/ZXTRESfront.jpg differ diff --git a/doc/src/img/bios.png b/doc/src/img/bios.png index c7cc9d6..5e759bc 100644 Binary files a/doc/src/img/bios.png and b/doc/src/img/bios.png differ diff --git a/doc/src/img/bios2.png b/doc/src/img/bios2.png index 2a75c3d..c2f8dd6 100644 Binary files a/doc/src/img/bios2.png and b/doc/src/img/bios2.png differ diff --git a/doc/src/img/bios3_zxtres.png b/doc/src/img/bios3_zxtres.png new file mode 100644 index 0000000..11ca0bf Binary files /dev/null and b/doc/src/img/bios3_zxtres.png differ diff --git a/doc/src/img/bios4_zxtres.png b/doc/src/img/bios4_zxtres.png new file mode 100644 index 0000000..309345b Binary files /dev/null and b/doc/src/img/bios4_zxtres.png differ diff --git a/doc/src/img/bios5_zxtres.png b/doc/src/img/bios5_zxtres.png new file mode 100644 index 0000000..bfef3a2 Binary files /dev/null and b/doc/src/img/bios5_zxtres.png differ diff --git a/doc/src/img/bios6.png b/doc/src/img/bios6.png index c5c5085..82f55a0 100644 Binary files a/doc/src/img/bios6.png and b/doc/src/img/bios6.png differ diff --git a/doc/src/img/boot_zxtres.png b/doc/src/img/boot_zxtres.png new file mode 100644 index 0000000..0c5fffb Binary files /dev/null and b/doc/src/img/boot_zxtres.png differ diff --git a/doc/src/img/esxdos.png b/doc/src/img/esxdos.png index 9732756..3f2c5b8 100644 Binary files a/doc/src/img/esxdos.png and b/doc/src/img/esxdos.png differ diff --git a/doc/src/img/jtagzxtres.jpg b/doc/src/img/jtagzxtres.jpg new file mode 100644 index 0000000..5ec43e2 Binary files /dev/null and b/doc/src/img/jtagzxtres.jpg differ diff --git a/doc/src/img/keyboardAv.png b/doc/src/img/keyboardAv.png index f55c710..f046b6c 100644 Binary files a/doc/src/img/keyboardAv.png and b/doc/src/img/keyboardAv.png differ diff --git a/doc/src/img/keyboardEng.png b/doc/src/img/keyboardEng.png index ed437f5..371d5da 100644 Binary files a/doc/src/img/keyboardEng.png and b/doc/src/img/keyboardEng.png differ diff --git a/doc/src/img/keyboardEsp.png b/doc/src/img/keyboardEsp.png index e6f7a01..5655ef2 100644 Binary files a/doc/src/img/keyboardEsp.png and b/doc/src/img/keyboardEsp.png differ diff --git a/doc/src/img/portada_zxtres.jpg b/doc/src/img/portada_zxtres.jpg new file mode 100644 index 0000000..17f87f9 Binary files /dev/null and b/doc/src/img/portada_zxtres.jpg differ diff --git a/doc/src/img/powerConnector.png b/doc/src/img/powerConnector.png new file mode 100644 index 0000000..81cff8f Binary files /dev/null and b/doc/src/img/powerConnector.png differ diff --git a/doc/src/img/recovery.png b/doc/src/img/recovery.png index b974315..de3804f 100644 Binary files a/doc/src/img/recovery.png and b/doc/src/img/recovery.png differ diff --git a/doc/src/img/recovery2.png b/doc/src/img/recovery2.png index 5f3391b..ecbe310 100644 Binary files a/doc/src/img/recovery2.png and b/doc/src/img/recovery2.png differ diff --git a/doc/src/miniduino_en.adoc b/doc/src/miniduino_en.adoc index 5b795c7..2a440c2 100644 --- a/doc/src/miniduino_en.adoc +++ b/doc/src/miniduino_en.adoc @@ -5,10 +5,10 @@ Maxduino plays, in a very similar way to how https://es.wikipedia.org/wiki/Caset == Ports and buttons [.text-center] -image:img/MiniduinoBack.jpg[pdfwidth=50%] +image:img/MiniduinoBack.jpg[scaledwidth=50%] [.text-center] -image:img/MiniduinoFront.jpg[pdfwidth=50%] +image:img/MiniduinoFront.jpg[scaledwidth=50%] [cols=2*] |=== @@ -34,7 +34,7 @@ A SD is needed in order to store the tape files to play. Fast cards (Class 10 or The 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,ZXUNO+ 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 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. If you have a device that can use motor control, you can also use a cable with a 2.6 mm jack. @@ -52,7 +52,7 @@ The player shows file and directory entries in the order stored in the internal Once the SD card with the data files is inserted, it's turned on plugging in the included USB power cable. [.text-center] -image:img/MiniduinoLogo.jpg[pdfwidth=30%] +image:img/MiniduinoLogo.jpg[scaledwidth=30%] Pressing down the control button shows the options menu which can set the following: @@ -64,7 +64,7 @@ Pressing down the control button shows the options menu which can set the follow 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. [.text-center] -image:img/MiniduinoVersion.jpg[pdfwidth=30%] +image:img/MiniduinoVersion.jpg[scaledwidth=30%] When the player is stopped (file and directories browser): @@ -77,7 +77,7 @@ When the player is stopped (file and directories browser): Once a file is being played, stop playing it with the left button (Stop) or pause using the right button (Play/Pause). [.text-center] -image:img/MiniduinoPlay.jpg[pdfwidth=30%] +image:img/MiniduinoPlay.jpg[scaledwidth=30%] When in pause (tape block browser: @@ -234,7 +234,7 @@ If everything has been done correctly the Miniduino will restart and show on the [.text-center] -image:img/usbasp.jpg[pdfwidth=40%] +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. @@ -266,7 +266,7 @@ Check in the file `userconfig.h` that all logo entries are commented except for Connect the Miniduino device to the USBasp programmer, making sure that the connector is in the right position (i.e VCC with VCC, MOSI with MOSI, GND witch GND, etc.), and connect the USB adapter to the computer [.text-center] -image:img/usbasp_2.jpg[pdfwidth=50%] +image:img/usbasp_2.jpg[scaledwidth=50%] Set the following options in the "Tools" menu: diff --git a/doc/src/miniduino_es.adoc b/doc/src/miniduino_es.adoc index 9c2e151..85f166b 100644 --- a/doc/src/miniduino_es.adoc +++ b/doc/src/miniduino_es.adoc @@ -5,10 +5,10 @@ Maxduino permite la reproducción, de una forma similar a como se manejaban las == Puertos y Botones [.text-center] -image:img/MiniduinoBack.jpg[pdfwidth=50%] +image:img/MiniduinoBack.jpg[scaledwidth=50%] [.text-center] -image:img/MiniduinoFront.jpg[pdfwidth=50%] +image:img/MiniduinoFront.jpg[scaledwidth=50%] [cols=2*] |=== @@ -34,7 +34,7 @@ Se necesita una tarjeta SD para almacenar los archivos de cinta que se quiere re La tarjeta debe estar formateada con con la primera partición en formato FAT16 o FAT32. -Además de la tarjeta, recordar utilizar un cable adecuado para la <<#_puertos_y_conectores,entrada de sonido del ZXUNO+>>, conectando el Miniduino. +Además de la tarjeta, recordar utilizar un cable adecuado para la <<#_puertos_y_conectores,entrada de sonido>>, conectando el Miniduino. Para los equipos que soporten control por motor, también se puede utilizar un cable con un jack de 2,6 mm. @@ -52,7 +52,7 @@ El reproductor muestra las entradas de archivos y directorios en el orden de la Una vez insertada la tarjeta SD con ficheros de datos, el Miniduino se enciende conectando el cable de alimentación USB incluido. [.text-center] -image:img/MiniduinoLogo.jpg[pdfwidth=30%] +image:img/MiniduinoLogo.jpg[scaledwidth=30%] Si se pulsa directamente el botón de control, se accede al menú de opciones que permite modificar lo siguiente: @@ -64,7 +64,7 @@ Si se pulsa directamente el botón de control, se accede al menú de opciones qu Estando fuera del menú de opciones, el botón de control se utiliza como una palanca de control de cuatro direcciones, que se comporta de dos maneras distintas, según esté la reproducción detenida (Stop) o en pausa (Pause). [.text-center] -image:img/MiniduinoVersion.jpg[pdfwidth=30%] +image:img/MiniduinoVersion.jpg[scaledwidth=30%] Con la reproducción detenida (navegación por archivos y directorios): @@ -77,7 +77,7 @@ Con la reproducción detenida (navegación por archivos y directorios): Una vez un archivo está en reproducción, el botón izquierda (Stop), la detiene, y el botón derecho (Play/Pause) la pone en pausa. [.text-center] -image:img/MiniduinoPlay.jpg[pdfwidth=30%] +image:img/MiniduinoPlay.jpg[scaledwidth=30%] Con la reproducción en pausa (navegación por bloques de cinta): @@ -238,7 +238,7 @@ Si todo se ha hecho correctamente se verá cómo el Miniduino se reinicia y en l - Programador USBASP [.text-center] -image:img/usbasp.jpg[pdfwidth=40%] +image:img/usbasp.jpg[scaledwidth=40%] Además, la instalación, se ha de hacer desde un ordenador (Windows, Mac, Linux) con el entorno https://www.arduino.cc/en/software[Arduino IDE]. @@ -269,7 +269,7 @@ Verificar en el fichero `userconfig.h` que estén comentadas todas las entradas Conectar el Miniduino al adaptador USBasp, asegurándose de que la serigrafía de los dos conectores se corresponde (ej: VCC con VCC, MOSI con MOSI, GND con GND, etc.), y conectar el adaptador USB al equipo. [.text-center] -image:img/usbasp_2.jpg[pdfwidth=50%] +image:img/usbasp_2.jpg[scaledwidth=50%] Configurar en el menú "Herramientas" las opciones