These are Updated versions of the TIME, DATE and RTC.SYS files from:

https://gitlab.com/victor.trucco/RTC

This 3.4 release includes .TIME Version 3.4 - we will keep them in step now

They have been debugged and adapted for the ZX Next by Tim Gilberts
This is the third Public BETA release but, they have been tested...
The ASM is now modified to assemble with z80asm from Z88DK.

They operate as DOT commands so just place DATE, TIME and I2CSCAN in
the /DOT directory (and in the /BIN if you want to use ESXDOS)

See later for how to use a suitable RTC.SYS.

If you use these without a Real Time Clock (RTC) soldered to the board
they will just give an error that no signature is found (RTCSIG.SYS) or
No ACK received (RTCACK.SYS)

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, may help to diagnose
any problems getting it working.

You can use the DATE and TIME commands without RTC.SYS to just set and
query the date and time respectively.  They expect the RTC to be in
24 hour mode and make use of the last two RAM storage locations, so do
not use these.  Any write of a DATE or TIME will set the signature.

If you place a file called RTC.SYS in the 'NextZXOS' folder then from 1.92
onwards all files you create or update from then on will contain a date
and time if the clock contents are valid. It does not have to be the
correct time and date just valid in the range of 2000-2099.

This will also make the date and time appear in the NextZXOS menus
automatically.  If you do not wish to use them or time stamping without removing
the chip then you can rename or remove RTC.SYS from the relevant folder or use
TIME -di to wipe the signature - if using RTCSIG.SYS.  You have to remove or
rename the RTC.SYS file if you are using RTCACK.SYS.

If you want the same facilities in ESXDOS then place a file called RTC.SYS
in the /SYS directory (the RTCESX.SYS version is compatible with both OS).
Note this will only work with ESXDOS 0.8.6Beta2 and above.  ESXDOS does
not change the date and time on update I belive only on create.

Option -h is available on both commands to show you the simple syntax.
The strings for date and time must now use quotes to be valid.

e.g.

.DATE "31/12/2017"  	- will set the date to new years eve.

.DATE			- will just print the current date

.TIME "00:30:00:	- will set the time to 30 minutes after midnight

.TIME -h		- will print its help

.ls			- will display the dates of files on NextZXOS/ESXDOS

cat exp			- Will give the time stamp as well on NextZXOS

Notes on the physical devices
-----------------------------

Note that the specification sheet asks for a Crystal of 12pF - The author
has one at 6pF and it seems to perform - YMMV.

The Author has several DS1307 chips and NOT ONE OF THEM allows RAM location
0x15 to be written - THIS MAY BE A BUG in the i2csystem - feedback is encouraged
(on the other hand it could just be cheap chips).

Using commands from BASIC
--------------------------

You can get the contents of a dot command into a string using this clever
trick in NextBASIC from Mr Garry Lancaster:

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

Then you can use string commands to cut out whatever bits you want!

You can effectively "touch" a file in BASIC with  OPEN #4,"u>filename":CLOSE #4

Equally there is now a .$ command in NextZXOS that allows you to pass a variable
to a dot command so you could pass parameters to the time dot commands.

ESXDOS Support
--------------

These commands do work with ESXDOS Beta 2 onwards (including the final release)

http://www.esxdos.org

Note that only the RTC.SYS file can in SYS can be used as there is a size limit
of 256 Bytes. It is based on RTCSIG so you can only use the DS1307 chip.

Other RTC clocks
----------------

As of TIME version 3.3 there is LIMTED support for a DS3231 module to be
connected to the I2C bus on the J15 GPIO pins.

(You can of course connect a DS1307 based module there as well if you want
to do less soldering on your board as only four connections are needed)

This has to be done the hard way; setting and reading registers by hand as
there is no RAM, a signature cannot be used. Counts and Register addresses
are in Hex but time is BCD so human readable.

So:

time -w00SSMMHHWWDDMMYY

will set the Seconds,Minutes,Hours,Dayofweek,Day,Month,Year

and

time -r1300

will read the status of the 19 regsiters 00-06h Time, 07-0dh Alarm, 
0E-10h Control and 11h/12h MSB/LSB of Temperature

In order for NextZXOS to recognise the time from this module for its
clock and timestamping of files you need RTCACK.SYS and a version
of NextZXOS that supports 512Byte SYS modules i.e. >=1.94c.

The default RTC.SYS in the NextZXOS folder is a renamed copy of RTCACK.SYS
which uses only the ACK on the bus for detection and some sanity checks
on the numbers returned.  This version works with the DS1307 as well.

The RTCACK.SYS and RTCSIG.SYS for NextZXOS also now both support returning
actual seconds in H (in addition to the two second resolution of the MSDOS API)
and 100ths if available in L (set to 255 if the resolution not available).

WARNING: These versions of RTC.SYS DO NOT WORK ON ESXDOS only NextZXOS
which of course implies that the DS3231 is only supported on NextZXOS
leaving the old RTC.SYS (a renamed copy of RTCESX.SYS) installed on
ESXDOS should not affect the DS3231 module - you will just not get
timestamps.  You can use Victor's original code as it should work with
both chips I think as it does no checks but, you will only get DATE stamps
and not time.

Utilities
---------

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.
The DS3231 module may have a fan out extender so you may also see a device
at 0x57.  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 Forum.

You can also use the .TIME command to see the output from the NextZXOS RTC API
using the -n option - this should be substantially the same as the figures
for BC and DE calculated by the .TIME -d command - which prints a full debug of
the RTC chip and calculates the relevent DE,BC values that result ignoring any
signature or Ack errors.

They may vary as at least a second or so could have elapsed even if you do

cls:.time -d:.time -n

This feature will obviously have an indeterminate effect on ESXDOS. HL is also
shown so you can see the results of the seconds and 100ths return.  Note that HL
will be junk on -d as .TIME does not support that feature.

