Apple /// Horses Demo

The most widely known demo for the Apple /// is the 'Running Horses' demo. The Horses demo is one of a suite of demos included on the 'Apple3 System Demonstration' disk. Here is a screenshot of it running in MAME:
 

You can grab the original demo disk image from here: Apple3SystemDemo

And you can run it here on the Internet Archive: Apple_3_Systems_Demonstration_Disk
(You'll need to be patient, the horses part is after all the graphs)
 

This was written by Andy Hertzfeld, and used the downloadable fonts of the Apple /// to help do the heavy lifting. The main code is contained in an 'invokable module' that can be loaded in with Business Basic and called by Basic programs. I have been interested to see how it was done, so decided to dig into the demo and see what makes it tick. Lets see what we find.


The first part was to look into the basic program side of the demo. The Invokable module is loaded in by the 'HELLO' Basic program which contains this line:
  95   INVOKE "bgraf.inv","Horses.inv"

This tells Business basic to load these files from disk into memory, relocate the code, and setup the entry points for each of the procedures/functions included in each of them. The "Horses.inv" is the one that includes the main code for the demo.

Next, the actual basic code that creates and runs the demo, is included in the 'SHOW' file:

  9000   REM ---  Now run the horse race! ---   
  9005   PRINT CHR$(16);CHR$(1);
  9010   PERFORM hinit
  9020   PRINT CHR$(15);
  9030   FOR a=1 TO 20
  9050     FOR i=0 TO 4
  9070       PERFORM hframe(%i)
  9090       NEXT i
  9110     NEXT a
  9120   FOR lap=1 TO 40
  9125     secs=.007*(20-lap)+.01
  9130     FOR i=0 TO 4
  9150       PERFORM hframe(%i)
  9170       PERFORM hscroll
  9190       IF secs>0 THEN GOSUB 350
  9210       NEXT i
  9250     NEXT lap
  10000   TEXT:HOME
 
The line 'PRINT CHR$(16);CHR$(1);' is the .CONSOLE drivers code for setting the display mode to 40x24 color. This is a 40 column text mode that each character can have its foreground and background colors set from any of 16 colors.

Next we need to look into the 'Horses.inv' module. This must have the code for the three functions, hinit, hframe and hscroll that the basic program uses. The first thing I did was to extract the horses.inv file from the demo disk and have a look with a hex editor. This led to an interesting find, there was some text in there that looked like the initial part of the source code:

Here it is taken out, looks like the source code has the date of 9/4/1980 on it, so just over 40 years ago!!

     .PAGE
 ;
 ;-----------------------------------------------------------------------
 ;
 ;    "Horse Demo"  Invokable Module for Business Basic
 ;
 ;           by Andy Hertzfeld  09/04/80
 ;
 ;----------------------------------------------------------------------
 ;
     .PROC   HINIT
 ;
 ; First get the device number of the console
 ;
     BRK
     .BYTE   084             ;GETDEVNUM SOS call
     .WORD   DEVBLOCK
 ;
     LDA     CDEVNUM
     STA     WDEVNUM         ;Update the device number
 ;

Next step was to disassemble the code. This proved somewhat difficult as the modules are assembled into a Pascal PCD file which also includes relocation and linker info. I tried to decode that, but will need some more work before I understand that fully. I ended up extracting the code block and disassembling with SourceGen (That Fantastic Disassembler from Andy McFadden). Using that as a start, I was able to trap it in Mame and then dump it from memory after it had been relocated and loaded by BusinessBasic. After quite a bit more work, I was able to take the reconstructed source, assemble it with the A3 Pascal assembler, and successfully use it to run the demo!


Here is a summary of the functions included the Horses.inv invokable module.

HINIT
Loads the text screen memory with the grid of character codes for the horses and loads the colorful foreground/background colors. Each horse consists of 8 characters wide x 4 lines. Codes 00 - 31 are used with the high bit set, so $80 to $9F.

HFRAME(frame)
Takes the frame number as input and then downloads updated font data based on this. Frame=0 is the only frame with all 32 characters included and is the first frame set. The others only update the required characters that change for each animation frame. See pictures below for each frame (8 x 4).
This uses a SOS Device Control call to the .CONSOLE device to load up to eight characters font data at a time.

HSCROLL
Moves the text screen bytes across one character with wrap around. Steps through each line from 1 to 24.



Now we have the source code rebuilt and preserved for this classic Apple /// demo. I have tried to add enough comments to understand the code. Let me know if you have any feedback.


You can grab the disassembled source code from github here:
https://github.com/robjustice/Apple3/tree/master/horses

There is also a bootable disk image on there with the source code included, the assembled invokable module, and the basic program to run the Horses demo. Boot it up, and then type 'run horsedemo'

Enjoy!

Resurrecting Apple /// SOS copy protected disks

There are a few Apple /// disk images around that won't work due the SOS copy protection failing. I described this in an earlier post, and its due to the volume numbers for specific sectors not matching with the ones that SOS is expecting. The dsk/po disk format does not include this information, just the sector data itself. So they are never going to be able to work for SOS protected disk images.

As an example, the Apple3SystemDemo.dsk disk image on apple3.org, will not boot and gives 'SYSTEM FAILURE = $06'

I did find a reference to this error code in the Apple /// technotes, see:
 TA32241 Apple III: System Failure Errors

  "Copying certain protected diskettes will cause an error $06 when the copy is booted. This
  is a normal effect of the protection scheme."

This is an interesting way of way of saying if you copy it, it's not going to work.



To resurrect these disks, there are two possible ways we could achieve this:

1. Convert the disk image to a format that includes the necessary information to look like the original disk.
2. Read in the SOS.INTERP file and then decrypt it with the known SOS key, and then write it back out to disk.

I decided to have a look at the first option. I'll try and come back to the second option at a later date.

There are two things we need to achieve to satisfy the SOS copy protection, the specific volumes numbers, and synchronisation of the tracks. The synchronisation is needed as SOS reads the first specific track/sector to get the first key/volume number and then just steps to the next track and reads the first sector it finds. At the last track, the sector number that is found and read first is compared with the expected one and if it does not match, then the protection check fails.

We now have available the woz disk image format that will work perfectly for this. If we image the original disks directly to woz format, then they work correctly. (thanks Jorma for imaging Apple /// software to woz format)

But what about our disk images that we do not have the original disk for. If we had a way to convert the dsk image to a woz format and add back the required volume numbers and track synchronisation, then we should be able to get a working disk image. I remembered reading that someone had written a dsk2woz program to do this exact thing (thanks Tom). All we need to do is modify it to meet the requirements needed for the SOS protection check.

Step 1 - add the volume numbers

The first thing to add are the volume numbers we need. I looked back at the previous blog post and this is the list, the first value is the required volume number.

VISIKEY:    .byte $7C      ;track 16, Sector 6
            .byte $BD      ;track 15, Sector 10
            .byte $BD      ;track 14, Sector 14
            .byte $9B      ;track 13, Sector 2
            .byte $F3      ;track 12, Sector 6
            .byte $E4      ;track 11, Sector 10
            .byte $C1      ;track 10, Sector 14
            .byte $B4      ;track  9, Sector 2

There is a part of the code in dsk2woz that builds the bitstream for each track. It just adds 254 as the default volume number for each track/sector. I then updated the code in this part to check if its one of the track and sectors in the list, and then add the expected volume number for these. Other wise, we just put in the default value for the volume number.

I converted the dsk image and then tried this in MAME to see if it would load. It still gave the same System failure $06 error. The synchronisation part needed sorting out now.

Step 2 - add the correct positioning of the tracks with respect to each other

dsk2woz builds each track with the sector data in the same order and position, as usually we don't need to worry about any special track alignment for non protected disks, so we end up with all tracks the same.

To check what SOS is getting when we boot this disk up, I referred back to the listing of BFM_INIT2 module. Looks like the check is done at the end of the key reading and its looking for sector number 06

00B8F3  1  A5 98            LDA       SECTOR
00B8F5  1  C9 06            CMP       #ENDSECT      ;TRACKS SYNC'ED?
00B8F7  1  D0 08            BNE       NOTPROT

Next was to startup MAME with the debugger active and set a break point at $B8F5 and see which sector is actually getting read. Turns out it was reading sector number 3.

Then I needed to add into dsk2woz some different alignment of the track data. The trackdata in a woz is the complete bitstream, and the length of the actual data is 6288 bytes long in the dsk2woz generated woz file tracks. All we really need to do is rotate the data for each track after its been prepared, before writing it out to the woz file. We will also need to keep track of this offset, so the next track is offset from the last tracks starting position and then 'rotated' by the same amount.

I added this to the code, and then just picked an arbitrary value of 600 bytes to shift the tracks by. Sure enough, SOS found a different sector, but not the correct one. I ended up just using trial and error to work out the offset needed to get SOS to end up reading the correct sector number at the end. There was around 400 bytes of range that resulted in the correct one being read, so i settled on a value in the middle of the range that worked.

The end result was the disk I started with now successfully boots now in MAME using the created woz file!

The converted file is available here Apple3SystemDemo.woz

The updated dsk2woz program is available here a3dsk2woz

Summary

This method will give the ability to run some disks in the emulator now, that have not been able to be run from the dsk images due to the copy protection info missing. I don't think we are missing any of this software, but its been an interesting project to see if this was possible. It also shows the beauty and power of the woz file format and how it caters for so much more than we have had before. Thanks John! and thanks to the MAME team for adding woz support in.

Apple /// Drivers, and a new way of cross compiling them

This is a bit of a long lead in story, its been awhile since I have done a blog update..

It started out when I was thinking about the Apple /// bootup and wondering about a small file selector that could be used, something like Selector ///. I had some ideas that if we had a tiny one like ProDOS Bitsy Bye, then maybe we could build that into SOS. I don't think the source code is released yet for Bitsy Bye, maybe in the future it looks like this will happen. I did some looking around and came across a ProDOS one called Squirt.

I then started to 'port' this over to SOS for fun. One bigger change was the move for the screen output from  direct video memory manipulation and A2 rom calls to using the SOS .CONSOLE driver. Like everything, its always a lot more work. The other part was mapping the ProDOS calls to SOS calls. These have some differences, more than I was expecting as ProDOS's calls are based on the SOS calls. It has a lot more to go, so not much use yet. You can view volumes online, navigate folders, and view text files. I was next going to add viewing A3 fonts, and that's when the story runs off on a tangent...

I thought I would use the .GRAFIX driver for the graphics output. Well, this had me stuck. I kept getting a device error ($30) back when ever I tried to send commands to it. I can open the .GRAFIX driver ok, but nothing more. I spent quite some time searching for info on what this error might be, and trying other things. There is an invokable module called bgraf.inv that works fine with the .GRAFIX driver. I did a test in Business Basic with this and all works as expected. So it must be possible to get it to work.

After some searching through the aIII wap dvd again, I found some very useful driver disassemblies in the 3's company BBS files. In there was one for the .GRAFIX driver. This has some clues, it seems there is some SOS global flag for memory allocation that the .GRAFIX driver uses, but this needs to be set by the calling program. I still have not got back to this, but this seems the main reason it was not working.

I have put up a disk image and the current source code for Squirt3 on github here:
 robjustice/Squirt3
For anyone interested to have a look. I'm not sure when I will put some more time into this, but it was a great learning exercise with what I have done so far.

Somehow while looking at the .GRAFIX driver source, I rekindled an old thought on trying to get a relocatable file format converted for use as a Apple /// driver, to help with cross platform development. I had come across the o65 file format and this looked like a possibility, and the ca65 assembler supports this. I have been trying to learn Python more, so this looked like a good fit. I had also helped with some debugging of the Driv3rs program, and this also helped understand the driver file format. (thanks Guys)

The o65 file includes the code and relocation information to allow the file to be loaded and relocated, similar to the PCD file that the Pascal assembler creates. The Apple 3 System Utilities SCP program takes the PCD files and converts these to a raw format. The SOS 1.3 source code contains in file SOSLDR.C.SRC.TEXT a brief note on this:
                           
  * SOS.DRIVER FILE FORMAT
  *
  *  (8)  LABEL
  *         = "SOS DRVR"
  *
  *  (2)  HEADER COUNT
  *         = # OF FLOPPY DRIVES
  *         = CHARACTER SET TABLE
  *         = KEYBOARD TABLE
  *       ...
  *                                                 +---------------------------------------+
  *  (2)  DM #N TITLE COUNT  <---+                  !       RELOCATION FIELD FORMAT         !
  *             TITLE FIELD      !                  !       -----------------------         !
  *  (2)     DM #N CODE  COUNT   ! DRIVER MODULE #N ! CONSISTS OF A LIST OF 2 BYTE POINTERS !
  *             CODE  FIELD      !                  ! WHICH POINT TO THE LOW BYTE OF A TWO  !
  *  (2)     DM #N RELOC COUNT   !                  ! BYTE QUANTITY TO BE RELOCATED.        !
  *             RELOC FIELD  <---+                  +---------------------------------------+
  *       ...
  *
  *       $FFFF = THE END

Explaining this a little more, for each of the drivers, they have the following:
  word - length of the comment
  bytes - comment
  word - length of the code
  bytes - code
  word - length of the relocation table
  bytes - list of addresses that need relocating

The program I have written decodes the input o65 file and converts it to this Apple3 driver format consisting of the three parts.

The latest version of the program is available here:
 robjustice/a3driverutil

There is some more detail in the readme there of the various functions available and how to run it. I have added a few more than I initially thought, so it has a bit of SCP functions in there now to add/list/extract drivers.

This allows a driver to be assembled with the ca65 assembler and then added or updated to a SOS.DRIVER file. With the use of a disk image util, then this process can be automated in a script to allow one command to do driver assembly, updating in a SOS.DRIVER file and launching in an emulator.

One other function it includes that I wanted to talk about here, is extracting a driver from a SOS.DRIVER file. I have done some disassembly of a few drivers and wanted a nice easy way to get the code out. While doing this I found that without 'relocating' the code, the origin of the code is address 0000. I found that this causes confusion with zero page locations and instructions when disassembling. To get around this, I have added the option of extracting and relocating the code to base address $2000.

hope you enjoy this.

Apple /// Copy protection - some further investigation

I did some further reading and it seemed that the On Three Uncopyprotect driver would also work for Apple Writer /// (version3.0). I found a copy of the disk images for this on the apple3.org website and booted up the first disk, AppleWriter30MSTR.dsk, in Mess. It failed to start, but came up with a different error message than Visicalc,  SYSTEM FAILURE = $06.

I then used the SCP and added the uncopyprotect driver to the disk image and then booted it again in Mess. This time success!

AppleWriter /// is using the same inbuilt copy protection and the same key as Visicalc. Interesting that it gives a different error. This would depend on the the jump taken in the still encrypted sos.interp file after the protection validation has failed. I traced with the Mess debugger and it jumps to the NMI handler routine, and then jumps to the system death routine which gives the above error.
I have seen this error for other disk images and had wondered why they gave that error. Looks like it could be due to copy protection failing for the disks.

I did some more searching and there is a copy of AppleWriter /// v4.1 in the WAP disks (APPLE-3-WAP-wdp-01a.dsk), and this one is not copy protected. So that's the easiest option to get it running and avoid this problem. Though we really need some NIB or better format images of the original v3.0 disks to preserve them in running condition.

Another disk image that I have seen reported before as broken, is the Apple3SystemDemo disk. I downloaded the disk image of this from apple3.org, Apple3SystemDemo.dsk and booted it in Mess. This also gives the same SYSTEM FAILURE=$06.

I then thought I would try to copy in the uncopyprotect driver to the disk and see if this would also work. One catch though, from the disassembly in the previous blog entry, it needs SOS1.3 to work, and this disk has SOS1.1 on it. I used the Apple3SystemUtilities to copy over the SOS1.3 and driver file with the uncopyprotectdriver on it. (for some reason Ciderpress complains about a damaged directory entry, so i had to do this the long way)

With the new sos.kernel file and the sos.driver file, the disk actually boots. but.. then gives an error about a sos call. I suspect this is due to the change from SOS1.1 to 1.3. The uncopyprotect driver did however, help to successfully decode the sos.interp file (which is business basic) and was able to run it. It must therefore use the same protection key as the other programs. I think this also means that SOS 1.1 had the same copy protection support built in.
 

The easier way to fix this would be to copy in a unprotected version of the Business Basic sos.interp into this disk. I used the Apple3SystemUtils disk and copied one over from a working Business basic disk. Success, the demo works now, here is the classic running Horses :-) (disk image here)

It looks like Apple used the same protection Key for Visicalc, AppleWriter, and this demodisk. I would have thought they may have used individual ones for each program, but seems this is not the case. Also looks like if any disk gives these errors, then it may be due to copy protection failing.

Apple /// Advanced Visicalc and an interesting discovery

I recently purchased a copy of the Apple /// version of Advanced VisiCalc on ebay. It has since arrived and is a nice and complete setup, with the manual, command helper sheet, pocket reference and two sets of disks.

I went to look for some disk images to have a quick play with it on the Mess emulator. I could not find any in any of the usual places, but did remember seeing it in the apple3rtr package. So some time later and some reading of the manual, I was quite impressed at how many features it had back then compared to what I am used to with the current version of Excel. Although no mouse support, so lots of key commands to learn.

I then thought I would image the disks that came with the package, with some suspicion that there might be some copy protection involved. My goto setup for imaging is ADT using my IIc, as this can be setup/removed on my desk quickly. I then tried the newly created disk images on the Mess emulator, and looks like there is some copy protection as the program will not run. SOS boots ok, and then when the application goes to run (sos.interp), you just get the following screen.

I did some basic comparison of the sos.kernal file (v1.3) to check it is not changed, and it was the same as others I had, so not that. I started Mess with the debugger enabled and looked to find out when SOS jumps to the interpreter, and then see what happens there to look for any clues. A quick look at the SOS source code to find a starting point and address $1EB0 is the address in SOS that it jumps to the interpreter. (in sosldr)

That jumped to $2007 (in the sos.interp for Visicalc), which contains an indirect JMP to the address at $FFFC. This turns out to contain address $E833, this looked to be within SOS. A further look through the SOS source code and we find that's the SOS system Cold Start routine, which is what we end up with when we run with the copied disks.

Something strange going on here. It all boots as described in the SOS manuals, but just ends up at the cold start routine.

I left it there, as I remembered the On Three 'uncopyprotect' driver. It allows Visicalc to run and bypass the copy protection. I wonder what this could be doing, it may give some clues. I then ran the SCP and added the uncopyprotect driver to the VisiCalc Loader disk image, and then the disk boots up fine.

So what does this driver do to bypass the protection. I then did a disassembly of the uncopyprotect driver. This takes a little bit to extract the relocatable code part and disassemble, the details for that will be for another blog post.

It was a very small driver so not too much work to decode. The disassembly listing is here uncopy.asm It still needs some finishing off, but the big clue is that it patches the SOS BFM_INIT2 module (bfm_init2.lst). This is very interesting as I had not looked at this in detail, but seems SOS has some copy protection support built in to the operating system! Sounds very similar to some discussion papers that surfaced recently on SSAFE!

The BFM_INIT2 module is run as part of the SOS loader during startup. The module reads the disk from Track 9, Sector 2, and grabs the volume number from the sector. It then waits a set time and seeks to the next track, reads a sector, again grabbing the volume number. And so on until Track 16. It then checks if the last Sector read was 6, and errors if its not. So it needs the sectors synchronized on the disk! (and the volume number preserved, so a DSK image was never  going to work) This leaves us with an 8 byte Key made up of 8 volume numbers, one read from each track. It then uses this key to decrypt the sos.interp file in memory, and then does some modification of the start pointer and then runs the interpreter.

A look back at the uncopyprotect driver and it has the specific Key hardcoded into it for visicalc. And the driver patches it into SOS when the driver is initialised. Then when Visicalc is run, SOS thinks it has read the correct key and decrypts and run Visicalc ok.

To summarise things:
- SOS has copy protection support built into the operating system (aka SSAFE)
- For programs using the protection, the sos.interp file is encrypted with a key stored on the original disk
- SOS uses eight volume numbers stored across eight track/sectors to 'hide' the key- The tracks are read in sequential order via a timed routine, and this expects a particular sector to be read on the last track, so they must be synced!
- When the disk is booted, the key is read and then the sos.interp file is decrypted with the key, and then run.
- without the key, the software cannot be decrypted and run!

I wonder how many other Apple /// software packages used this support. I could see it possible to read the key from the original disk and decrypt the sos.interp file and then make a new disk with this on it. Then the software would be permanently unprotected. This may be worthwhile if there are a few disks that have this protection used.

Wow, not how I thought this journey would have ended.

Update with additional info:
NIB image of the original disk: AVCLOADER.NIB
Volume numbers extracted from the NIB image: Volume Number list

Link to AppleSSAFEProject Documents

RetroChallenge_201610 #2

Sometimes you need to read the manual...

The idea I was thinking of was to be able to enter the music notes and the lyrics either directly into the basic program, or enter them as a text file and have the program read it. I think I'll use this as a good easy song to start with. :-)

    
Then have a file something like this, notes, then duration, and the lyrics lined up possibly to get the timing.
   c.5 c.5 d1    c1  f1 e2  c.5 c.5 d1    c1  f1 e2  
   Hap-py  birth-day to you Hap-py  birth-day to you

I need to try and work out some ways to transfer the music notes to the speech to bring the tune into it. And play with some of the other features of SAM to see what adds to this. First thing was to enter the text and convert using the new function on my driver. The first line converted to phonemes ends up like this.
   /HAEPIY BERTH DEY5 TUX YUW

SAM supports setting the pitch, the standard pitch used is 120 in the examples, so the first thought was to make this C, and then add 10 for each note. ie D becomes 110, E = 120, and so on. rolled out, it becomes like this.
   "#P120"   (C)
   "/HAE"
   "#P120"   (C)
   "PIY"
   "#P130"   (D)
   " BERTH"
   "#P120"   (C)
   " DEY5"
   "#P150"   (F)
   " TUX"
   "#P140"   (E)
   " YUW"

Well, here is how that sounds, not to good at all.
Happy1.mp3

Now remember the opening line of the blog, a quick look at the SAM manual and it looks like the pitch is the other way around, smaller value is higher pitch.
   PITCH
   00-20 impractical
   20-30 very high
   30-40 high
   40-50 high normal
   50-70 normal
   70-80 low normal
   80-90 low
   90-255 very low
   default = 64

A quick swap around and this was the modified test program:

and this was the result. Still not to good.
Happy2.mp3

SAM supports adding a stress value after the phoneme to add some expression. From the manual:
   1 = very emotional stress
   2 = very emphatic stress
   3 = rather strong stress
   4 = ordinary stress
   5 = tight stress
   6 = neutral (no pitch change) stress
   7 = pitch-dropping stress
   8 = extreme pitch-dropping stress

I then added a value of 5, need to have a play with these more, they might be quite useful.
This was the modified test program with an arbitrary stress value after the last phoneme:

and this was the result. Not to sure if this is better, I think it is improving.
Happy3.mp3

Then the next thing was to extend the words, based on timing. I did this by just repeating the phonemes. Although the last word 'you' should probably be extended more, but it does not sound to good like that. Need to try some other ideas for it.
This is the test program with these changes:

and here is the result, its starting to get there!
Happy4.mp3

I need to play some more with this, but I have some ideas now on how to translate from the music/lyrics to SAM.

RetroChallenge_201610 #1

Time to get started on this challenge!

To be able to work with and manipulate the speech output, I need to work with Phonemes, rather than plain text. This will allow me to extend the words and 'hold a note' for longer (or sing!). But working with them would take a lot of manual work to convert them from the text of the song lyrics. So the first thing I want to do is extend my Apple/// SAM driver to help with this.

First, some background on SAM. The original SAM software came with two binary programs, SAM and RECITER.

SAM is the actual speech program that takes Phonemes as input, and outputs speech from these through the 8 bit DAC card. Phonemes are speech sounds made by the mouth. Put together these make up words or speech. The full list of Phonemes that SAM supports are available in the user manual, linked here:

SAM Owner Manual

As an example, to say "Hello There" would need the following input " /HEHLOW DHEHR" to SAM.

The other program RECITER takes plain text as input and using rule based conversion, converts these to Phonemes. It then passes the output to SAM to speak them. Reciter has a large table of rules that it uses to look at letters preceding and after to work out the Phonemes it should use. Some of these are for specific words, and some are building blocks, eg sounds for word. I just noticed it has a table entry for Atari! ".ASCII "(ATARI)=AHTAA4RI""


My Apple/// driver implementation is done as a SOS character mode driver. A character mode driver supports reading and writing character strings. Currently I have two 'sub' drivers implemented, .SAM to support Phonemes, and .RECITER to support plain text.

For both of these 'sub' drivers, you first open them. And then just write a string to them, and they will speak the string. To check for errors, you can read from these, and the error code is returned. If its 255, then all went ok. Other wise, it will return the character position in the string where the error occured. eg when an incorrect phoneme is found.

What I want to be able to do is after the .RECITER has converted the plain text to Phonemes, I want to be able to read this back. The way i will implement this is to detect when a second read occurs, then return the converted string.

I have added a variable to monitor the number of reads:
  READNUM     .BYTE   000     ;flag to determine number of reads after write, 0=none
Whenever a write occurs, I will clear this back to zero:
  SPEAK       LDA     #000
              STA     014FC               ;disable extended indirect addressing for FB/FC
              STA     READNUM             ;clear previous reads number
              LDA     EReg
           
Then in the READ part, i have added a check and then either return the error code for the first read
or return the converted string.

  $010        LDA     READNUM             ;check number of previous reads
              BNE     RETPHONM            ;yes, there has been, return converted string
                                          ;otherwise, return error code
  ;
  ;return error code
  ;
 
  ....
 
  ;
  ;return converted string containing Phonemes
  ;
  RETPHONM    LDY     #00
  $020        LDA     INPUTBUF,Y          ;read converted text from INPUTBUF
              STA     (BUFFER),Y          ;store in read buffer
              INY
              CMP     #ASC_CR             ;if CR then this is the end of the string
              BNE     $020                ;no, next
              TYA                         ;yes, ret count = index +1
              LDY     #00
              STA     (RTNCNT),Y          ;actual characters read count, low byte
              LDA     #00
              INY
              STA     (RTNCNT),Y          ;actual characters read count, high byte
              RTS
One issue with this is it will actually speak the output each time your convert. If I have time, I will come back and improve this.
     
I have updated the changes into my github repository for this here:
https://github.com/robjustice/Apple3SAM

To test this out, I have updated one of my test programs to check the driver operation. The disk image is available here with the updated driver and Basic test program.
demo2.dsk

its quite simple, here is the output show the program and the output from it running in MESS:

Next step will be to add pitch statements to see if SAM can start to sing..