SpecNext Wiki - User contributions [en-gb]

Mouse

2020-12-21T12:11:19Z

Daz: typo

The Spectrum Next has a PS/2 port for connecting a PS/2 keyboard or mouse (or both via a splitter).

'''WARNING: Do not plug in or remove PS/2 devices with the power on.'''

A USB mouse plugged in via a USB-to-PS/2 converter will only work if the mouse itself supports the PS/2 protocol.

=== PS/2 Port and modes of operation ===

The "ps2" setting in the /machines/next/config.ini file determines the PS/2 port mode:

'''PS2=0''' is KEYBOARD mode where a PS/2 keyboard is plugged into the Next, or with a splitter you can use both a mouse and a keyboard.

'''PS2=1''' is MOUSE mode where the mouse should be plugged in directly. Do not use a splitter in this mode as it can have funny effects.

You can use the "ps2mode" dot command to see which mode is active. The best place to set the value is in the tbblue .ini file, but if you start in the wrong mode then on the Next (or a membrane) keyboard you can type ps2mode -m to select MOUSE or ps2mode -k to select KEYBOARD.

=== Driver ===
The NextZXOS distribution includes a mouse driver from version 1.95 onwards.

All you need is the file MOUSE.DRV in the NextZXOS folder. The mouse can then be used from BASIC with the new DRIVER command.

This mouse driver is driver number 126. There will be a supported list of driver codes and any that use streams (this does not) will need to be allocated one from 65-90/A-Z or the lower case range (or both) so this avoids that area.

The driver is stopped and started with the 'install' and 'uninstall' DOT commands in the BIN directory:

<pre>.install /nextos/mouse.drv
</pre>

=== Sample BASIC programs ===

There is a demo program called NXMOUSE.BAS that uses Sprite and Text features for you to play with (in the /demos/mouse folder). The NXMOUSET.BAS program uses some of the features of the sprite cursor and lets you play with acceleration settings in Timex HiRes mode.

They both use sprites from the BREAKOUT test but, you can change line 300 to load any set you wish. Note that if you
hold the 's' button and move it around at times the sprite cursor will seem to disappear - that is because you have reached the maximum 12 sprites per display line.

You could modify the code to remove the tail of previously used sprites if you want but, it is quite fun to play with.

=== Mouse Driver API ===

DRIVER supports the following parameters:

<pre>DRIVER 126,1 TO %b,x,y
</pre>

This will get the current location of the mouse on a 192 x 640 grid with 0,0 in the top left of the outer border where sprites can go. It uses the higher X number to allow use in Timex mode where there are twice as many horizontal pixels.

<pre>%b@111</pre> will be the three buttons bit activated in combination so 1,2,4 or 3,5,6,7 for combinations.
<pre>%b>>4</pre> will be the current value of the wheel mouse from 0 to 15.

<pre>DRIVER 126,2{,sprite{,pattern}}
</pre>

The optional sprite number 0-63 and pattern number 0-63 will default to 0. This will cause that sprite to always be displayed (anywhere that clipping is not in effect) at the current X,Y coordinate - over a Timex screen it will sit between two pixels of course.

<pre>DRIVER 126,3
</pre>
Will disable the sprite cursor.

<pre>DRIVER 126,4{,attribute}
</pre>
will display an attribute based character cursor using the ULA attributes - this will cope with some screen changes but, not scrolling so remember to disable it when changing the screen wholesale.

So using the new features of NextOS to include a binary number (@) in an integer statement (%)

<pre>DRIVER 126,4,%@11100111
</pre>
Will set a Bright, Flashing, Green and White cursor. The first two 1's are Bright and Flash the next two groups of three are the paper and ink:

<pre>FTGRBGRB</pre> - where T=Bright.

<pre>DRIVER 126,5</pre>

will remove the Attribute based cursor.

<pre>DRIVER 126,6,x_threshold
</pre>
Where x_threshold is forced to be in the range 0-255 by using LSB only:

* 0 Means always accelerate the X direction
* 255 Means never accelerate the X direction

By default x_threshold is set at 32 which will trigger more rapid movement if you move the mouse quickly. You can adjust to suit your own preference.

The Y does not have the option as 0-192 pixels probably would not benefit but, it is not ruled out and you have the source to hack...

---

Based on the distribution readme by Tim Gilberts.

File Formats

2020-08-29T12:53:39Z

Daz: Added note on tzx files

NextZXOS can directly read and load these kind of files: bas, tap, z80, sna, snx, dot, o, p. Many other file types are supported by the use of external dot commands.

* '''[https://www.worldofspectrum.org/faq/reference/z80format.htm .z80]''' is a Spectrum snapshot file, more suitable as emulator compatibility than a real format. Files can be loaded using the NextZXOS browser, the NextZXOS SPECTRUM keyword, the esxDOS NMI menu, and the exDOS .snapload command.
* '''[https://faqwiki.zxnet.co.uk/wiki/SNA_format .sna]''' is a Spectrum snapshot file, more suitable as emulator compatibility than a real format. Both 48K and 128K SNA files are supported. Files can be loaded using the NextZXOS browser, the NextZXOS SPECTRUM keyword, the esxDOS NMI menu, and the exDOS .snapload command. When loading in NextZXOS, any private data appended to the file is ignored during loading, and the program code may later read it by reopening itself using a hardcoded filename. If private data is appended to them then they cannot be loaded by esxDOS. Also the NextZXOS will reconfigure the machine based on the type of the SNA file, for example the {{PortNo|$7FFD}} memory banking is locked when 48K SNA file is loaded, etc.. (all of this can be reconfigured through Next registers to unlock/enable all features back, but the initial state is designed to provide maximum compatibility with legacy/original SW)
* '''.snx''' is a Spectrum snapshot file, more suitable as emulator compatibility than a real format. It is identical to a 128K .sna file, but when loaded using the browser or the SPECTRUM command, NextZXOS leaves file handle 0 open for further use by the program. The program is expected close the handle before exiting. .snx files may also have private data appended to them. They are not supported by esxDOS.
* '''.o''' is a ZX80 snapshot
* '''.p''' is a ZX81 snapshot
* '''[[NEX file format|.nex]]''' is good for a program that takes over the machine. With some care, it can also be used to load a program without overwriting sysvars, allowing NextZXOS API calls to be used. It can be loaded using the NextZXOS file browser and the .nexload dot command. The [[Emulators|CSpect]] emulator can open .nex files natively from the F2 dialog. esxDOS cannot open .nex files.
* '''.dot''' is good for dot commands and programs that can coexist with BASIC/NextZXOS and can return to BASIC safely (i.e. counterpart to nex)
* '''[[TAP file format|.tap]]''' is a simple container format that can hold many files, is compatible with emulators and supported by many tools. When loading .tap files using the NextZXOS browser, a menu is displayed asking whether you want to load in standard, USR0 or 48K mode.
* '''.bas''' is the native SD-card format for BASIC programs (first 128 bytes of the file form standard +3DOS header).
* .'''scr''' is used for a standard Spectrum screenshot created with ''SAVE "picture.scr" SCREEN$'' (256x192, 15 colours per character cell). Note that if saved from BASIC, .scr files will have a 128 byte +3DOS header (7,040 bytes), but .scr files created in external PC tools may not have a +3DOS header (6,912 bytes). The NextZXOS browser and the BASIC ''LOAD'' statement can cope with both headered and headerless .scr files.
* '''.shc''' is used for a screenshot in Timex 8x1 Hi-colour mode (256x192, 15 colors).
* '''.shr''' is used for a screenshot in Timex Hi-res mode (512x192, mono).
* '''.slr''' is used for a lo-res screenshot (128x96, 256 colours).
* '''.sl2''' is used for a Layer 2 screenshot (256x192, 256 colour) (when stored by NextBASIC, the binary content of file is: regular 128 bytes +3DOS header, then 256*192 bytes with pixel data, NO palette data = in total 49280 bytes).
* '''.pal''' is a 9-bit palette format (256 pairs of bytes in %RRRGGGBB, %P000000B format). Files can be loaded and saved from the Screenshots menu in NextZXOS after pressing the M1 button or F9. The P bit sets priority when used in layer 2 palettes. Palette entries with P=1 cause their pixels to appear above everything else, regardless of globally-set layer priorities.
* '''.npl''' is a 9-bit palette format. The first 512 bytes are identical to a .pal file. The 513th byte designates transparency - for sprite palettes, the transparency byte is a real index, and for other palettes it is a colour mask. .npl files can be created, saved and loaded by [[Miscellaneous#WASPtools|WASPtools]].
* '''.nxi''' is layer 2 screen format, with optional palette. If the file size is 49,152 bytes, the file contains 256x192 pixels of layer 2 data, indexed with palette values. This is essentially a memory dump of the six sequential layer 2 MMU banks. If the size is 49,664 bytes, the pixel data is prepended with 512 bytes of palette data (256 pairs of bytes in %RRRGGGBB, %P000000B format). .nxi files can be processed by PLOTIT, Dnext, [https://github.com/stefanbylund/zxnext_bmp_tools zxnext_bmp_tools] and Jim Bagley's tools.

The most notable of the other file formats is tzx. Although the browser recognises tzx files, they can only be loaded if you have a Raspberry Pi installed in your Next. See the [[FAQ]] for details.

ESXDOS

2019-09-10T21:12:38Z

Daz: Folder case

= esxDOS =

esxDOS is one of the operating systems that can be run on the Next. It provides a POSIX-like API to access the SD card as disk and it provides a familiar interface to the disk from BASIC. esxDOS from version 0.8.6 supports the Real Time Clock of the Next; a new version 0.9.x is being written with features like Long File Name (LFN) support. esxDOS currently only supports the so-called USR0 mode in BASIC (single keyword/48K Basic) - there is an experimental .128 command to allow the editor to be started.

You do not need to install esxDOS if you just want to run software designed for it as NextZXOS implements the esxDOS Application Programming Interface (API) so programs will work anyway. This includes running "dot commands". You can copy your dot command files to the /DOT folder of the SD card. Note that NextZXOS already includes several dot commands that are newer than the ones included with esxDOS, so you may want to use these. Many of these work on
both systems. For esxDOS compliant versions, use the ones located under c:/dot/extra.

If you want to use its other features like BetaDisk support or just want to see what it is like you will need to follow the instructions to install it as another identity on the Next.

Instructions to Install esxDos on the Next

1. Download the esxDOS distribution (minimum version 0.8.6) from www.esxdos.org

2. Within NextZXOS, create two folders on the root of your SD card, named "bin" and "sys" by giving:

mkdir "c:/BIN"
mkdir "c:/SYS"
mkdir "c:/TMP"

3. Using a PC, unzip the contents of esxdos.zip then rename esxmmc.bin as esxmmc.rom

4. Copy the .bin file into /tbblue/ on the SD card

5. Copy the contents of the "BIN" and "SYS" folders in the esxDOS distribution into their respective places on the SD card.

6. [todo --- modify the /tbblue/config.ini file ?]

ESXDOS

2019-09-10T16:02:02Z

Daz: Added esxDOS install steps but need someone with a dev board to verify them

= esxDos =

esxDOS is one of the operating systems that can be run on the Next. It provides a POSIX-like API to access the SD card as disk and it provides a familiar interface to the disk from BASIC. The current version of esxDOS is 0.8.6 - which supports the Real Time Clock of the Next; a new version 0.9.x is being written with features like Long File Name (LFN) support. esxDOS currently only supports the so-called USR0 mode in BASIC (single keyword/48K Basic) - there is an experimental .128 command to allow the editor to be started.

You do not need to install esxDOS if you just want to run software designed for it as NextZXOS implements the esxDOS Application Programming Interface (API) so programs will work anyway. This includes running "dot commands". You can copy your dot command files to the /DOT folder of the SD card. Note that NextZXOS already includes several dot commands that are newer than the ones included with esxDOS, so you may want to use these. Many of these work on
both systems. For esxDOS compliant versions, use the ones located under c:/dot/extra.

If you want to use its other features like BetaDisk support or just want to see what it is like you will need to follow the instructions to install it as another identity on the Next.

Instructions to Install esxDos on the Next

1. Download the esxDOS distribution (minimum version 0.8.6) from www.esxdos.org

2. Within NextZXOS, create two folders on the root of your SD card, named "bin" and "sys" by giving:

mkdir "c:/bin"
mkdir "c:/sys"

3. Using a PC, unzip the contents of esxdos.zip then rename esxmmc.bin as esxmmc.rom

4. Copy the .bin file into /tbblue/ on the SD card

5. Copy the contents of the "bin" and "sys" folders in the esxDOS distribution into their respective places on the SD card.

6. [todo --- modify the /tbblue/config.ini file ?]

ESXDOS

2019-07-30T14:04:51Z

Daz: Expanded info on dot commands

GPIO Socket (J15)

2019-07-04T13:11:07Z

Daz: FPGA page link

The GPIO socket, marked J15 on the circuit board, allows access to several different power and data lines:

* I2C serial protocol
* UART
* Spare pins on the [[FPGA]]
* 5v, 3.3v and GND

The UART is also used for the [[ESP8266-01|ESP Wi-fi module]], and can't be used from the GPIO without removing the ESP module. I2C is also used to communicate with the [[RTC|real time clock]] module.

The GPIO is not populated and requires a socket to be installed (2 x 10 IDC 2.54mm spc. Male Pin Header). Pull up/down resistors may be required for some pins to limit current.

[[Image:NEXT GPIO location.jpg|thumb|J15 position on circuit board]]
[[Image:NEXT_GPIO.png|thumb|GPIO pinout image]]

In June 2019 it was announced that pins 4 and 17 of J15 would be used for two additional keyboard connections on full cased Nexts. Final specs have not yet been finalised.

GPIO Socket (J15)

2019-07-04T12:59:34Z

Daz: Added links

The GPIO socket, marked J15 on the circuit board, allows access to several different power and data lines:

* I2C serial protocol
* UART
* Spare pins on the FPGA
* 5v, 3.3v and GND

The UART is also used for the [[ESP8266-01|ESP Wi-fi module]], and can't be used from the GPIO without removing the ESP module. I2C is also used to communicate with the [[RTC|real time clock]] module.

The GPIO is not populated and requires a socket to be installed (2 x 10 IDC 2.54mm spc. Male Pin Header). Pull up/down resistors may be required for some pins to limit current.

[[Image:NEXT GPIO location.jpg|thumb|J15 position on circuit board]]
[[Image:NEXT_GPIO.png|thumb|GPIO pinout image]]

In June 2019 it was announced that pins 4 and 17 of J15 would be used for two additional keyboard connections on full cased Nexts. Final specs have not yet been finalised.

GPIO Socket (J15)

2019-06-24T20:39:50Z

Daz: Keyboard pins heads-up

The GPIO socket, marked J15 on the circuit board, allows access to several different power and data lines:

* I2C serial protocol
* UART
* Spare pins on the FPGA
* 5v, 3.3v and GND

The UART is also used for the ESP Wi-fi module, and can't be used from the GPIO without removing the ESP module. I2C is also used to communicate with the real time clock module.

The GPIO is not populated and requires a socket to be installed (2 x 10 IDC 2.54mm spc. Male Pin Header). Pull up/down resisters may be required for some pins to limit current.

[[Image:NEXT GPIO location.jpg|thumb|J15 position on circuit board]]
[[Image:NEXT_GPIO.png|thumb|GPIO pinout image]]

In June 2019 it was announced that two pins of J15 would be used for two additional keyboard connections on full cased Nexts. Final specs have not yet been finalised.

Beeper (hardware)

2019-06-21T12:45:40Z

Daz: Grammar

The Spectrum Next can create sound using [[Turbo Sound Next]] (3 AY-3-8912 sound chips) controlled by the BASIC PLAY keyword and the signal from these goes to the HDMI port or the 'ear' socket. Additionally an internal speaker can be connected which will generate sound in the same manner as the original 48k Spectrum, controlled via the BEEP keyword, which will also output via HDMI/ear.

A speaker attaches to connector J3 on the circuit board and requires a 2.54mm Pitch, 4 Way, 1 Row through-hole pin header. If you're fitting the board inside an original rubber key case, you'll probably need a right-angled connector due to the height required.

The buzzer should be approximately 1 inch diameter with impedance of 16 ohm (which should equate to a basic 'PC BIOS' piezo type speaker). J3 pins 1 and 2 are negative, pins 3 and 4 are positive.

The internal speaker can be disabled from the TBBlue boot ROM options menu.

Beeper (hardware)

2019-06-21T12:44:26Z

Daz: Initial version - all the info I could scrape up from the forums/FB

The Spectrum Next can create sound using [[Turbo Sound Next]] (3 AY-3-8912 sound chips) controlled by the BASIC PLAY keyword and the signal from these goes to the HDMI port or the 'ear' socket. Additionally an internal speaker can be connected which will generate sound in the same manner as the original 48k Spectrum, controlled via the BEEP keyword, which will also output via HDMI/ear.

A speaker attaches to connector J3 on the circuit board and requires a 2.54mm Pitch, 4 Way, 1 Row through-hole pin header. If you're fitting the board inside an original rubber key case, you'll probably need a right-angled connector due to the height of the connector.

The buzzer should be approximately 1 inch diameter with impedance of 16 ohm (which should equate to a basic 'PC BIOS' piezo type speaker). J3 pins 1 and 2 are negative, pins 3 and 4 are positive.

The internal speaker can be disabled from the TBBlue boot ROM options menu.

GPIO Socket (J15)

2019-06-20T15:24:48Z

Daz: Added J15 header info

The GPIO socket, marked J15 on the circuit board, allows access to several different power and data lines:

* I2C serial protocol
* UART
* Spare pins on the FPGA
* 5v, 3.3v and GND

The UART is also used for the ESP Wi-fi module, and can't be used from the GPIO without removing the ESP module. I2C is also used to communicate with the real time clock module.

The GPIO is not populated and requires a socket to be installed (2 x 10 IDC 2.54mm spc. Male Pin Header). Pull up/down resisters may be required for some pins to limit current.

[[Image:NEXT GPIO location.jpg|thumb|J15 position on circuit board]]
[[Image:NEXT_GPIO.png|thumb|GPIO pinout image]]

Main Page

2019-06-20T15:00:06Z

Daz:

== References ==

=== System architecture ===
* [[Extended Z80 instruction set]]
* [[Memory map]] and switching mechanics
* [[Reference machines]] and timing
* [[Boot Sequence]]
* [[Board feature control]] and port list
* [[Interrupts]]
* [[RPi0 Acceleration]]
* [[DMA|zxnDMA]]
* [[Copper]]
* [[File Formats]]
* [[Z80 programming]]

=== Video ===
* [[Video Modes]]
* [[Tilemap]]
* [[Sprites]]
* [[Layer 2]]
* [[Palettes]]
* [[Blend Modes]]

=== Audio ===
* [[Turbo Sound Next]]
* [[SpecDrum/DAC]]
* [[Beeper (audio) | Beeper]]

=== Firmware ===
* [https://gitlab.com/thesmog358/tbblue TBBlue Official Distribution git repository]
* [[NextZXOS]]
* [[ESXDOS]]
* [[NextBASIC]]
* [[System Variables]]

=== Electronics ===
* [[Circuit Diagrams]]

=== Development Tools ===
* [[Emulators]]
* [[Assemblers]]
* [[Compilers]]
* [[Miscellaneous]]

=== Hardware Expansion ===

Your next computer can be expanded internally to add additional functionality.
* [[RTC | RTC - Real Time Clock]]
* [[Raspberry Pi Zero | Accelerator - Raspberry Pi Zero]]
* [[ESP8266-01 | ESP8266-01 - Wifi Module]]
* [[Expansion | Expansion Slot]]
* [[GPIO Socket (J15)]]
* [[JTAG Socket]]
* [[2MB RAM Expansion]]
* [[Beeper (hardware) | Beeper]]
* ''[https://www.specnext.com/forum/viewtopic.php?f=6&t=544 Specnext Forums]
: A link to the forums discussing hardware additions

=== Peripherals ===

* [[Mouse]]

= Community =

* [https://www.specnext.com/forum/ Official forums]
* [https://www.facebook.com/groups/specnext Facebook group]
* [https://specnext.slack.com/ Slack chat] ([https://join.slack.com/t/specnext/shared_invite/enQtMjQ2ODgzNTI5MzAzLWE2NzhhNjUzZGZhNWIxZWIyMTY4N2JmNTY3MWM4ZTkxOWY2M2UwZDQzN2FhYTEzNjFiY2I5MDA1MTc3NjVmYTI sign up])

= Sources =
* [[Bibliography]]

= Wiki "to do" list =
* [[Wiki TODO list]] (can be used also as warning which pages may contain outdated information)

Mouse

2019-06-20T14:59:18Z

Daz: Initial version based on Tim Gilberts "MOUSEreadme.txt"

The Spectrum Next has a PS/2 port for connecting a PS/2 keyboard or mouse (or both via a splitter).

'''WARNING: Do not plug in or remove PS/2 devices with the power on.'''

A USB mouse plugged in via a USB-to-PS/2 converter will only work if the mouse itself supports the PS/2 protocol.

=== PS/2 Port and modes of operation ===

The "ps2" setting in the /tbblue/config.ini file determines how the PS/2 port mode:

'''PS2=0''' is KEYBOARD mode where a PS/2 keyboard is plugged into the Next, or with a splitter you can use both a mouse and a keyboard.

'''PS2=1''' is MOUSE mode where the mouse should be plugged in directly. Do not use a splitter in this mode as it can have funny effects.

You can use the "ps2mode" dot command to see which mode is active. The best place to set the value is in the tbblue .ini file, but if you start in the wrong mode then on the Next (or a membrane) keyboard you can type ps2mode -m to select MOUSE or ps2mode -k to select KEYBOARD.

=== Driver ===
The NextZXOS distribution includes a mouse driver from version 1.95 onwards.

All you need is the file MOUSE.DRV in the NextZXOS folder. The mouse can then be used from BASIC with the new DRIVER command.

This mouse driver is driver number 126. There will be a supported list of driver codes and any that use streams (this does not) will need to be allocated one from 65-90/A-Z or the lower case range (or both) so this avoids that area.

The driver is stopped and started with the 'install' and 'uninstall' DOT commands in the BIN directory:

<pre>.install /nextos/mouse.drv
</pre>

=== Sample BASIC programs ===

There is a demo program called NXMOUSE.BAS that uses Sprite and Text features for you to play with (in the /demos/mouse folder). The NXMOUSET.BAS program uses some of the features of the sprite cursor and lets you play with acceleration settings in Timex HiRes mode.

They both use sprites from the BREAKOUT test but, you can change line 300 to load any set you wish. Note that if you
hold the 's' button and move it around at times the sprite cursor will seem to disappear - that is because you have reached the maximum 12 sprites per display line.

You could modify the code to remove the tail of previously used sprites if you want but, it is quite fun to play with.

=== Mouse Driver API ===

DRIVER supports the following parameters:

<pre>DRIVER 126,1 TO %b,x,y
</pre>

This will get the current location of the mouse on a 192 x 640 grid with 0,0 in the top left of the outer border where sprites can go. It uses the higher X number to allow use in Timex mode where there are twice as many horizontal pixels.

<pre>%b@111</pre> will be the three buttons bit activated in combination so 1,2,4 or 3,5,6,7 for combinations.
<pre>%b>>4</pre> will be the current value of the wheel mouse from 0 to 15.

<pre>DRIVER 126,2{,sprite{,pattern}}
</pre>

The optional sprite number 0-63 and pattern number 0-63 will default to 0. This will cause that sprite to always be displayed (anywhere that clipping is not in effect) at the current X,Y coordinate - over a Timex screen it will sit between two pixels of course.

<pre>DRIVER 126,3
</pre>
Will disable the sprite cursor.

<pre>DRIVER 126,4{,attribute}
</pre>
will display an attribute based character cursor using the ULA attributes - this will cope with some screen changes but, not scrolling so remember to disable it when changing the screen wholesale.

So using the new features of NextOS to include a binary number (@) in an integer statement (%)

<pre>DRIVER 126,4,%@11100111
</pre>
Will set a Bright, Flashing, Green and White cursor. The first two 1's are Bright and Flash the next two groups of three are the paper and ink:

<pre>FTGRBGRB</pre> - where T=Bright.

<pre>DRIVER 126,5</pre>

will remove the Attribute based cursor.

<pre>DRIVER 126,6,x_threshold
</pre>
Where x_threshold is forced to be in the range 0-255 by using LSB only:

* 0 Means always accelerate the X direction
* 255 Means never accelerate the X direction

By default x_threshold is set at 32 which will trigger more rapid movement if you move the mouse quickly. You can adjust to suit your own preference.

The Y does not have the option as 0-192 pixels probably would not benefit but, it is not ruled out and you have the source to hack...

---

Based on the distribution readme by Tim Gilberts.

DMA

2019-06-20T11:21:25Z

Daz: Fix heading levels

== Overview ==
The ZX Spectrum Next DMA (zxnDMA) is a single channel DMA device that implements a subset of the Z80 DMA functionality. The subset is large enough to be compatible with common uses of the similar Datagear interface available for standard ZX Spectrum computers and compatibles. It also adds a burst mode capability that can deliver audio at programmable sample rates to the DAC device.

== Accessing the zxnDMA ==
The zxnDMA is mapped to a single Read/Write IO Port 0x6B which is the same one used by the Datagear but unlike the Datagear it doesn't also map itself to a second port 0x0B similar to the MB-02 interface.

<code>PORT 0x6b: zxnDMA</code>

== Description ==
The normal Z80 DMA (Z8410) chip is a pipelined device and because of that it has numerous off-by-one idiosyncrasies and requirements on the order that certain commands should be carried out. These issues are not duplicated in the zxnDMA. You can continue to program the zxnDMA as if it is were a Z8410 DMA device but it can also be programmed in a simpler manner.

The single channel of the zxnDMA chip consists of two ports named A and B. Transfers can occur in either direction between ports A and B, each port can describe a target in memory or IO, and each can be configured to autoincrement, autodecrement or stay fixed after a byte is transferred.

A special feature of the zxnDMA can force each byte transfer to take a fixed amount of time so that the zxnDMA can be used to deliver sampled audio.

== Modes of Operation ==
The zxnDMA can operate in a z80-DMA compatibility mode.

The z80-DMA compatibility mode is selected by setting bit 6 of nextreg 0x06. In this mode, all transfers involve length+1 bytes which is the same behaviour as the z80-DMA chip. In zxn-DMA mode, the transfer length is exactly the number of bytes programmed. This mode is mainly present to accommodate existing spectrum software that uses the z80-DMA and for cp/m programs that may have a z80-DMA option.

The zxnDMA can also operate in either burst or continuous modes.

Continuous mode means the DMA chip runs to completion without allowing the CPU to run. When the CPU starts the DMA, the DMA operation will complete before the CPU executes its next instruction.

Burst mode nominally means the DMA lets the CPU run if either port is not ready. This condition can't happen in the zxnDMA chip except when operated in the special fixed time transfer mode. In this mode, the zxnDMA will let the CPU run while it waits for the fixed time to expire between bytes transferred.

Note that there is no byte transfer mode as in the Z80 DMA.

== Programming the zxnDMA ==
Like the Z80 DMA chip, the zxnDMA has seven write registers named WR0-WR6 that control the device. Each register WR0-WR6 can have zero or more parameters associated with it.

In a first write to the zxnDMA port, the write value is compared against a bitmask to determine which of the WR0-WR6 is the target. Remaining bits in the written value can contain data as well as a list of associated parameter bits. The parameter bits determine if further writes are expected to deliver parameter values. If there are multiple parameter bits set, the expected order of parameter values written is determined by parameter bit position from right to left (bit 0 through bit 7). Once all parameters are written, the zxnDMA again expects a regular register write selecting WR0-WR6.

The table below describes the registers and the bitmask required to select them on the zxnDMA.

{|
! Register Group
! Register Function Description
! Bitmask
! Notes
|-
| WR0
| Direction, Operation and Port A configuration
| <pre>0XXXXXAA</pre>
| AA must NOT be 00
|-
| WR1
| Port A configuration
| <pre>0XXXX100</pre>
|
|-
| WR2
| Port B configuration
| <pre>0XXXX000</pre>
|
|-
| WR3
| Activation
| <pre>1XXXXX00</pre>
| It’s best to use WR6
|-
| WR4
| Port B, Timing and Interrupt configuration
| <pre>1XXXXX01</pre>
|
|-
| WR5
| Ready and Stop configuration
| <pre>10XXX010</pre>
|
|-
| WR6
| Command Register
| <pre>1XXXXX11</pre>
|
|}

== zxnDMA Registers ==
These are described below following the same convention used by Zilog for its DMA chip:

=== WR0 – Write Register Group 0 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | | | |
| | | | | 0 0 Do not use
| | | | | 0 1 Transfer (Prefer this for Z80 DMA compatibility)
| | | | | 1 0 Do not use (Behaves like Transfer, Search on Z80 DMA)
| | | | |
| | | | | 1 1 Do not use (Behaves like Transfer, Search/Transfer on Z80 DMA)
| | | | |
| | | | 0 = Port B -> Port A (Byte transfer direction)
| | | | 1 = Port A -> Port B
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (LOW BYTE)
| | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (HIGH BYTE)
| V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (LOW BYTE)
V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (HIGH BYTE)</pre>

Several registers are accessible from WR0. The first write to WR0 is to the base register byte. Bits D6:D3 are optionally set to indicate that associated registers in this group will be written next. The order the writes come in are from D3 to D6 (right to left). For example, if bits D6 and D3 are set, the next two writes will be directed to PORT A STARTING ADDRESS LOW followed by BLOCK LENGTH HIGH.

=== WR1 – Write Register Group 1 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 1 0 0
| | | |
| | | 0 = Port A is memory
| | | 1 = Port A is IO
| | |
| 0 0 = Port A address decrements
| 0 1 = Port A address increments
| 1 0 = Port A address is fixed
| 1 1 = Port A address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A VARIABLE TIMING BYTE
0 0 0 0 0 0 | |
0 0 = Cycle Length = 4
0 1 = Cycle Length = 3
1 0 = Cycle Length = 2
1 1 = Do not use
</pre>

The cycle length is the number of cycles used in a read or write operation. The first cycle asserts signals and the last cycle releases them. There is no half cycle timing for the control signals.

=== WR2 – Write Register Group 2 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 0 0 0
| | | |
| | | 0 = Port B is memory
| | | 1 = Port B is IO
| | |
| 0 0 = Port B address decrements
| 0 1 = Port B address increments
| 1 0 = Port B address is fixed
| 1 1 = Port B address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B VARIABLE TIMING BYTE
0 0 | 0 0 0 | |
| 0 0 = Cycle Length = 4
| 0 1 = Cycle Length = 3
| 1 0 = Cycle Length = 2
| 1 1 = Do not use
|
V
D7 D6 D5 D4 D3 D2 D1 D0 ZXN PRESCALAR (FIXED TIME TRANSFER)
</pre>
The ZXN PRESCALAR is a feature of the zxnDMA implementation. If non-zero, a delay will be inserted after each byte is transferred such that the total time needed for each transfer is determined by the prescalar. This works in both the continuous mode and the burst mode. If the DMA is operated in burst mode, the DMA will give up any waiting time to the CPU so that the CPU can run while the DMA is idle.

The rate of transfer is given by the formula “Frate = 875kHz / prescalar” or, rearranged, “prescalar = 875kHz / Frate”. The formula is framed in terms of a sample rate (Frate) but Frate can be inverted to set a transfer time for each byte instead. The 875kHz constant is a nominal value assuming a 28MHz system clock; the system clock actually varies from this depending on the video timing selected by the user (HDMI, VGA0-6) so for complete accuracy the constant should be prorated according to documentation for nextreg 0x11.

In a DMA audio setting, selecting a sample rate of 16kHz would mean setting the prescalar value to 55. This sample period is constant across changes in CPU speed.

=== WR3 – Write Register Group 3 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | 0 0 0 0 0 0
|
1 = DMA Enable
</pre>
The Z80 DMA defines more fields but they are ignored by the zxnDMA. The two other registers defined by the Z80 DMA in this group on D4 and D3 are implemented by the zxnDMA but they do nothing.

It is preferred to start the DMA by writing an 'Enable DMA' command to WR6.

=== WR4 – Write Register Group 4 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | | 0 | | 0 1
| | | |
0 0 = Do not use (Behaves like Continuous mode, Byte mode on Z80 DMA)
0 1 = Continuous mode
1 0 = Burst mode
1 1 = Do not use
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (LOW BYTE)
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (HIGH BYTE)
</pre>
The Z80 DMA defines three more registers in this group through D4 that define interrupt behaviour. Interrups and pulse generation are not implemented in the zxnDMA nor are these registers available for writing.

=== WR5 – Write Register Group 5 ===
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 0 | | 0 0 1 0
| |
| 0 = /ce only
| 1 = /ce & /wait multiplexed
|
0 = Stop on end of block
1 = Auto restart on end of block
</pre>
The /ce & /wait mode is implemented in the zxnDMA but is not currently used. This mode has an external device using the DMA's /ce pin to insert wait states during the DMA's transfer.

The auto restart feature causes the DMA to automatically reload its source and destination addresses and reset its byte counter to zero to repeat the last transfer when a previous one is finished.

=== WR6 – Command Register ===
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 ? ? ? ? ? 1 1
| | | | |
1 0 0 0 0 = 0xC3 = Reset
1 0 0 0 1 = 0xC7 = Reset Port A Timing
1 0 0 1 0 = 0xCB = Reset Port B Timing
0 1 1 1 1 = 0xBF = Read Status Byte
0 0 0 1 0 = 0x8B = Reinitialize Status Byte
0 1 0 0 1 = 0xA7 = Initialize Read Sequence
1 0 0 1 1 = 0xCF = Load
1 0 1 0 0 = 0xD3 = Continue
0 0 0 0 1 = 0x87 = Enable DMA
0 0 0 0 0 = 0x83 = Disable DMA
+-- 0 1 1 1 0 = 0xBB = Read Mask Follows
|
D7 D6 D5 D4 D3 D2 D1 D0 READ MASK
0 | | | | | | |
| | | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Status Byte
| | | | | |
| | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter Low
| | | | |
| | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter High
| | | |
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address Low
| | |
| | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address High
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address Low
|
V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address High
</pre>
Unimplemented Z80 DMA commands are ignored.

Prior to starting the DMA, a LOAD command must be issued to copy the Port A and Port B addresses into the DMA's internal pointers. Then an 'Enable DMA' command is issued to start the DMA.

The 'Continue' command resets the DMA's byte counter so that a following 'Enable DMA' allows the DMA to repeat the last transfer but using the current internal address pointers. I.e. it continues from where the last copy operation left off.

Registers can be read via an IO read from the DMA port after setting the read mask. (At power up the read mask is set to 0x7f). Register values are the current internal DMA counter values. So 'Port Address A Low' is the lower 8-bits of Port A’s next transfer address. Once the end of the read mask is reached, further reads loop around to the first one.

The format of the DMA status byte is as follows:

<pre>00E1101T</pre>

E is set to 0 if the total block length has been transferred at least once.

T is set to 1 if at least one byte has been transferred.

== Operating speed ==
The zxnDMA operates at the same speed as the CPU, that is 3.5MHz, 7MHz or 14MHz. This is a contended clock that is modified by the ULA and the auto-slowdown by [[Layer 2|Layer2]].

Auto-slowdown occurs without user intervention if speed exceeds 7Mhz and the active Layer2 display is being generated (higher speed operation resumes when the active Layer2 display is not generated). Programmers do NOT need to account for speed differences regarding DMA transfers as this happens automatically.

Because of this, the cycle lengths for Ports A and B can be set to their minimum values without ill effects. The cycle lengths specified for Ports A and B are intended to selectively slow down read or write cycles for hardware that cannot operate at the DMA's full speed.

== The DMA and Interrupts ==
The zxnDMA cannot currently generate [[Interrupts|interrupts]].

The other side of this is that while the DMA controls the bus, the Z80 cannot respond to interrupts. On the Z80, the NMI interrupt is edge triggered so if an NMI occurs the fact that it occurred is stored internally in the Z80 so that it will respond when it is woken up. On the other hand, maskable interrupts are level triggered. That is, the Z80 must be active to regularly sample the /INT line to determine if a maskable interrupt is occurring. On the Spectrum and the ZX Next, the ULA (and line interrupt) are only asserted for a fixed amount of time ~30 cycles at 3.5MHz. If the DMA is executing a transfer while the interrupt is asserted, the CPU will not be able to see this and it will most likely miss the interrupt. In burst mode, the CPU will never miss these interrupts, although this may change if multiple channels are implemented.

== Programming examples ==
A simple way to program the DMA is to walk down the list of registers WR0-WR5, sending desired settings to each. Then start the DMA by sending a LOAD command followed by an ENABLE_DMA command to WR6. Once more familiar with the DMA, you will discover that the amount of information sent can be reduced to what changes between transfers.

=== Assembly ===
Short example program to DMA memory to the screen, then DMA a sprite image from memory to sprite RAM, and then showing said sprite scrolling across the screen.

<pre>;------------------------------------------------------------------------------
device zxspectrum48
;------------------------------------------------------------------------------
; DEFINE testing
;------------------------------------------------------------------------------
; DMA (Register 6)
;
;------------------------------------------------------------------------------
;zxnDMA programming example
;------------------------------------------------------------------------------
;(c) Jim Bagley
;------------------------------------------------------------------------------
DMA_RESET equ $c3
DMA_RESET_PORT_A_TIMING equ $c7
DMA_RESET_PORT_B_TIMING equ $cb
DMA_LOAD equ $cf ; %11001111
DMA_CONTINUE equ $d3
DMA_DISABLE_INTERUPTS equ $af
DMA_ENABLE_INTERUPTS equ $ab
DMA_RESET_DISABLE_INTERUPTS equ $a3
DMA_ENABLE_AFTER_RETI equ $b7
DMA_READ_STATUS_BYTE equ $bf
DMA_REINIT_STATUS_BYTE equ $8b
DMA_START_READ_SEQUENCE equ $a7
DMA_FORCE_READY equ $b3
DMA_DISABLE equ $83
DMA_ENABLE equ $87
DMA_WRITE_REGISTER_COMMAND equ $bb
DMA_BURST equ %11001101
DMA_CONTINUOUS equ %10101101
ZXN_DMA_PORT equ $6b
SPRITE_STATUS_SLOT_SELECT equ $303B
SPRITE_IMAGE_PORT equ $5b
SPRITE_INFO_PORT equ $57
;------------------------------------------------------------------------------

IFDEF testing
org $6000
ELSE
org $2000
ENDIF

start
ld hl,$0000
ld de,$4000
ld bc,$800
call TransferDMA ; copy some random data to the screen pointing
; to ROM for now, for the purpose of showing
; how to do a DMA copy.
ld a,0 ; sprite image number we want to update
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a ; set the sprite image number
ld bc,1*256 ; number to transfer (1)
ld hl,testsprite ; from
call TransferDMASprite ; transfer to sprite ram

nextreg 21,1 ; turn sprite on. for more info on this check
; out https://www.specnext.com/tbblue-io-port-system/
ld de,0
ld (xpos),de ; set initial X position ( doesn't need it for
; this demo, but if you run the .loop again it
; will continue from where it was
ld a,$20
ld (ypos),a ; set initial Y position

.loop
ld a,0 ; sprite number we want to position
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a
ld de,(xpos)
ld hl,(ypos) ; ignores H so doing this rather than
; ld a,(ypos):ld l,a
ld bc,(image) ; not flipped or palette shifted
call SetSprite

halt

ld de,(xpos)
inc de
ld (xpos),de
ld a,d
cp $01
jr nz,.loop ; if high byte of xpos is not 1 (right of
; screen )
ld a,e
cp $20+1
jr nz,.loop ; if low byte is not $21 just off the right of
; the screen, $20 is off screen but as the
; INC DE is just above and not updated sprite
; after it, it needs to be $21
xor a
ret ; return back to basic with OK

xpos dw 0 ; x position
ypos db 0 ; y position
; these next two BITS and IMAGE are swapped
; as bits needs to go into B register image
; db 0+$80 ; use image 0 (for the image we
; transfered)+$80 to set the sprite to active
bits db 0 ; not flipped or palette shifted

c1 = %11100000
c2 = %11000000
c3 = %10100000
c4 = %10000000
c5 = %01100000
c6 = %01000000
c7 = %00100000
c8 = %00000000

testsprite
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1

;-------------------------------------------------
; de = X
; l = Y
; b = bits
; c = sprite image
SetSprite
push bc
ld bc,SPRITE_INFO_PORT
out (c),e ; Xpos
out (c),l ; Ypos
pop hl
ld a,d
and 1
or h
out (c),a
ld a,l:or $80
out (c),a ; image
ret

;--------------------------------
; hl = source
; de = destination
; bc = length
;--------------------------------
TransferDMA
di
ld (DMASource),hl
ld (DMADest),de
ld (DMALength),bc
ld hl,DMACode
ld b,DMACode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACode db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASource dw 0 ; R0-Port A, Start address
; (source address)
DMALength dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-write A time byte, increment, to
; memory, bitmask
db %00000010 ; 2t
db %01010000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db DMA_CONTINUOUS ; R4-Continuous mode (use this for block
; transfer), write dest adress
DMADest dw 0 ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_Len equ $-DMACode

;------------------------------------------------------------------------------
; hl = source
; bc = length
; set port to write to with TBBLUE_REGISTER_SELECT
; prior to call
;------------------------------------------------------------------------------
TransferDMAPort
di
ld (DMASourceP),hl
ld (DMALengthP),bc
ld hl,DMACodeP
ld b,DMACode_LenP
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeP db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceP dw 0 ; R0-Port A, Start address (source address)
DMALengthP dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw $253b ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_LenP equ $-DMACodeP
;------------------------------------------------------------------------------
; hl = source
; bc = length
;------------------------------------------------------------------------------
TransferDMASprite
di
ld (DMASourceS),hl
ld (DMALengthS),bc
ld hl,DMACodeS
ld b,DMACode_LenS
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeS db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceS dw 0 ; R0-Port A, Start address (source address)
DMALengthS dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw SPRITE_IMAGE_PORT ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA
DMACode_LenS equ $-DMACodeS
;------------------------------------------------------------------------------
; de = dest, a = fill value, bc = lenth
;------------------------------------------------------------------------------
DMAFill
di
ld (FillValue),a
ld (DMACDest),de
ld (DMACLength),bc
ld hl,DMACCode
ld b,DMACCode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

FillValue db 22
DMACCode db DMA_DISABLE
db %01111101
DMACSource dw FillValue
DMACLength dw 0
db %00100100,%00010000,%10101101
DMACDest dw 0
db DMA_LOAD,DMA_ENABLE
DMACCode_Len equ $-DMACCode

;------------------------------------------------------------------------------
; End of file
;------------------------------------------------------------------------------

IFDEF testing
savesna "DMAtest.sna",start
ELSE
fin
savebin "DMATEST",start,fin-start
ENDIF
</pre>

Based on original text by: Allen Albright & Mike Dailly with input by Jim Bagley, Lyndon J Sharp and Phoebus R. Dokos

DMA

2019-06-20T11:20:14Z

Daz: Completely replaced text with that from distro/specnext.com at suggestion of SevenFFF

== The ZX Spectrum Next DMA (zxnDMA)==

=== Overview ===
The ZX Spectrum Next DMA (zxnDMA) is a single channel DMA device that implements a subset of the Z80 DMA functionality. The subset is large enough to be compatible with common uses of the similar Datagear interface available for standard ZX Spectrum computers and compatibles. It also adds a burst mode capability that can deliver audio at programmable sample rates to the DAC device.

=== Accessing the zxnDMA ===
The zxnDMA is mapped to a single Read/Write IO Port 0x6B which is the same one used by the Datagear but unlike the Datagear it doesn't also map itself to a second port 0x0B similar to the MB-02 interface.

<code>PORT 0x6b: zxnDMA</code>

=== Description ===
The normal Z80 DMA (Z8410) chip is a pipelined device and because of that it has numerous off-by-one idiosyncrasies and requirements on the order that certain commands should be carried out. These issues are not duplicated in the zxnDMA. You can continue to program the zxnDMA as if it is were a Z8410 DMA device but it can also be programmed in a simpler manner.

The single channel of the zxnDMA chip consists of two ports named A and B. Transfers can occur in either direction between ports A and B, each port can describe a target in memory or IO, and each can be configured to autoincrement, autodecrement or stay fixed after a byte is transferred.

A special feature of the zxnDMA can force each byte transfer to take a fixed amount of time so that the zxnDMA can be used to deliver sampled audio.

=== Modes of Operation ===
The zxnDMA can operate in a z80-DMA compatibility mode.

The z80-DMA compatibility mode is selected by setting bit 6 of nextreg 0x06. In this mode, all transfers involve length+1 bytes which is the same behaviour as the z80-DMA chip. In zxn-DMA mode, the transfer length is exactly the number of bytes programmed. This mode is mainly present to accommodate existing spectrum software that uses the z80-DMA and for cp/m programs that may have a z80-DMA option.

The zxnDMA can also operate in either burst or continuous modes.

Continuous mode means the DMA chip runs to completion without allowing the CPU to run. When the CPU starts the DMA, the DMA operation will complete before the CPU executes its next instruction.

Burst mode nominally means the DMA lets the CPU run if either port is not ready. This condition can't happen in the zxnDMA chip except when operated in the special fixed time transfer mode. In this mode, the zxnDMA will let the CPU run while it waits for the fixed time to expire between bytes transferred.

Note that there is no byte transfer mode as in the Z80 DMA.

=== Programming the zxnDMA ===
Like the Z80 DMA chip, the zxnDMA has seven write registers named WR0-WR6 that control the device. Each register WR0-WR6 can have zero or more parameters associated with it.

In a first write to the zxnDMA port, the write value is compared against a bitmask to determine which of the WR0-WR6 is the target. Remaining bits in the written value can contain data as well as a list of associated parameter bits. The parameter bits determine if further writes are expected to deliver parameter values. If there are multiple parameter bits set, the expected order of parameter values written is determined by parameter bit position from right to left (bit 0 through bit 7). Once all parameters are written, the zxnDMA again expects a regular register write selecting WR0-WR6.

The table below describes the registers and the bitmask required to select them on the zxnDMA.

{|
! Register Group
! Register Function Description
! Bitmask
! Notes
|-
| WR0
| Direction, Operation and Port A configuration
| <pre>0XXXXXAA</pre>
| AA must NOT be 00
|-
| WR1
| Port A configuration
| <pre>0XXXX100</pre>
|
|-
| WR2
| Port B configuration
| <pre>0XXXX000</pre>
|
|-
| WR3
| Activation
| <pre>1XXXXX00</pre>
| It’s best to use WR6
|-
| WR4
| Port B, Timing and Interrupt configuration
| <pre>1XXXXX01</pre>
|
|-
| WR5
| Ready and Stop configuration
| <pre>10XXX010</pre>
|
|-
| WR6
| Command Register
| <pre>1XXXXX11</pre>
|
|}

=== zxnDMA Registers ===
These are described below following the same convention used by Zilog for its DMA chip:

==== WR0 – Write Register Group 0 ====

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | | | |
| | | | | 0 0 Do not use
| | | | | 0 1 Transfer (Prefer this for Z80 DMA compatibility)
| | | | | 1 0 Do not use (Behaves like Transfer, Search on Z80 DMA)
| | | | |
| | | | | 1 1 Do not use (Behaves like Transfer, Search/Transfer on Z80 DMA)
| | | | |
| | | | 0 = Port B -> Port A (Byte transfer direction)
| | | | 1 = Port A -> Port B
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (LOW BYTE)
| | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (HIGH BYTE)
| V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (LOW BYTE)
V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (HIGH BYTE)</pre>

Several registers are accessible from WR0. The first write to WR0 is to the base register byte. Bits D6:D3 are optionally set to indicate that associated registers in this group will be written next. The order the writes come in are from D3 to D6 (right to left). For example, if bits D6 and D3 are set, the next two writes will be directed to PORT A STARTING ADDRESS LOW followed by BLOCK LENGTH HIGH.

==== WR1 – Write Register Group 1 ====

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 1 0 0
| | | |
| | | 0 = Port A is memory
| | | 1 = Port A is IO
| | |
| 0 0 = Port A address decrements
| 0 1 = Port A address increments
| 1 0 = Port A address is fixed
| 1 1 = Port A address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A VARIABLE TIMING BYTE
0 0 0 0 0 0 | |
0 0 = Cycle Length = 4
0 1 = Cycle Length = 3
1 0 = Cycle Length = 2
1 1 = Do not use
</pre>

The cycle length is the number of cycles used in a read or write operation. The first cycle asserts signals and the last cycle releases them. There is no half cycle timing for the control signals.

==== WR2 – Write Register Group 2 ====

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 0 0 0
| | | |
| | | 0 = Port B is memory
| | | 1 = Port B is IO
| | |
| 0 0 = Port B address decrements
| 0 1 = Port B address increments
| 1 0 = Port B address is fixed
| 1 1 = Port B address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B VARIABLE TIMING BYTE
0 0 | 0 0 0 | |
| 0 0 = Cycle Length = 4
| 0 1 = Cycle Length = 3
| 1 0 = Cycle Length = 2
| 1 1 = Do not use
|
V
D7 D6 D5 D4 D3 D2 D1 D0 ZXN PRESCALAR (FIXED TIME TRANSFER)
</pre>
The ZXN PRESCALAR is a feature of the zxnDMA implementation. If non-zero, a delay will be inserted after each byte is transferred such that the total time needed for each transfer is determined by the prescalar. This works in both the continuous mode and the burst mode. If the DMA is operated in burst mode, the DMA will give up any waiting time to the CPU so that the CPU can run while the DMA is idle.

The rate of transfer is given by the formula “Frate = 875kHz / prescalar” or, rearranged, “prescalar = 875kHz / Frate”. The formula is framed in terms of a sample rate (Frate) but Frate can be inverted to set a transfer time for each byte instead. The 875kHz constant is a nominal value assuming a 28MHz system clock; the system clock actually varies from this depending on the video timing selected by the user (HDMI, VGA0-6) so for complete accuracy the constant should be prorated according to documentation for nextreg 0x11.

In a DMA audio setting, selecting a sample rate of 16kHz would mean setting the prescalar value to 55. This sample period is constant across changes in CPU speed.

==== WR3 – Write Register Group 3 ====

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | 0 0 0 0 0 0
|
1 = DMA Enable
</pre>
The Z80 DMA defines more fields but they are ignored by the zxnDMA. The two other registers defined by the Z80 DMA in this group on D4 and D3 are implemented by the zxnDMA but they do nothing.

It is preferred to start the DMA by writing an 'Enable DMA' command to WR6.

==== WR4 – Write Register Group 4 ====

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | | 0 | | 0 1
| | | |
0 0 = Do not use (Behaves like Continuous mode, Byte mode on Z80 DMA)
0 1 = Continuous mode
1 0 = Burst mode
1 1 = Do not use
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (LOW BYTE)
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (HIGH BYTE)
</pre>
The Z80 DMA defines three more registers in this group through D4 that define interrupt behaviour. Interrups and pulse generation are not implemented in the zxnDMA nor are these registers available for writing.

==== WR5 – Write Register Group 5 ====
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 0 | | 0 0 1 0
| |
| 0 = /ce only
| 1 = /ce & /wait multiplexed
|
0 = Stop on end of block
1 = Auto restart on end of block
</pre>
The /ce & /wait mode is implemented in the zxnDMA but is not currently used. This mode has an external device using the DMA's /ce pin to insert wait states during the DMA's transfer.

The auto restart feature causes the DMA to automatically reload its source and destination addresses and reset its byte counter to zero to repeat the last transfer when a previous one is finished.

==== WR6 – Command Register ====
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 ? ? ? ? ? 1 1
| | | | |
1 0 0 0 0 = 0xC3 = Reset
1 0 0 0 1 = 0xC7 = Reset Port A Timing
1 0 0 1 0 = 0xCB = Reset Port B Timing
0 1 1 1 1 = 0xBF = Read Status Byte
0 0 0 1 0 = 0x8B = Reinitialize Status Byte
0 1 0 0 1 = 0xA7 = Initialize Read Sequence
1 0 0 1 1 = 0xCF = Load
1 0 1 0 0 = 0xD3 = Continue
0 0 0 0 1 = 0x87 = Enable DMA
0 0 0 0 0 = 0x83 = Disable DMA
+-- 0 1 1 1 0 = 0xBB = Read Mask Follows
|
D7 D6 D5 D4 D3 D2 D1 D0 READ MASK
0 | | | | | | |
| | | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Status Byte
| | | | | |
| | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter Low
| | | | |
| | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter High
| | | |
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address Low
| | |
| | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address High
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address Low
|
V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address High
</pre>
Unimplemented Z80 DMA commands are ignored.

Prior to starting the DMA, a LOAD command must be issued to copy the Port A and Port B addresses into the DMA's internal pointers. Then an 'Enable DMA' command is issued to start the DMA.

The 'Continue' command resets the DMA's byte counter so that a following 'Enable DMA' allows the DMA to repeat the last transfer but using the current internal address pointers. I.e. it continues from where the last copy operation left off.

Registers can be read via an IO read from the DMA port after setting the read mask. (At power up the read mask is set to 0x7f). Register values are the current internal DMA counter values. So 'Port Address A Low' is the lower 8-bits of Port A’s next transfer address. Once the end of the read mask is reached, further reads loop around to the first one.

The format of the DMA status byte is as follows:

<pre>00E1101T</pre>

E is set to 0 if the total block length has been transferred at least once.

T is set to 1 if at least one byte has been transferred.

=== Operating speed ===
The zxnDMA operates at the same speed as the CPU, that is 3.5MHz, 7MHz or 14MHz. This is a contended clock that is modified by the ULA and the auto-slowdown by [[Layer 2|Layer2]].

Auto-slowdown occurs without user intervention if speed exceeds 7Mhz and the active Layer2 display is being generated (higher speed operation resumes when the active Layer2 display is not generated). Programmers do NOT need to account for speed differences regarding DMA transfers as this happens automatically.

Because of this, the cycle lengths for Ports A and B can be set to their minimum values without ill effects. The cycle lengths specified for Ports A and B are intended to selectively slow down read or write cycles for hardware that cannot operate at the DMA's full speed.

=== The DMA and Interrupts ===
The zxnDMA cannot currently generate [[Interrupts|interrupts]].

The other side of this is that while the DMA controls the bus, the Z80 cannot respond to interrupts. On the Z80, the NMI interrupt is edge triggered so if an NMI occurs the fact that it occurred is stored internally in the Z80 so that it will respond when it is woken up. On the other hand, maskable interrupts are level triggered. That is, the Z80 must be active to regularly sample the /INT line to determine if a maskable interrupt is occurring. On the Spectrum and the ZX Next, the ULA (and line interrupt) are only asserted for a fixed amount of time ~30 cycles at 3.5MHz. If the DMA is executing a transfer while the interrupt is asserted, the CPU will not be able to see this and it will most likely miss the interrupt. In burst mode, the CPU will never miss these interrupts, although this may change if multiple channels are implemented.

=== Programming examples ===
A simple way to program the DMA is to walk down the list of registers WR0-WR5, sending desired settings to each. Then start the DMA by sending a LOAD command followed by an ENABLE_DMA command to WR6. Once more familiar with the DMA, you will discover that the amount of information sent can be reduced to what changes between transfers.

==== Assembly ====
Short example program to DMA memory to the screen, then DMA a sprite image from memory to sprite RAM, and then showing said sprite scrolling across the screen.

<pre>;------------------------------------------------------------------------------
device zxspectrum48
;------------------------------------------------------------------------------
; DEFINE testing
;------------------------------------------------------------------------------
; DMA (Register 6)
;
;------------------------------------------------------------------------------
;zxnDMA programming example
;------------------------------------------------------------------------------
;(c) Jim Bagley
;------------------------------------------------------------------------------
DMA_RESET equ $c3
DMA_RESET_PORT_A_TIMING equ $c7
DMA_RESET_PORT_B_TIMING equ $cb
DMA_LOAD equ $cf ; %11001111
DMA_CONTINUE equ $d3
DMA_DISABLE_INTERUPTS equ $af
DMA_ENABLE_INTERUPTS equ $ab
DMA_RESET_DISABLE_INTERUPTS equ $a3
DMA_ENABLE_AFTER_RETI equ $b7
DMA_READ_STATUS_BYTE equ $bf
DMA_REINIT_STATUS_BYTE equ $8b
DMA_START_READ_SEQUENCE equ $a7
DMA_FORCE_READY equ $b3
DMA_DISABLE equ $83
DMA_ENABLE equ $87
DMA_WRITE_REGISTER_COMMAND equ $bb
DMA_BURST equ %11001101
DMA_CONTINUOUS equ %10101101
ZXN_DMA_PORT equ $6b
SPRITE_STATUS_SLOT_SELECT equ $303B
SPRITE_IMAGE_PORT equ $5b
SPRITE_INFO_PORT equ $57
;------------------------------------------------------------------------------

IFDEF testing
org $6000
ELSE
org $2000
ENDIF

start
ld hl,$0000
ld de,$4000
ld bc,$800
call TransferDMA ; copy some random data to the screen pointing
; to ROM for now, for the purpose of showing
; how to do a DMA copy.
ld a,0 ; sprite image number we want to update
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a ; set the sprite image number
ld bc,1*256 ; number to transfer (1)
ld hl,testsprite ; from
call TransferDMASprite ; transfer to sprite ram

nextreg 21,1 ; turn sprite on. for more info on this check
; out https://www.specnext.com/tbblue-io-port-system/
ld de,0
ld (xpos),de ; set initial X position ( doesn't need it for
; this demo, but if you run the .loop again it
; will continue from where it was
ld a,$20
ld (ypos),a ; set initial Y position

.loop
ld a,0 ; sprite number we want to position
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a
ld de,(xpos)
ld hl,(ypos) ; ignores H so doing this rather than
; ld a,(ypos):ld l,a
ld bc,(image) ; not flipped or palette shifted
call SetSprite

halt

ld de,(xpos)
inc de
ld (xpos),de
ld a,d
cp $01
jr nz,.loop ; if high byte of xpos is not 1 (right of
; screen )
ld a,e
cp $20+1
jr nz,.loop ; if low byte is not $21 just off the right of
; the screen, $20 is off screen but as the
; INC DE is just above and not updated sprite
; after it, it needs to be $21
xor a
ret ; return back to basic with OK

xpos dw 0 ; x position
ypos db 0 ; y position
; these next two BITS and IMAGE are swapped
; as bits needs to go into B register image
; db 0+$80 ; use image 0 (for the image we
; transfered)+$80 to set the sprite to active
bits db 0 ; not flipped or palette shifted

c1 = %11100000
c2 = %11000000
c3 = %10100000
c4 = %10000000
c5 = %01100000
c6 = %01000000
c7 = %00100000
c8 = %00000000

testsprite
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1

;-------------------------------------------------
; de = X
; l = Y
; b = bits
; c = sprite image
SetSprite
push bc
ld bc,SPRITE_INFO_PORT
out (c),e ; Xpos
out (c),l ; Ypos
pop hl
ld a,d
and 1
or h
out (c),a
ld a,l:or $80
out (c),a ; image
ret

;--------------------------------
; hl = source
; de = destination
; bc = length
;--------------------------------
TransferDMA
di
ld (DMASource),hl
ld (DMADest),de
ld (DMALength),bc
ld hl,DMACode
ld b,DMACode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACode db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASource dw 0 ; R0-Port A, Start address
; (source address)
DMALength dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-write A time byte, increment, to
; memory, bitmask
db %00000010 ; 2t
db %01010000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db DMA_CONTINUOUS ; R4-Continuous mode (use this for block
; transfer), write dest adress
DMADest dw 0 ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_Len equ $-DMACode

;------------------------------------------------------------------------------
; hl = source
; bc = length
; set port to write to with TBBLUE_REGISTER_SELECT
; prior to call
;------------------------------------------------------------------------------
TransferDMAPort
di
ld (DMASourceP),hl
ld (DMALengthP),bc
ld hl,DMACodeP
ld b,DMACode_LenP
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeP db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceP dw 0 ; R0-Port A, Start address (source address)
DMALengthP dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw $253b ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_LenP equ $-DMACodeP
;------------------------------------------------------------------------------
; hl = source
; bc = length
;------------------------------------------------------------------------------
TransferDMASprite
di
ld (DMASourceS),hl
ld (DMALengthS),bc
ld hl,DMACodeS
ld b,DMACode_LenS
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeS db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceS dw 0 ; R0-Port A, Start address (source address)
DMALengthS dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw SPRITE_IMAGE_PORT ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA
DMACode_LenS equ $-DMACodeS
;------------------------------------------------------------------------------
; de = dest, a = fill value, bc = lenth
;------------------------------------------------------------------------------
DMAFill
di
ld (FillValue),a
ld (DMACDest),de
ld (DMACLength),bc
ld hl,DMACCode
ld b,DMACCode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

FillValue db 22
DMACCode db DMA_DISABLE
db %01111101
DMACSource dw FillValue
DMACLength dw 0
db %00100100,%00010000,%10101101
DMACDest dw 0
db DMA_LOAD,DMA_ENABLE
DMACCode_Len equ $-DMACCode

;------------------------------------------------------------------------------
; End of file
;------------------------------------------------------------------------------

IFDEF testing
savesna "DMAtest.sna",start
ELSE
fin
savebin "DMATEST",start,fin-start
ENDIF
</pre>

Based on original text by: Allen Albright & Mike Dailly with input by Jim Bagley, Lyndon J Sharp and Phoebus R. Dokos

GPIO Socket (J15)

2019-06-19T14:06:16Z

Daz:

The GPIO socket, marked J15 on the circuit board, allows access to several different power and data lines:

* I2C serial protocol
* UART
* Spare pins on the FPGA
* 5v, 3.3v and GND

The UART is also used for the ESP Wi-fi module, and can't be used from the GPIO without removing the ESP module. I2C is also used to communicate with the real time clock module.

The GPIO is not populated and requires a socket to be installed. Pull up/down resisters may be required for some pins to limit current.

[[Image:NEXT GPIO location.jpg|thumb|J15 position on circuit board]]
[[Image:NEXT_GPIO.png|thumb|GPIO pinout image]]

GPIO Socket (J15)

2019-06-19T13:42:51Z

Daz: Image links

The GPIO socket, marked J15 on the circuit board, allows access to several different power and data lines:

* I2C serial protocol
* UART
* Spare pins on the FPGA
* 5v, 3.3v and GND

The UART is also used for the ESP Wi-fi module, and can't be used from the GPIO without removing the ESP module. I2C is also used to communicate with the real time clock module.

The GPIO is not populated and requires a socket to be installed. Pull up/down resisters may be required for some pins to limit current.

[[Image:NEXT GPIO location.jpg|thumb|J15 position on circuit board]]
[[Image:https://www.specnext.com/forum/download/file.php?id=403|thumb|GPIO pinout image (from SpecNext.com forums)]]

GPIO Socket (J15)

2019-06-19T13:39:16Z

Daz: Initial version - all the info I could scrape up, but needs more depth...

The GPIO socket, marked J15 on the circuit board, allows access to several different power and data lines:

* I2C serial protocol
* UART
* Spare pins on the FPGA
* 5v, 3.3v and GND

The UART is also used for the ESP Wi-fi module, and can't be used from the GPIO without removing the ESP module. I2C is also used to communicate with the real time clock module.

The GPIO is not populated and requires a socket to be installed. Pull up/down resisters may be required for some pins to limit current.

<gallery>
https://www.specnext.com/forum/download/file.php?id=403|J15 pinout image (from SpecNext.com forums)
/w/images/e/e6/NEXT_GPIO_location.jpg|J15 position on circuit board
</gallery>

File Formats

2019-06-11T20:54:22Z

Daz: Typo fixed

The NextZXOS can directly read and load these kind of files: bas, tap, z80, sna, snx, dot, o, p. Many other file types are supported by the use of external dot commands.

* '''[https://www.worldofspectrum.org/faq/reference/z80format.htm .z80]''' is a Spectrum snapshot file, more suitable as emulator compatibility than a real format. Files can be loaded using the NextZXOS browser, the NextZXOS SPECTRUM keyword, the esxDOS NMI menu, and the exDOS .snapload command.
* '''[https://faqwiki.zxnet.co.uk/wiki/SNA_format .sna]''' is a Spectrum snapshot file, more suitable as emulator compatibility than a real format. Both 48K and 128K SNA files are supported. Files can be loaded using the NextZXOS browser, the NextZXOS SPECTRUM keyword, the esxDOS NMI menu, and the exDOS .snapload command. When loading in NextZXOS, any private data appended to the file is ignored during loading, and the program code may later read it by reopening itself using a hardcoded filename. If private data is appended to them then they cannot be loaded by esxDOS.
* '''.snx''' is a Spectrum snapshot file, more suitable as emulator compatibility than a real format. It is identical to a 128K .sna file, but when loaded using the browser or the SPECTRUM command, NextZXOS leaves file handle 0 open for further use by the program. The program is expected close the handle before exiting. .snx files may also have private data appended to them. They are not supported by esxDOS.
* '''.o''' is a ZX80 snapshot
* '''.p''' is a ZX81 snapshot
* '''[[NEX file format|.nex]]''' is good for a program that takes over the machine. With some care, it can also be used to load a program without overwriting sysvars, allowing NextZXOS API calls to be used. It can be loaded using the NextZXOS file browser and the .nexload dot command. The [[Emulators|CSpect]] emulator can open .nex files natively from the F2 dialog. esxDOS cannot open .nex files.
* '''.dot''' is good for dot commands and programs that can coexist with BASIC/NextZXOS and can return to BASIC safely (i.e. counterpart to nex)
* '''[[TAP file format|.tap]]''' is a simple container format that can hold many files, is compatible with emulators and supported by many tools. When loading .tap files using the NextZXOS browser, a menu is displayed asking whether you want to load in standard, USR0 or 48K mode.
* '''.bas''' is the native SD-card format for BASIC programs (first 128 bytes of the file form standard +3DOS header).
* .'''scr''' is used for a standard Spectrum screenshot created with ''SAVE "picture.scr" SCREEN$'' (256x192, 15 colours per character cell).
* '''.shc''' is used for a screenshot in Timex 8x1 Hi-colour mode (256x192, 15 colors).
* '''.shr''' is used for a screenshot in Timex Hi-res mode (512x192, mono).
* '''.slr''' is used for a lo-res screenshot (128x96, 256 colours).
* '''.sl2''' is used for a Layer 2 screenshot (256x192, 256 colour).
* '''.pal''' is a 9-bit palette format (256 pairs of bytes in %RRRGGGBB, %P000000B format). Files can be loaded and saved from the Screenshots menu in NextZXOS after pressing the M1 button or F9. The P bit sets priority when used in layer 2 palettes. Palette entries with P=1 cause their pixels to appear above everything else, regardless of globally-set layer priorities.
* '''.npl''' is a 9-bit palette format. The first 512 bytes are identical to a .pal file. The 513th byte designates transparency - for sprite palettes, the transparency byte is a real index, and for other palettes it is a colour mask. .npl files can be created, saved and loaded by [[Miscellaneous#WASPtools|WASPtools]].

Template:Emulator

2019-06-11T11:38:39Z

Daz: Fix wifi link in template

<noinclude>
{{#cargo_declare:
_table = Emulator
|name = String
|author = String
|description = String
|os = String
|downloadurl = String
|sourceurl = String
|sourceavail = String
|supportlores = String
|supportrasterint = String
|supporttripleay = String
|supportopcodes = String
|supportsid = String
|supportspecdrum = String
|supportwifi = String
}}
</noinclude>
<includeonly>
{{#subobject:{{{name}}}
|name={{{name|}}}
|author={{{author|}}}
|description={{{description|}}}
|os={{{os|}}}
|downloadurl={{{downloadurl|}}}
|sourceurl={{{sourceurl|}}}
|sourceavail={{{sourceavail|}}}
|supportrasterint={{{supportrasterint|}}}
}}
{{#cargo_store:
_table = Emulator
|name={{{name|}}}
|author={{{author|}}}
|os={{{os|}}}
|description={{{description|}}}
|downloadurl={{{downloadurl|}}}
|sourceurl={{{sourceurl|}}}
|sourceavail={{{sourceavail|}}}
|supportrasterint={{{supportrasterint|}}}
|supporttripleay={{{supporttripleay|}}}
|supportopcodes={{{supportopcodes|}}}
|supportsid={{{supportsid|}}}
|supportspecdrum={{{supportspecdrum|}}}
|supportwifi={{{supportwifi|}}}
}}
|valign='top'|'''{{{name|}}}''' - ''{{{author|}}}''<br/>{{{description|}}}<br/>{{#if:{{{downloadurl|}}}|[{{{downloadurl|}}} download]    }}{{#if:{{{sourceurl|}}}|[{{{sourceurl|}}} source]    }}
|valign='top'|{{{os|}}}
|valign='top'|{{{sourceavail|}}}
|valian='top'|{{Capability|{{{supportsprites|}}}|[[Sprites]]}}{{Capability|{{{supportlores|}}}|[[Video Modes|Lores Layer]]}}{{Capability|{{{supportlayer2|}}}|[[Layer 2]]}}{{Capability|{{{supportrasterint|}}}|Raster interrupt}}{{Capability|{{{supporttripleay|}}}|[[Turbo Sound Next|3xAY audio]]}}{{Capability|{{{supportopcodes|}}}|[[Extended Z80 instruction set|Next Opcodes]]}}{{Capability|{{{supportsid|}}}|[[Turbo Sound Next|SID audio]]}}{{Capability|{{{supportspecdrum|}}}|Specdrum/Covox DAC}}{{Capability|{{{supportwifi|}}}|[[ESP8266-01|Wifi Module]]}}
|-
</includeonly>

Emulators

2019-06-11T11:37:44Z

Daz: Added "supportwifi" to CSpect

{{EmulatorListTop}}

{{Emulator|name=CSpect
|author=Mike Dailly
|downloadurl=http://dailly.blogspot.co.uk/
|description=Emulates many features of the Next and includes an assembler (pre-made SD card images [http://www.zxspectrumnext.online/cspect/index.html here])
|os=Windows<br>(mac/linux partially works through mono)
|sourceavail=N
|supportsprites=~
|supportlores=Y
|supportlayer2=Y
|supportopcodes=Y
|supporttripleay=Y
|supportsid=N
|supportwifi=Y
}}

{{Emulator|name=ZEsarUX
|author=César Hernández Bañó
|downloadurl=https://github.com/chernandezba/zesarux/releases
|sourceurl=https://github.com/chernandezba/zesarux
|description=A full feature emulator including a debugger - frequently updated to support Next updates
|os=Any
|sourceavail=Y
|supportsprites=~
|supportlores=Y
|supportlayer2=Y
|supportopcodes=Y
|supporttripleay=Y
|supportsid=N
|supportspecdrum=Y
}}

{{Emulator|name=NX
|author=Matt Davies
|downloadurl=https://github.com/next-dev/nx
|sourceurl=https://github.com/next-dev/nx
|description=An in-development emulator
|os=Windows / Mac
|sourceavail=Y
}}

{{Emulator|name=Zeus
|author=Design Design
|downloadurl=http://www.desdes.com/products/oldfiles/zeus.htm
|description=A PC cross-assembler which includes a Z80 emulator, which can emulate the ZX Spectrum 48K/128K hardware.
|os=Windows
|sourceavail=N
|supportsprites=~
|supportlores=N
|supportlayer2=N
|supportopcodes=Y
|supporttripleay=N
|supportsid=N
|supportspecdrum=N
|supportsmmu=Y
}}

{{EmulatorListBottom}}

Template:Emulator

2019-06-11T11:36:08Z

Daz: Added "supportwifi" flag

File Formats

2019-05-31T14:05:26Z

Daz: Added layer resolutions

The NextZXOS can read and load these kind of files: bas, tap, nex, z80, sna, snx, dot, o, p

* .z80, .sna and .snx are Spectrum snapshots, more suitable as emulator compatibility than a real format
* .o is a ZX80 snapshot
* .p is a ZX81 snapshot
* [[NEX file format|.nex]] is good for a program that takes over the machine
* .dot is good for dot commands and programs that can coexist with BASIC/NextZXOS and can return to BASIC safely (i.e. counterpart to nex)
* [[TAP file format|.tap]] is a simple container format that can hold many files, is compatible with emulators and supported by many tools.
* .bas is the native SD-card format for BASIC programs (first 128 bytes of the file form standard +3DOS header).
* .scr is used for a standard Spectrum screenshot created with ''SAVE "picture.scr" SCREEN$'' (256x192, 15 colours per character cell).
* .shc is used for a screenshot in Timex 8x1 Hi-colour mode (256x192, 15 colors).
* .shr is used for a screenshot in Timex Hi-res mode (512x192, mono).
* .slr is used for a lo-res screenshot (128x96, 256 colours).
* .sl2 is used for a Layer 2 screenshot (256x192, 256 colour).

File Formats

2019-05-31T13:02:11Z

Daz: Added more file formats.

The NextZXOS can read and load these kind of files: bas, tap, nex, z80, sna, snx, dot, o, p

* .z80, .sna and .snx are Spectrum snapshots, more suitable as emulator compatibility than a real format
* .o is a ZX80 snapshot
* .p is a ZX81 snapshot
* [[NEX file format|.nex]] is good for a program that takes over the machine
* .dot is good for dot commands and programs that can coexist with BASIC/NextZXOS and can return to BASIC safely (i.e. counterpart to nex)
* [[TAP file format|.tap]] is a simple container format that can hold many files, is compatible with emulators and supported by many tools.
* .bas is the native SD-card format for BASIC programs (first 128 bytes of the file form standard +3DOS header).
* .scr is used for a standard Spectrum screenshot (SAVE "picture.scr" SCREEN$)
* .shc is used for a screenshot in Timex 8x1 Hi-colour mode.
* .shr is used for a screenshot in Timex Hi-res mode.
* .slr is used for a lo-res screenshot.
* .sl2 is used for a layer 2 screenshot.

ESP8266-01

2019-05-20T12:53:05Z

Daz:

A Wi-Fi module and Real Time Clock (RTC) were optional additions to the full cased Spectrum Next at the time of the original Kickstarter. They can be added to development boards and units that don't already have them. Although the RTC requires soldering components to the board, but the Wi-Fi module is a push-fit component.

== Hardware Requirements ==

Adding Wi-Fi to a board requires only a ESP8266 ESP-01 module. This supports 802.11 b/g/n at 2.5 Ghz including the WPA and WPA2 security protocols. The mounting point for the module is just behind the VGA port.

ESP modules have an updatable firmware. In general the standard firmware, should work out of the box with the Spectrum Next. If you're buying a module, check it has a standard firmware.

The Wi-Fi makes use of the on-board UART (Universal Asynchronous Receiver-Transmitter) of the Spectrum Next (you can use this without a WiFi module for serial connections as as well.) The UART on the Next board (built inside the FPGA logic) can control the RX/TX lines from 2400 bps up to 115200 bps (the default speed). The ESP module uses the "AT instruction set" of a typical modem and the official PDF is available here: https://www.espressif.com/sites/default/files/documentation/4a-esp8266_at_instruction_set_en.pdf

== Software Support ==

This information relates to [https://www.specnext.com/latestdistro/ TBBlue SD Distribution] 2.00.26 and later (2019-01-27).

The distribution contains dot commands (including "UART") and the "TERMINALS.BAS" program for working with the Wi-Fi module.

.UART is a simple DOT command that works in NextZXOS (and ESXDOS) to allow you to talk to a connected device which could be a Wi-Fi module. Due to the limitations of the 512 byte hardware buffer ,it can only be used for small amounts of data and is mainly intended to allow diagnosis. It does include a simple CIPSEND mode that allows connections to be made with an ESP Wi-Fi module.

UART.DRV is an interrupt driven driver (NextZXOS only) which can provide a 16K software buffer which means much less incoming data is lost. There is both a simple demo IUDEMO and a terminal program (not a DOT command) that provides an alternative to .UART that can handle much more data. This is intended for users of the port without the Wi-Fi module really but can be used to setup the ESP.

The TERMINAL.BAS program is much better than .UART and you will have better results following through some of the examples below.

You can also begin to play with the real feature of the Internet Toolbox which is the ESPAT driver for BASIC (again NextZXOS only). It can be used with the BASIC ESPTERM program to chat over an IP link and the ESPHTTP sample program shows how a web page can be retrieved from BASIC (but not rendered.)

The Source code to the IRQ stub is provided to allow the ESPAT code to be used in games that take over the machine, providing a gaming API.

Be sure to check out NXTel the Viewdata (Prestel/Teletext) terminal that allows the Next to connect and get news pages from Viewdata servers already online.

=== .UART ===

'''Key mapping'''

{|
|-
| Spectrum key || PS/2 Key || Action
|-
| EDIT || SHIFT+1 || Cycle output mode
|-
| CAPS LOCK || SHIFT+2 || On/off toggle (on by default)
|-
| TRUE VIDEO || SHIFT+3 || Debug mode for CIPSEND on/off (silent)
|-
| INV VIDEO || SHIFT+4 || CIPSEND mode on/off, also does an ATE0
|-
| GRAPHICS || SHIFT+9 || Change BAUD rate
|-
| DELETE || SHIFT+0 || Delete
|-
| SYMBOL SHIFT + SPACE || CONTROL+SPACE || Exit Program
|}

== Basic Connection ==

Run the .UART command, or better LOAD "TERMINAL.BAS" and RUN it.

First of all when you press ''ENTER'' you should get 'ERROR' because you didn't send a valid command to the ESP module. If you don't then it may be a number of things:

* You are using the TBU and firmware BEFORE 0.8 and NextOS 1.92 - if so this will only work at 3.5Mhz so slow the machine down and restart .UART.
* You are using a TBU and firmware with a Core .29 or greater, with an OLD copy of the .UART program which wrote the BAUD rate differently - if so when you cycle through the speeds (EDIT/SHIFT+1) you will find it may 'work' at 38400 - it is actually a fluke as the old value for that rate is quite close to the value needed for 115200 on the new system.
* Your module may have come with a default baud rate other than the 115200 of the Next. Using GRAPHICS (SHIFT+9) you can cycle through each option pressing ''ENTER'' until you see "ERROR!" (If you can physically see the module then many have a little blue light that flashes when receiving.)

If you believe the baud rate is set incorrectly on the module, from version 2.2e of .UART, there is a command to search all possible settings from about 4000 to 2.2M baud:

.UART -f

Once you have the module reporting 'ERROR' you should be able to type 'AT' and press ''ENTER''. That should give "OK".

Probably the first thing you want to do is tell the module to use the default speed of the next so type:

AT+UART=115200,8,1,0,0

and press ''ENTER''.

You now need to use ''GRAPHICS'' (SHIFT+9) to go back around to 115200 so that ''ENTER'' gives ERROR and AT ''ENTER'' gives OK again....

We just used one of the AT commands:

AT+UART=<baudrate>,<databits>,<stopbits>,<parity>,<flow control>

== Getting on the Network ==

Now to connect to a Wi-Fi access point:

First let's check that the system is in STAtion mode:

AT+CWMODE=?

This will give 1,2 or 3 (where STA=1, AP=2, Both=3). Mode 1 or 3 is fine but, more config is needed in mode 2.

Set the mode:

AT+CWMODE=1

List Access Points:
AT+CWLAP

To join an Access Point:
AT+CWJAP="wifinetwork","password"

Note that the module will retain the Wi-Fi connection and you can just do an AT+RST which will reset the module and give a CONNECTED and GOT IP.

Here are some more common AT commands:

{|
|-
| AT+CIFSR || Echo the current IP address on the network
|-
| AT+GMR || Echo the current versions of the software on your module
|-
| AT+CWQAP || Forget the WiFi network and password
|}

== Connecting to a Server ==

Let's try connecting to a server on the internet:

AT+CIPSTART="TCP","www.google.com",80

That is just the first stage and means there is now a pipe from the ESP to the Google server. Before it does anything you need to send it something. If you do feel brave before you close the connection then you can send:

AT+CIPSEND=7

at the ">" prompt which appears you should type:

GET /

These 5 characters need to be followed by a character 13-Carriage Return and a 10-linefeed. I.E. Just press return twice.

AT+CIPSEND=length allows you to get the ">" prompt and type 'length' characters. Incoming replies will be "+ IPD,length:" followed by the data (no space). Finally you will need to close down the connection:

AT+CIPCLOSE

This is very fiddly so .UART and TERMINAL include a mode called CIPSEND that does all the decoding for you.

If you press INV VIDEO (SHIFT+4) then the system will send an ATE0 to stop the ESP echoing everything and then anything you type will be sent followed by a Return and Newline.

You can also on TERMINAL use EDIT (SHIFT+1) to go into immediate mode, where everything you type is sent as you do it. In this mode to send a LF you need to Symbol Shift + ENTER after pressing ENTER (or SHIFT and 6 / down-arrow) to send a 10 / LF / Newline. This makes AT commands more complex but this mode is more useful to use the program as a traditional text terminal.

Anything the other end replies with will just appear. Note that at 14MHz you will get more text before the system begins to lose data due to the delays in printing what is received. Far more works on TERMINAL than .UART.

This mode is good enough to be a simple text terminal for a shell on a linux box or any test system.

If you connect to Google again and use CIPSEND mode then send four lines EXACTLY like this:

GET / HTTP/1.1\r\n
Host: www.google.com\r\n
Connection: close\r\n
\r\n

(where the \r\n represent what CIPSEND will do when you press ENTER)

Your screen will fill with the RAW data that makes up the very simple Google home page...

In order to get back to talking to the ESP you will now need to exit CIPSEND mode by pressing INV VIDEO (SHIFT+4) again.

== Connecting to a Non-HTTP Server ==

AT+CIPSTART="TCP","dict.org",2628

Should get you:

220 ..............some WELCOME.....

Go into CIPSEND mode with INV. VIDEO (SHIFT+4) and type:

DEFINE wn server\r\n

And you should get:

150 1 definitions retrieved
151 "server" wn "WordNet (r) 2.0"
server
n 1: a person whose occupation is to serve at table (as in a
restaurant) [syn: {waiter}]
2: (court games) the player who serves to start a point
3: (computer science) a computer that provides client stations
with access to files and printers as shared resources to a
computer network [syn: {host}]
4: utensil used in serving food or drink
.
250 ok [d/m/c = 1/0/18; 0.000r 0.000u 0.000s]

Now send:

QUIT

and you will get

221 bye [d/m/c = 0/0/0; 16.000r 0.000u 0.000s]

== Other Hardware ==

In addition to controlling the ESP-01 Wi-Fi module, the .UART command also provides facilities to use the serial connection port, either directly through some form of serial converter (e.g. a USB to TTL serial) or standard RS232 module (probably based on the MAX232).

A USB serial connection allows you to do all sorts of clever things - it is possible to connect up to a PC like this for transferring data. In fact if you were an early purchaser you probably bought one with your ESP-01 as it is the one needed to program it.

If you use one of the easy to get TTL modules then you can communicate with PC's and other older machines - E.g. a real Spectrum with Interface 1... KevB is using one for his PC - see article on the forum at https://www.specnext.com/forum/viewtopic.php?f=6&t=895

It should be possible just to hook up to an external Raspberry PI for example and use a serial console connection allowing you to use the ZX Next as the keyboard... as the voltages match it should be fine just to connect the UART RX/TX and GND to the PI's PIN's 4/5/6 GND/TXD0-GPIO14/RXD0-GPIO15. See https://elinux.org/RPi_Serial_Connection

There is a diagram of the GPIO header here: https://elinux.org/RPi_Low-level_peripherals

Be aware of the differences with a Pi 3.

== Further Reading ==

For further information, see [https://www.specnext.com/the-next-on-the-network/ "The Next on the Network" at SpecNext.com] and in the TBBlue Distribution the file "\docs\extra-hw\wifi\WIFIand UARTReadME1st.txt"

ESP8266-01

2019-05-20T12:50:04Z

Daz: Added UART -f option as per https://www.facebook.com/groups/specnext/permalink/871158003241521/

A Wi-Fi module and Real Time Clock (RTC) were optional additions to the full cased Spectrum Next at the time of the original Kickstarter. They can be added to development boards and units that don't already have them. Although the RTC requires soldering components to the board, but the Wi-Fi module is a push-fit component.

== Hardware Requirements ==

Adding Wi-Fi to a board requires only a ESP8266 ESP-01 module. This supports 802.11 b/g/n at 2.5 Ghz including the WPA and WPA2 security protocols. The mounting point for the module is just behind the VGA port.

ESP modules have an updatable firmware. In general the standard firmware, should work out of the box with the Spectrum Next. If you're buying a module, check it has a standard firmware.

The Wi-Fi makes use of the on-board UART (Universal Asynchronous Receiver-Transmitter) of the Spectrum Next (you can use this without a WiFi module for serial connections as as well.) The UART on the Next board (built inside the FPGA logic) can control the RX/TX lines from 2400 bps up to 115200 bps (the default speed). The ESP module uses the "AT instruction set" of a typical modem and the official PDF is available here: https://www.espressif.com/sites/default/files/documentation/4a-esp8266_at_instruction_set_en.pdf

== Software Support ==

This information relates to [https://www.specnext.com/latestdistro/ TBBlue SD Distribution] 2.00.26 and later (2019-01-27).

The distribution contains dot commands (including "UART") and the "TERMINALS.BAS" program for working with the Wi-Fi module.

.UART is a simple DOT command that works in NextZXOS (and ESXDOS) to allow you to talk to a connected device which could be a Wi-Fi module. Due to the limitations of the 512 byte hardware buffer ,it can only be used for small amounts of data and is mainly intended to allow diagnosis. It does include a simple CIPSEND mode that allows connections to be made with an ESP Wi-Fi module.

UART.DRV is an interrupt driven driver (NextZXOS only) which can provide a 16K software buffer which means much less incoming data is lost. There is both a simple demo IUDEMO and a terminal program (not a DOT command) that provides an alternative to .UART that can handle much more data. This is intended for users of the port without the Wi-Fi module really but can be used to setup the ESP.

The TERMINAL.BAS program is much better than .UART and you will have better results following through some of the examples below.

You can also begin to play with the real feature of the Internet Toolbox which is the ESPAT driver for BASIC (again NextZXOS only). It can be used with the BASIC ESPTERM program to chat over an IP link and the ESPHTTP sample program shows how a web page can be retrieved from BASIC (but not rendered.)

The Source code to the IRQ stub is provided to allow the ESPAT code to be used in games that take over the machine, providing a gaming API.

Be sure to check out NXTel the Viewdata (Prestel/Teletext) terminal that allows the Next to connect and get news pages from Viewdata servers already online.

=== .UART ===

'''Key mapping'''

{|
|-
| Spectrum key || PS/2 Key || Action
|-
| EDIT || SHIFT+1 || Cycle output mode
|-
| CAPS LOCK || SHIFT+2 || On/off toggle (on by default)
|-
| TRUE VIDEO || SHIFT+3 || Debug mode for CIPSEND on/off (silent)
|-
| INV VIDEO || SHIFT+4 || CIPSEND mode on/off, also does an ATE0
|-
| GRAPHICS || SHIFT+9 || Change BAUD rate
|-
| DELETE || SHIFT+0 || Delete
|-
| SYMBOL SHIFT + SPACE || CONTROL+SPACE || Exit Program
|}

== Basic Connection ==

Run the .UART command, or better LOAD "TERMINAL.BAS" and RUN it.

First of all when you press ''ENTER'' you should get 'ERROR' because you didn't send a valid command to the ESP module. If you don't then it may be a number of things:

* You are using the TBU and firmware BEFORE 0.8 and NextOS 1.92 - if so this will only work at 3.5Mhz so slow the machine down and restart .UART.
* You are using a TBU and firmware with a Core .29 or greater, with an OLD copy of the .UART program which wrote the BAUD rate differently - if so when you cycle through the speeds (EDIT/SHIFT+1) you will find it may 'work' at 38400 - it is actually a fluke as the old value for that rate is quite close to the value needed for 115200 on the new system.
* Your module may have come with a default baud rate other than the 115200 of the Next. Using GRAPHICS (SHIFT+9) you can cycle through each option pressing ''ENTER'' until you see "ERROR!" (If you can physically see the module then many have a little blue light that flashes when receiving.)

If you believe the baud rate is set incorrectly on the module, from version 2.2e of .UART, there is a command to search all possible settings from about 4000 to 2.2M baud:

.UART -f

Once you have the module reporting 'ERROR' you should be able to type 'AT' and press ''ENTER''. That should give "OK".

Probably the first thing you want to do is tell the module to use the default speed of the next so type:

AT+UART=115200,8,1,0,0

and press ''ENTER''.

You now need to use GRAPHICS (SHIFT+9) to go back around to 115200 so that ''ENTER'' gives ERROR and AT ''ENTER'' gives OK again....

We just used one of the AT commands:

AT+UART=<baudrate>,<databits>,<stopbits>,<parity>,<flow control>

== Getting on the Network ==

Now to connect to a Wi-Fi access point:

First let's check that the system is in STAtion mode:

AT+CWMODE=?

This will give 1,2 or 3 (where STA=1, AP=2, Both=3). Mode 1 or 3 is fine but, more config is needed in mode 2.

Set the mode:

AT+CWMODE=1

List Access Points:
AT+CWLAP

To join an Access Point:
AT+CWJAP="wifinetwork","password"

Note that the module will retain the Wi-Fi connection and you can just do an AT+RST which will reset the module and give a CONNECTED and GOT IP.

Here are some more common AT commands:

{|
|-
| AT+CIFSR || Echo the current IP address on the network
|-
| AT+GMR || Echo the current versions of the software on your module
|-
| AT+CWQAP || Forget the WiFi network and password
|}

== Connecting to a Server ==

Let's try connecting to a server on the internet:

AT+CIPSTART="TCP","www.google.com",80

That is just the first stage and means there is now a pipe from the ESP to the Google server. Before it does anything you need to send it something. If you do feel brave before you close the connection then you can send:

AT+CIPSEND=7

at the ">" prompt which appears you should type:

GET /

These 5 characters need to be followed by a character 13-Carriage Return and a 10-linefeed. I.E. Just press return twice.

AT+CIPSEND=length allows you to get the ">" prompt and type 'length' characters. Incoming replies will be "+ IPD,length:" followed by the data (no space). Finally you will need to close down the connection:

AT+CIPCLOSE

This is very fiddly so .UART and TERMINAL include a mode called CIPSEND that does all the decoding for you.

If you press INV VIDEO (SHIFT+4) then the system will send an ATE0 to stop the ESP echoing everything and then anything you type will be sent followed by a Return and Newline.

You can also on TERMINAL use EDIT (SHIFT+1) to go into immediate mode, where everything you type is sent as you do it. In this mode to send a LF you need to Symbol Shift + ENTER after pressing ENTER (or SHIFT and 6 / down-arrow) to send a 10 / LF / Newline. This makes AT commands more complex but this mode is more useful to use the program as a traditional text terminal.

Anything the other end replies with will just appear. Note that at 14MHz you will get more text before the system begins to lose data due to the delays in printing what is received. Far more works on TERMINAL than .UART.

This mode is good enough to be a simple text terminal for a shell on a linux box or any test system.

If you connect to Google again and use CIPSEND mode then send four lines EXACTLY like this:

GET / HTTP/1.1\r\n
Host: www.google.com\r\n
Connection: close\r\n
\r\n

(where the \r\n represent what CIPSEND will do when you press ENTER)

Your screen will fill with the RAW data that makes up the very simple Google home page...

In order to get back to talking to the ESP you will now need to exit CIPSEND mode by pressing INV VIDEO (SHIFT+4) again.

== Connecting to a Non-HTTP Server ==

AT+CIPSTART="TCP","dict.org",2628

Should get you:

220 ..............some WELCOME.....

Go into CIPSEND mode with INV. VIDEO (SHIFT+4) and type:

DEFINE wn server\r\n

And you should get:

150 1 definitions retrieved
151 "server" wn "WordNet (r) 2.0"
server
n 1: a person whose occupation is to serve at table (as in a
restaurant) [syn: {waiter}]
2: (court games) the player who serves to start a point
3: (computer science) a computer that provides client stations
with access to files and printers as shared resources to a
computer network [syn: {host}]
4: utensil used in serving food or drink
.
250 ok [d/m/c = 1/0/18; 0.000r 0.000u 0.000s]

Now send:

QUIT

and you will get

221 bye [d/m/c = 0/0/0; 16.000r 0.000u 0.000s]

== Other Hardware ==

In addition to controlling the ESP-01 Wi-Fi module, the .UART command also provides facilities to use the serial connection port, either directly through some form of serial converter (e.g. a USB to TTL serial) or standard RS232 module (probably based on the MAX232).

A USB serial connection allows you to do all sorts of clever things - it is possible to connect up to a PC like this for transferring data. In fact if you were an early purchaser you probably bought one with your ESP-01 as it is the one needed to program it.

If you use one of the easy to get TTL modules then you can communicate with PC's and other older machines - E.g. a real Spectrum with Interface 1... KevB is using one for his PC - see article on the forum at https://www.specnext.com/forum/viewtopic.php?f=6&t=895

It should be possible just to hook up to an external Raspberry PI for example and use a serial console connection allowing you to use the ZX Next as the keyboard... as the voltages match it should be fine just to connect the UART RX/TX and GND to the PI's PIN's 4/5/6 GND/TXD0-GPIO14/RXD0-GPIO15. See https://elinux.org/RPi_Serial_Connection

There is a diagram of the GPIO header here: https://elinux.org/RPi_Low-level_peripherals

Be aware of the differences with a Pi 3.

== Further Reading ==

For further information, see [https://www.specnext.com/the-next-on-the-network/ "The Next on the Network" at SpecNext.com] and in the TBBlue Distribution the file "\docs\extra-hw\wifi\WIFIand UARTReadME1st.txt"

2MB RAM Expansion

2019-05-02T12:34:19Z

Daz: Initial version

An Issue 2 Spectrum Next has 1024Kb of RAM in two 512Kb modules, which can be expanded to with a further two modules for a total internal maximum of 2Mb.

The RAM modules known to work with a Next are:

* 71V424S10Y(G) by Integrated Device Technology, Inc (IDT).
* AS7C34096A-10JCN (10JIN) by Alliance Semiconductor Corp.

(Core version 0.7 fixed a timing problem with the memory access, this list assumes you have at least this version.)

'''IMPORTANT''': when fitting RAM note that the memory expansion sockets are slightly longer than the memory chip (40 pin sockets for 36 pin modules). This is because sockets of the precise size are no longer produced. The chip should be slotted into the left-hand side of the socket as shown here:

https://www.specnext.com/wp-content/uploads/2017/12/ram_final.jpg

Note the four connectors to the right (two on top and two on the bottom) are left empty, as the memory chip is aligned to the left. There is a small depression/hole in one corner of the memory chips. There is a cut out section on one corner of the sockets. These need to align.

NextZXOS shows the available RAM in the bottom corner of the start-up menu.

ESP8266-01

2019-04-30T15:30:32Z

Daz: WIP

A Wi-Fi module and Real Time Clock (RTC) were optional additions to the full cased Spectrum Next at the time of the original Kickstarter. They can be added to development boards and units that don't already have them. Although the RTC requires soldering components to the board, but the Wi-Fi module is a push-fit component.

== Hardware Requirements ==

Adding Wi-Fi to a board requires only a ESP8266 ESP-01 module. This supports 802.11 b/g/n at 2.5 Ghz including the WPA and WPA2 security protocols. The mounting point for the module is just behind the VGA port.

ESP modules have an updatable firmware. In general the standard firmware, should work out of the box with the Spectrum Next. If you're buying a module, check it has a standard firmware.

The Wi-Fi makes use of the on-board UART (Universal Asynchronous Receiver-Transmitter) of the Spectrum Next (you can use this without a WiFi module for serial connections as as well.) The UART on the Next board (built inside the FPGA logic) can control the RX/TX lines from 2400 bps up to 115200 bps (the default speed). The ESP module uses the "AT instruction set" of a typical modem and the official PDF is available here: https://www.espressif.com/sites/default/files/documentation/4a-esp8266_at_instruction_set_en.pdf

== Software Support ==

This information relates to [https://www.specnext.com/latestdistro/ TBBlue SD Distribution] 2.00.26 and later (2019-01-27).

The distribution contains dot commands (including "UART") and the "TERMINALS.BAS" program for working with the Wi-Fi module.

.UART is a simple DOT command that works in NextZXOS (and ESXDOS) to allow you to talk to a connected device which could be a Wi-Fi module. Due to the limitations of the 512 byte hardware buffer ,it can only be used for small amounts of data and is mainly intended to allow diagnosis. It does include a simple CIPSEND mode that allows connections to be made with an ESP Wi-Fi module.

UART.DRV is an interrupt driven driver (NextZXOS only) which can provide a 16K software buffer which means much less incoming data is lost. There is both a simple demo IUDEMO and a terminal program (not a DOT command) that provides an alternative to .UART that can handle much more data. This is intended for users of the port without the Wi-Fi module really but can be used to setup the ESP.

The TERMINAL.BAS program is much better than .UART and you will have better results following through some of the examples below.

You can also begin to play with the real feature of the Internet Toolbox which is the ESPAT driver for BASIC (again NextZXOS only). It can be used with the BASIC ESPTERM program to chat over an IP link and the ESPHTTP sample program shows how a web page can be retrieved from BASIC (but not rendered.)

The Source code to the IRQ stub is provided to allow the ESPAT code to be used in games that take over the machine, providing a gaming API.

Be sure to check out NXTel the Viewdata (Prestel/Teletext) terminal that allows the Next to connect and get news pages from Viewdata servers already online.

=== .UART ===

'''Key mapping'''

{|
|-
| Spectrum key || PS/2 Key || Action
|-
| EDIT || SHIFT+1 || Cycle output mode
|-
| CAPS LOCK || SHIFT+2 || On/off toggle (on by default)
|-
| TRUE VIDEO || SHIFT+3 || Debug mode for CIPSEND on/off (silent)
|-
| INV VIDEO || SHIFT+4 || CIPSEND mode on/off, also does an ATE0
|-
| GRAPHICS || SHIFT+9 || Change BAUD rate
|-
| DELETE || SHIFT+0 ||
|-
| Exit Program || Symbol Shift and Space together.
|}

== Basic Connection ==

Run the .UART command, or better LOAD "TERMINAL.BAS" and RUN it.

First of all when you press ''ENTER'' you should get 'ERROR' because you didn't send a valid command to the ESP module. If you don't then it may be a number of things:

* You are using the TBU and firmware BEFORE 0.8 and NextOS 1.92 - if so this will only work at 3.5Mhz so slow the machine down and restart .UART.
* You are using a TBU and firmware with a Core .29 or greater, with an OLD copy of the .UART program which wrote the BAUD rate differently - if so when you cycle through the speeds (EDIT/SHIFT+1) you will find it may 'work' at 38400 - it is actually a fluke as the old value for that rate is quite close to the value needed for 115200 on the new system.
* Your module may have come with a default baud rate other than the 115200 of the Next. Using GRAPHICS (SHIFT+9) you can cycle through each option pressing ''ENTER'' until you see "ERROR!" (If you can physically see the module then many have a little blue light that flashes when receiving.)

Once you have that you should be able to type 'AT' and press ''ENTER''. That should give "OK".

Probably the first thing you want to do is tell the module to use the default speed of the next so type:

AT+UART=115200,8,1,0,0

and press ''ENTER''.

You now need to use GRAPHICS (SHIFT+9) to go back around to 115200 so that ''ENTER'' gives ERROR and AT ''ENTER'' gives OK again....

We just used one of the AT commands:

AT+UART=<baudrate>,<databits>,<stopbits>,<parity>,<flow control>

== Getting on the Network ==

Now to connect to a Wi-Fi access point:

First let's check that the system is in STAtion mode:

AT+CWMODE=?

This will give 1,2 or 3 (where STA=1, AP=2, Both=3). Mode 1 or 3 is fine but, more config is needed in mode 2.

Set the mode:

AT+CWMODE=1

List Access Points:
AT+CWLAP

To join an Access Point:
AT+CWJAP="wifinetwork","password"

Note that the module will retain the Wi-Fi connection and you can just do an AT+RST which will reset the module and give a CONNECTED and GOT IP.

Here are some more common AT commands:

{|
|-
| AT+CIFSR || Echo the current IP address on the network
|-
| AT+GMR || Echo the current versions of the software on your module
|-
| AT+CWQAP || Forget the WiFi network and password
|}

== Connecting to a Server ==

Let's try connecting to a server on the internet:

AT+CIPSTART="TCP","www.google.com",80

That is just the first stage and means there is now a pipe from the ESP to the Google server. Before it does anything you need to send it something. If you do feel brave before you close the connection then you can send:

AT+CIPSEND=7

at the ">" prompt which appears you should type:

GET /

These 5 characters need to be followed by a character 13-Carriage Return and a 10-linefeed. I.E. Just press return twice.

AT+CIPSEND=length allows you to get the ">" prompt and type 'length' characters. Incoming replies will be "+ IPD,length:" followed by the data (no space). Finally you will need to close down the connection:

AT+CIPCLOSE

This is very fiddly so .UART and TERMINAL include a mode called CIPSEND that does all the decoding for you.

If you press INV VIDEO (SHIFT+4) then the system will send an ATE0 to stop the ESP echoing everything and then anything you type will be sent followed by a Return and Newline.

You can also on TERMINAL use EDIT (SHIFT+1) to go into immediate mode, where everything you type is sent as you do it. In this mode to send a LF you need to Symbol Shift + ENTER after pressing ENTER (or SHIFT and 6 / down-arrow) to send a 10 / LF / Newline. This makes AT commands more complex but this mode is more useful to use the program as a traditional text terminal.

Anything the other end replies with will just appear. Note that at 14MHz you will get more text before the system begins to lose data due to the delays in printing what is received. Far more works on TERMINAL than .UART.

This mode is good enough to be a simple text terminal for a shell on a linux box or any test system.

If you connect to Google again and use CIPSEND mode then send four lines EXACTLY like this:

GET / HTTP/1.1\r\n
Host: www.google.com\r\n
Connection: close\r\n
\r\n

(where the \r\n represent what CIPSEND will do when you press ENTER)

Your screen will fill with the RAW data that makes up the very simple Google home page...

In order to get back to talking to the ESP you will now need to exit CIPSEND mode by pressing INV VIDEO (SHIFT+4) again.

== Connecting to a Non-HTTP Server ==

AT+CIPSTART="TCP","dict.org",2628

Should get you:

220 ..............some WELCOME.....

Go into CIPSEND mode with INV. VIDEO (SHIFT+4) and type:

DEFINE wn server\r\n

And you should get:

150 1 definitions retrieved
151 "server" wn "WordNet (r) 2.0"
server
n 1: a person whose occupation is to serve at table (as in a
restaurant) [syn: {waiter}]
2: (court games) the player who serves to start a point
3: (computer science) a computer that provides client stations
with access to files and printers as shared resources to a
computer network [syn: {host}]
4: utensil used in serving food or drink
.
250 ok [d/m/c = 1/0/18; 0.000r 0.000u 0.000s]

Now send:

QUIT

and you will get

221 bye [d/m/c = 0/0/0; 16.000r 0.000u 0.000s]

== Other Hardware ==

In addition to controlling the ESP-01 Wi-Fi module, the .UART command also provides facilities to use the serial connection port, either directly through some form of serial converter (e.g. a USB to TTL serial) or standard RS232 module (probably based on the MAX232).

A USB serial connection allows you to do all sorts of clever things - it is possible to connect up to a PC like this for transferring data. In fact if you were an early purchaser you probably bought one with your ESP-01 as it is the one needed to program it.

If you use one of the easy to get TTL modules then you can communicate with PC's and other older machines - E.g. a real Spectrum with Interface 1... KevB is using one for his PC - see article on the forum at https://www.specnext.com/forum/viewtopic.php?f=6&t=895

It should be possible just to hook up to an external Raspberry PI for example and use a serial console connection allowing you to use the ZX Next as the keyboard... as the voltages match it should be fine just to connect the UART RX/TX and GND to the PI's PIN's 4/5/6 GND/TXD0-GPIO14/RXD0-GPIO15. See https://elinux.org/RPi_Serial_Connection

There is a diagram of the GPIO header here: https://elinux.org/RPi_Low-level_peripherals

Be aware of the differences with a Pi 3.

== Further Reading ==

For further information, see [https://www.specnext.com/the-next-on-the-network/ "The Next on the Network" at SpecNext.com] and in the TBBlue Distribution the file "\docs\extra-hw\wifi\WIFIand UARTReadME1st.txt"

ESP8266-01

2019-04-30T15:06:57Z

Daz:

ESP8266-01

2019-04-30T12:14:33Z

Daz:

ESP8266-01

2019-04-28T12:59:23Z

Daz: WIP

ESP8266-01

2019-04-27T14:26:07Z

Daz: Work in progress...

Palette Value (9 bit colour) Register

2019-04-26T15:15:31Z

Daz: "Enhanced ULA"

{{NextRegister
|Number=$44
|Readable=Yes
|Writable=Yes
|ShortDesc=Use to set 9-bit (2-byte) colours of the Enhanced ULA palette, or to read second byte of colour.
}}
Two consecutive writes are needed to write the 9 bit colour:
* 1st write: bits 7-0 = RRRGGGBB
* 2nd write: bits 7-1 are reserved, must be 0 (except bit 7 for Layer 2), bit 0 = lsb B

(to detect whether first or second write is expected, one can read bit 7 of {{NextRegNo|$03}}, in case your code is not aware of current state)

If writing the Layer 2 palette colour, in the second byte, bit 7 is "priority" bit. Priority colour will be always on top (drawn above all other layers), even on a priority arrangement like "USL" . If you need the exact same colour with priority and non priority, you will need to program the same colour twice, changing bit 7 to 0 for the non priority colour alternative.

After the write of second byte, the palette index is auto-incremented, if the auto-increment is enabled by {{NextRegNo|$43}}.

The read will always read the second byte of colour (%p000000B) and it will not modify the index.

The modified palette remains until a Hard Reset.

Emulators

2019-04-26T15:12:41Z

Daz: Added "Zeus"

{{EmulatorListTop}}

{{Emulator|name=CSpect
|author=Mike Dailly
|downloadurl=http://dailly.blogspot.co.uk/
|description=Emulates many features of the Next and includes an assembler
|os=Windows
|sourceavail=N
|supportsprites=Y
|supportlores=Y
|supportlayer2=Y
|supportopcodes=Y
|supporttripleay=Y
|supportsid=N
}}

{{Emulator|name=ZEsarUX
|author=César Hernández Bañó
|downloadurl=https://sourceforge.net/projects/zesarux/
|sourceurl=https://sourceforge.net/p/zesarux/code/ci/master/tree/
|description=A full feature emulator including a debugger - frequently updated to support Next updates
|os=Any
|sourceavail=Y
|supportsprites=Y
|supportlores=Y
|supportlayer2=Y
|supportopcodes=~
|supporttripleay=Y
|supportsid=N
|supportspecdrum=Y
}}

{{Emulator|name=NX
|author=Matt Davies
|downloadurl=https://github.com/next-dev/nx
|sourceurl=https://github.com/next-dev/nx
|description=An in-development emulator
|os=Windows / Mac
|sourceavail=Y
}}

{{Emulator|name=Zeus
|author=Design Design
|downloadurl=http://www.desdes.com/products/oldfiles/zeus.htm
|description=A PC cross-assembler which includes a Z80 emulator, which can emulate the ZX Spectrum 48K/128K hardware.
|os=Windows
|sourceavail=N
|supportsprites=Y
|supportlores=N
|supportlayer2=N
|supportopcodes=~
|supporttripleay=N
|supportsid=N
|supportspecdrum=N
}}

{{EmulatorListBottom}}

RTC

2019-04-26T13:48:49Z

Daz: Headings

A Real Time Clock (RTC) and Wi-Fi module were optional additions to the full cased Spectrum Next at the time of the original Kickstarter. They can be added to development boards and units that don't already have them, although the RTC requires soldering components to the board (whilst the Wi-Fi module is push-fit).

== Hardware Requirements ==

Adding a RTC requires the following components:

* 12pF Crystal
* DS1307 IC
* 8 pin DIL Socket
* CR2032 Holder
* CR2032 Battery

(6pF Crystals have been reported to work)

This is the mounting position on the PCB:

{| width=100%
|valign=top width=50%| [[Image:RTC_Port_Location.jpg]]
|valign=top| [[Image:RTC_Port.png]]
|}

== Software Support ==

The [https://www.specnext.com/latestdistro/ TBBlue SD Distribution] contains dot commands "DATE" and "TIME" for working with the RTC:

{|
|-
| .DATE "31/12/2017" || Set the date to new years eve
|-
| .DATE || Print the current date
|-
| .TIME "00:30:00:" || Set the time to 30 minutes after midnight
|-
| .TIME || Print the current time
|-
| .TIME -h || Print help message
|}

If you use these without a RTC soldered to the board they will just give an error that no signature is found or No ACK received. You can however use the option TIME -d to get the contents of the chip which will be junk if the RTC is not fitted but, but may help to diagnose any problems getting it working.

When the RTC is fitted, the date and time automatically appear in the NextOS menus. The ".ls" command will print a file listing with dates, and "cat exp" will show times as well.

You can get the contents of a dot command into a string using this NextBASIC:

DIM a$(100):OPEN #2,"v>a$":.TIME:CLOSE #2:PRINT a$

You can effectively "touch" a file in BASIC to update its timestamp with:

OPEN #4,"u>filename":CLOSE #4

The RTC is connected to the I2C bus. Also supplied is a DOT command called I2CSCAN - this will search the I2C bus for any devices found which can help in seeing what is connected. You should see at least one device at 0x68 if the RTC chip is connected. If you see others when you have nothing on J15 then make sure you have the latest TBU, any Capacitor mod etc - if so and you still have others detected then please contribute to the RTC posts on Facebook or the [https://www.specnext.com/forum Forum].

Further information, including ESXDOS support, can be found on the TBBlue Distribution in the file \docs\extra-hw\rtc\RTCI2CTIMEDATEreadme.txt

RTC

2019-04-26T13:27:58Z

Daz: Added dot commands

A Real Time Clock (RTC) and Wi-Fi module were optional additions to the full cased Spectrum Next at the time of the original Kickstarter. They can be added to development boards and units that don't already have them, although the RTC requires soldering components to the board (whilst the Wi-Fi module is push-fit).

Adding a RTC requires the following components:

* 12pF Crystal
* DS1307 IC
* 8 pin DIL Socket
* CR2032 Holder
* CR2032 Battery

(6pF Crystals have been reported to work)

This is the mounting position on the PCB:

{| width=100%
|valign=top width=50%| [[Image:RTC_Port_Location.jpg]]
|valign=top| [[Image:RTC_Port.png]]
|}

The [https://www.specnext.com/latestdistro/ TBBlue SD Distribution] contains dot commands "DATE" and "TIME" for working with the RTC:

{|
|-
| .DATE "31/12/2017" || Set the date to new years eve
|-
| .DATE || Print the current date
|-
| .TIME "00:30:00:" || Set the time to 30 minutes after midnight
|-
| .TIME || Print the current time
|-
| .TIME -h || Print help message
|}

If you use these without a RTC soldered to the board they will just give an error that no signature is found or No ACK received. You can however use the option TIME -d to get the contents of the chip which will be junk if the RTC is not fitted but, but may help to diagnose any problems getting it working.

When the RTC is fitted, the date and time automatically appear in the NextOS menus. The ".ls" command will print a file listing with dates, and "cat exp" will show times as well.

You can get the contents of a dot command into a string using this NextBASIC:

DIM a$(100):OPEN #2,"v>a$":.TIME:CLOSE #2:PRINT a$

You can effectively "touch" a file in BASIC to update its timestamp with:

OPEN #4,"u>filename":CLOSE #4

The RTC is connected to the I2C bus. Also supplied is a DOT command called I2CSCAN - this will search the I2C bus for any devices found which can help in seeing what is connected. You should see at least one device at 0x68 if the RTC chip is connected. If you see others when you have nothing on J15 then make sure you have the latest TBU, any Capacitor mod etc - if so and you still have others detected then please contribute to the RTC posts on Facebook or the [https://www.specnext.com/forum Forum].

Further information, including ESXDOS support, can be found on the TBBlue Distribution in the file \docs\extra-hw\rtc\RTCI2CTIMEDATEreadme.txt

RTC

2019-04-26T12:36:16Z

Daz:

RTC

2019-04-26T12:34:37Z

Daz:

RTC

2019-04-26T12:33:39Z

Daz:

RTC

2019-04-26T12:30:53Z

Daz:

RTC

2019-04-26T12:29:58Z

Daz: Components required for adding a RTC.