Try these TAQOZ code snippets and learn!
Peter Jakacki
Posts: 10,193
What came out of the zoom meeting about TAQOZ was the need for simple code examples that anyone can try and then learn from. TAQOZ is an amazing "tool" that anyone can access on their P2 because it is already built into the ROM and very useful for sanity checking hardware but also very useful for rapid prototyping of code without any kind of IDE or external tools, although I recommend Visual Studio Code as an excellent code editor from which I also run minicom as my serial terminal emulator within one of its terminal windows.
What I'd like to do with this thread is to continue with a new code snippet each day and depending upon feedback find out what I can write about in some ongoing online tutorials.
One of the simple things I was showing was a one-liner, that is all the code fits onto one line and executes immediately when you hit enter. These are useful for quick tests.
Then I took one line and defined a new word to be added to the Forth dictionary. Normally any word you type in a Forth command line is delimited by spaces or tabs or CR and Forth will search its dictionary for an exact match which if found will normally then execute the code associated with that dictionary entry. If it doesn't find a match it then tries to convert it to a number if possible and if so, it then pushes that number onto the top of the data stack. All parameters and pointers and results are passed back and forth by means of the data stack.
Anyway, I called this word DEMO which when typed or implicitly called from any other code, will run its code and return. Here is that code except I call it NOTES and instead of embedding the pin number for audio output, I allow that to be passed via the stack:
You can try this in the TAQOZ ROM, just connect any serial terminal at any baud rate, typically 115200 baud, type the two character auto-baud sequence " > space " followed by an escape to enter TAQOZ in ROM. (The P2 goes to sleep after a few minutes if it doesn't boot anything, so you might have to press the reset again to wake it up).
This is what I see:
Now copy and paste the NOTES line of code shown above and perhaps hit enter if necessary and then you will see the "--- ok" response. If you have a speaker or transducer connected to P6 then type "6 NOTES" and you will hear the gliding tone.
Didn't Work?
Perhaps it said "6NOTES ???" which means there is no such word in the dictionary. Make sure you have at least one space between the 6 and NOTES.
Still didn't work?
If it says "NOTES ???" then it is quite possible that you made a mistake typing in NOTES if you didn't paste it, or that TAQOZ has been reset since and lost it.
If you want to save this for next time you boot up then type BACKUP which will backup the whole TAQOZ image into Flash. Although TAQOZ in ROM is not designed to automatically boot, you can restore the Flash image once you are back into TAQOZ using RESTORE or simply a ^R (control R) which also restarts TAQOZ from this restored image. Btw, the image is saved in the $F.0000 area of the Flash chip as a 64kB binary.
HOW DOES IT WORK: ( Edit - I just made this code copy&pastable by adding --- comment directives )
You can also do exactly the same with TAQOZ RELOADED, the version that you can boot from on SD or load serially. Also, don't forget I have lots and lots of wiki pages talking about all things TAQOZ and Tachyon and P2 and P1 on my SourceForge site.
EXTRA: If you are using TAQOZ RELOADED and want NOTES to automatically execute on power-up/reset then simply change NOTES to include the pin number before PIN such as "6 PIN" etc and type "AUTO NOTES" and then "BACKUP BIX" to save your TAQOZ image back to the SD card.
MORE FUN: Here are two simple classic arcade sound effects that you can even build into a game.
What I'd like to do with this thread is to continue with a new code snippet each day and depending upon feedback find out what I can write about in some ongoing online tutorials.
One of the simple things I was showing was a one-liner, that is all the code fits onto one line and executes immediately when you hit enter. These are useful for quick tests.
Then I took one line and defined a new word to be added to the Forth dictionary. Normally any word you type in a Forth command line is delimited by spaces or tabs or CR and Forth will search its dictionary for an exact match which if found will normally then execute the code associated with that dictionary entry. If it doesn't find a match it then tries to convert it to a number if possible and if so, it then pushes that number onto the top of the data stack. All parameters and pointers and results are passed back and forth by means of the data stack.
Anyway, I called this word DEMO which when typed or implicitly called from any other code, will run its code and return. Here is that code except I call it NOTES and instead of embedding the pin number for audio output, I allow that to be passed via the stack:
pub NOTES ( pin -- ) PIN 3000 100 DO I HZ 50 ms 100 +LOOP MUTE ;Now I have an amplified speaker connected to P6 and P7 so that when I type 6 NOTES<CR> it produces a series of gliding notes starting at 100Hz, holding it for 50 ms before stepping up another 100Hz until it reaches the limit of 3000 where it then exits the loop and in this case MUTEs the audio output.
You can try this in the TAQOZ ROM, just connect any serial terminal at any baud rate, typically 115200 baud, type the two character auto-baud sequence " > space " followed by an escape to enter TAQOZ in ROM. (The P2 goes to sleep after a few minutes if it doesn't boot anything, so you might have to press the reset again to wake it up).
This is what I see:
x Cold start ------------------------------------------------------------------------------- Parallax P2 .:.:--TAQOZ--:.:. V1.1--v33h 190219-1900 ------------------------------------------------------------------------------- TAQOZ#Hit the enter key and TAQOZ will respond with "--- ok" and reprompt on a new line (CR+LF). This simply indicates TAQOZ is responding to your input.
Now copy and paste the NOTES line of code shown above and perhaps hit enter if necessary and then you will see the "--- ok" response. If you have a speaker or transducer connected to P6 then type "6 NOTES" and you will hear the gliding tone.
Didn't Work?
Perhaps it said "6NOTES ???" which means there is no such word in the dictionary. Make sure you have at least one space between the 6 and NOTES.
Still didn't work?
If it says "NOTES ???" then it is quite possible that you made a mistake typing in NOTES if you didn't paste it, or that TAQOZ has been reset since and lost it.
If you want to save this for next time you boot up then type BACKUP which will backup the whole TAQOZ image into Flash. Although TAQOZ in ROM is not designed to automatically boot, you can restore the Flash image once you are back into TAQOZ using RESTORE or simply a ^R (control R) which also restarts TAQOZ from this restored image. Btw, the image is saved in the $F.0000 area of the Flash chip as a 64kB binary.
HOW DOES IT WORK: ( Edit - I just made this code copy&pastable by adding --- comment directives )
pub NOTES --- Create a new public word called NOTES, and start compiling the following code
( pin -- ) --- ( is a comment up to the matching ), in this case a stack effects comment
--- with "pin" as value on the stack when entering, without returning any results.
PIN --- Latches the value supplied as the destination for any further PIN type operations.
3000 --- Not a word, but recognized as the number 3000 which is pushed onto the stack
100 --- The number 100 is pushed onto the stack over the top of the 3000
DO --- Marks the beginning of a loop and takes a starting index (100) and a stop limit (3000)
I --- Returns the value of the current Index starting from 100 (on top of the stack)
HZ --- HZ takes the value from the stack and sets the current PIN to output a matching NCO frequency
50 --- 50
ms --- will delay 50ms before continuing, long enough to hear a distinct note.
100 --- the Hz value we want to step up each time through the loop (100Hz)
+LOOP --- Increment the index by the value supplied and loop again until the limit is reached
MUTE --- Now to stop that infernal racket, MUTE will simply reset the smartpin function of the pin
; --- Exit and return (also completes this word when it is first being created)
You can also do exactly the same with TAQOZ RELOADED, the version that you can boot from on SD or load serially. Also, don't forget I have lots and lots of wiki pages talking about all things TAQOZ and Tachyon and P2 and P1 on my SourceForge site.
EXTRA: If you are using TAQOZ RELOADED and want NOTES to automatically execute on power-up/reset then simply change NOTES to include the pin number before PIN such as "6 PIN" etc and type "AUTO NOTES" and then "BACKUP BIX" to save your TAQOZ image back to the SD card.
MORE FUN: Here are two simple classic arcade sound effects that you can even build into a game.
pub ZAP ( use PIN ) 3000 100 DO I HZ 15 I 300 / - ms 200 +LOOP MUTE ; pub SAUCER ( use PIN ) 10 FOR 600 Hz 50 ms 580 Hz 50 ms NEXT MUTE ;Remember to set the PIN once beforehand and you can even have repeat ZAPs:
pub ZAPS ( cnt -- ) FOR ZAP 50 ms NEXT ;
Comments
What is the TAQOZ 'way' of handling event triggers.
eg., On Pin 1 Rising => ZAP, On Pin 2 Falling => SAUCER. Would this be handled in a master loop or do you have a way to hook events ( or interrupts ) into TAQOZ
Actually, there is a way to interrupt TAQOZ and I was thinking about this the other day. I just need to think about how to make this super simple to use. Remember too that while TAQOZ is waiting for keyboard input that it calls POLLS which can have new polls added to it at anytime with +POLL. The other thing I want to add is what I have in Tachyon on the P1 where one cog is running background timer and alarm functions. So it is very easy for a Forth routine that scans button inputs for instance to be checked every 1ms if need be, so that it either executes a short bit of code (<1ms) or else interrupts the main application cog which then does what it needs to do. So many ways of tackling this but I will try and implement and demonstrate this soon.
I don't know how to express this in TAQOZ but in pseudocode :
=> ZAP(Pin=1, COG1) ; ZAP(Pin=2,COG2)
So the idea is : start ZAP task on Pin 1 in Cog1 and also start ZAP task on Pin 2 on Cog 2. They run and then release the COG when done.
Is this something TAQOZ can do?
That should be nothing more than telling these cogs to run this code, like this: Then loading these with: Btw, AT is just an alias for the ' symbol. Easier to read and see.
If these two cogs always ran sounds from the same pins then you could simplify this even further too.
I've just watched the youtube video introducing Taqoz. I'm a retired radio ham - I'm currently building a stepper motor controller for a tunable antenna using Flashforth on a pic18. I've dabbled in forth for 20+ years, so I'm greatly impressed and enthused by what Taqoz has to offer - fantastic job, Peter. When in production, I'll be making things with it.
I've followed many versions of Forth over the years and seen most fail to gain any following. The ones that persisted longest all had:-
1. Good documentation - a dictionary of words with stack effect and brief description of what each word does is a good start but not enough in itself
2. An organised collection of the simplest possible snippets showing how groups of closely associated words work - a collection of example files in the distribution would be the minimum - keep it all together so folks don't have to ferret through a forum or whatever. Keep it simple - no more than 1 side of paper each so it's quickly taken in.
3. A limited number of words in the dictionary - which is what you have in the ROM of course
4. Stability - if the sdcard version of Taqoz changes all the time, then few people will adopt it. If it's just expanding all the time in a modular way, well that's great.
Flashforth just about has all the above - not perfect - but enough that it's been adopted commercially, which is a big thing for a Forth in these days.
Forth's big strength comes from quickly getting people flashing lights, making noises, reading sensors and making motors turn with the minimum syntax to remember. Building your own language to support the job in hand.
Everybody is too busy engineering to write the documentation for the users. Can you set up some kind of wiki so that users could contribute Taqoz documentation? I would be willing to help write Taqoz documentation given a source of useful data - I've written electronics related technical documents all my working life.
You have to ask yourself - what would make Taqoz used more than what has gone before. Don't leave it like Win32Forth - 1000's of undocumented words - useless as the learning curve was enormous.
It's important to tap into a large community like arduino. Make at least some P2 boards that are arduino shield compatible to appeal to the widest audience. I know the P2 stands on it's own feet perfectly well without expansion cards - it's the huge community you attract that's important, for their contributions.
RPN is not a problem to people being introduced to programming - only to old programmers who're set in their ways in other languages.
Forget trying to 'dumb down' forth for kids - I'm guessing there are other tools like blockly or python that would require less effort to get 'visually interesting' and to provide the attractive GUI that folks go for (I like attractive GUIs for some things).
I'm a big fan of what you're all doing with P2 and am at least watching and would like to contribute from now on - cheers, Bob Edwards, ham radio callsign G4BBY, SW England
Well said, and to the point Bob. I must say though that good documentation is a task better met by more than a team of one. If TAQOZ was my sole project and software is all I did, then I might have time enough for it, although a single perspective, however knowledgeable, can easily fail to capture the big picture and the big audience. The truth is that I'm probably just as immersed in hardware design and having to document that as well. On top of that I have been involved with helping to document the P2 and lot of the earlier stuff I did is now obsolete although I havepublished the only datasheet so far.
However I am saying this simply because while I would like to have good documentation, I also have limitations, more so in recent years, and only so much time. While I share what I am doing with others, the main aim from the beginning was to provide a platform for my designs first. If it works for me, then I reason, it can work for others, plus I love sharing and it's fun. There is also where some of my ideas come from, either directly or indirectly via the forum.
Yes, I am busy engineering and have little time for documentation, but then again, I'm not everybody, just one person
You mentioned Win32Forth - yes, the trouble with the PC environment is you end up with using up those vast resources the same way we end up using the garden shed, by filling it to the point of not being to find what we want. I believe that this is much harder to do on smaller MCUs, especially the P1 and also many of the smaller micros that Flashforth would be used on. Now we have the P2 with 512k and it seems I can't even fill 64k, although I am trying! This is where I am trying to be careful and not create extra public functions that need to be documented. The ones I like are the ones that are or should be self-explanatory, words such as "ms" and "Hz" and "mV" etc. It amuses me that delay.ms(50) and set.frequency(1000) seem more "natural" to many programmers
Back to Forth in general, it has been said that necessity is the mother of Invention, and Forth was invented out of necessity mostly for real-time control of radio telescopes. Charles Moore was once asked if he could go back, would he change anything about Forth, and what he said was most telling, quote "The thing about Forth is that if I wanted a change, I made it. That's still true today. Forth is really a language tool kit. You select and modify every time you encounter a new application."
Whoa! That is not helping this documentation thing we are discussing here, it's true, but understanding that Forth is not just a "language" but really a language tool kit that you can make application specific helps us to strike some balance between locking everything in a time bubble just so it can be well and truly documented, and letting loose in write-only fashion. I hope we can have good documentation without clipping Forth's wings in the process.
I really look forward to discussing what we and perhaps others can do or suggest in regards to documenting TAQOZ.
BTW, have you had a look at my wiki pages on SourceForge?
Cheers,
Peter
Whilst Forth's syntax is very simple compared to other languages, that helps but doesn't eliminate remembering what Forth words to use. There will be 100 - 200 words in Taqoz ROM, but many more in SDcard Taqoz. Even Peter was forgetting what word to use during the video and he's the author. So - faced with maybe 1000+ words in a programming language, how do unfamiliar users become acquainted with them all without memorising the lot!!
The designers of test and measurement language LabView had to solve the same problem. This is a graphical language whereby small icons (representing functions) are tied together by wires (representing data flow) to make a program. There are many hundreds of LabView functions, access to which are made easy by two things:-
1. The LabView editor has a pop-up menu from which functions can be picked by the user and placed into the design. The menu is multi-level and highly organised by general -> specific function
2. Hovering over a function optionally brings up a comprehensive help window on that function with a pointer to an example of use. This happens in the design or the menu window. Browsing the function menu becomes highly informed like that.
So a dumb terminal is OK, but a smart terminal that did the above would be a big help to new and oldsters
Incidentally, the LabView development system is now available as a free community edition for non-commercial use. It's not limited in any technical way. I've found it very useful to talk to Forth based microcontrollers - like bacon and eggs. For electronics builders that's a big gift. I've no connection other than being a big fan.
I missed your reply before adding the other comment. I fully appreciate you're topped out earning a living and supporting Parallax - the documentation is down the list. Also me offering to help write documentation is only useful if it doesn't make more work for you and the team. Best to acquire a dev. board - then could write documentation as an aid to learning how to use taqoz?
I liked the simplicity of the words you demonstrated for pin control - Mr Moore would approve I think. I'll revisit the sourceforge wiki and shut up meanwhile!
That's the problem when we are doing the talking, our minds don't always work the way they normally do and we even forget the names of people we know quite well. The reason I couldn't find a particular word in TAQOZ is simply because I haven't implemented that section of it yet, although it does exist in the more mature Tachyon version for P1
It seems the Labview community edition is only a 32-bit app that only works on Windows. No Mac, no Linux, no RPi.
However, the terminal doesn't have to be smart although that would help. When we are downloading chunks of source code then compilation speed is more important, but when we are in interactive console mode where we are typing in those new definitions it wouldn't hurt for TAQOZ to actively lookup keywords and functions etc, seeing that we can store all that information on a tiny part of the SD card, or even the Flash chip. This is, in part, what I wanted to do with Tachyon on the P1.
What can we do to kick this documentation and help system off?
Should turn on the LED
56 LOW
or to make it blink
56 BLINK
to change the blink rate
10 HZ
etc
Other sections could be added related to 'getting started' and 'testing a new board' as ideas firm up. I guess my first information source would be the Taqoz source code and keep the questions as low as possible? Does Parallax have a technical document blank you all use, else I'll make something up?
As an example - not long ago I wrote a 50 page programmers' guide for a LabView library that I fancied using. See a little way down https://lavag.org/topic/16360-lvtn-messenger-library/page/8/ (too big to add as a file here) The author was pleased with the result.
Cheers, Bob
Produces:
But yet when I mount, I reports the size correctly.
https://github.com/speccy88/TAQOZ/blob/master/docs/guide.md
CARD: SANDISK SD SC32G REV$80 #2266301459 DATE:2018 /3
This is the information taken from the CID register on the card itself and translated so that I look up the manufacturer code and if I find a match then I print the name. Here's the relevant code that prints the CID if you can follow it.
So the line that says "SPACE cid 3 + 5 CTYPE" prints SC32G which is the manufacturer's model number indicating it is a 32G card.
Btw, what the card reports in its CID and CSD may be different to what FAT32 reports which may be less.
Yes, that's right Fred. Thanks for the reminder, I will put it in my links as well although I have your page up in one of my many TAQOZ tabs.
Perhaps that one long page can be broken up into sections such as logic, arithmetic, dictionary etc. Do you want me to incorporate that material on the Tachyon SF page for ongoing editing and contributions?
It would be nice to have that kind of cheat sheet
http://flashforth.com/ff5-sheet.pdf
Yes, I remember the quick reference sheets for Spin and PASM that were very similar and very useful too. I've just converted that pdf into doc format and made a copy of it as the TAQOZ QUICK REFERENCE SHEET in odf format (could be doc) since I use LibreOffice. I've saved this into the TAQOZ Dropbox folder in a new doc folder but I will see if I can format this in Google docs (which it didn't first off) so that editing can be shared easily.
I might even see where it is advantageous to align the naming and operation to suit something familiar to other Forth users. However I note that while "Forths" are available for many micros, they seem to be too intent on being "a Forth that runs on that micro" rather than a Forth designed from the ground up not just for the micro, but for everything that the micro is used for. There are also a lot of things in Forth that are "archaic" and limited such as string represented with two stack values, a count, and the string. I prefer to have just one item, the pointer to a null terminated string. There are many other aspects of the classic Forth that I don't agree with in 2020.
Here's a copy of the file that I started to work on, just briefly.
The original source code was this:
Now let's see how it was compiled.
TAQOZ# see NOTES 1C131: pub NOTES 09E5C: 3F68 PIN 09E5E: 006F 3000 $0BB8 09E62: 1864 100 09E64: 1028 DO 09E66: 0120 I 09E68: 440C HZ 09E6A: 1832 50 09E6C: 0F54 ms 09E6E: 1864 100 09E70: 0125 +LOOP 09E72: 430B MUTE ; ( 24 bytes ) --- okThis is a very useful tool for checking, patching, and understanding what happens when a word is compiled. As you can see each word in the source corresponds to a 16-bit word in the compiled code, except for 3000 which was compiled as a code 006F that calls an unnamed routine that will read in the next 16-bits as a literal and push it onto the stack.
Most 16-bit "wordcodes" are actual addresses, either in the cog, or in the hubexec area above $800, or other threaded wordcode. so the I word is $0120 which indicates that it is in the cog as is +LOOP but DO is at $1028 which is a hubexec area. Furthermore 100 is a single 16-bit word $1864 but if you read hex you will recognize the 64 hex as 100 decimal. There are a range of "addresses" from $1800 to $1FFF that are not called but rather decoded further. In this case 10-bit literals are encoded in compact form with a base code of $1800* which will range up to $1BFF. Other codes are used for branching and other operations which require a small offset such as IF and UNTIL etc.
There is an extra optimization right at the end when it comes to the last wordcode, if it is an address to other threaded code then these areas are always on an even address so by setting the LSB of this address, TAQOZ will interpret this as call this address (after masking) but don't bother pushing the IP (Forth's PC) onto the return stack, effectively making it a jump instead of a call. This means there is no need to waste another EXIT instruction after this to do nothing else but return. The ; word actively checks for a valid address and that there are no internal IF THEN words that jump to that location either or are literals or strings etc.
So that's how we get 24 bytes of code and that's why I have such trouble trying to fill the first 64k with code!
Extra: If I just wanted to decompile the code back into something that I could modify and paste back in, then simply ask it to decompile.
TAQOZ# DECOMP NOTES 1C131: pub NOTES PIN 3000 100 DO I HZ 50 ms 100 +LOOP MUTE ; ( 24 bytes ) --- okNotes:
* The $1800 area was chosen because it means that anything above this area is threaded code that may eventually overflow outside of the first 64k (tested), but that's another story. At the same time while this area cannot be used for actual runtime code, it is used for buffers and variables etc.
I hope forth has found a way to increase the size of all disks by factor 4 😀
It must be reported the saved details of my card but I'm sure once you mount your card it will be reported correctly! But maybe if you leave it unmounted you could have 4 times the memory?
I will do a new image tonight that also mounts the card at startup, which it used to, but this was left out for some other tests earlier in the year.
I saw Fred Blais's original of the "Hitchhikers Guide" to Taqoz ROM? I can take that on - thanks for the ROM listing.
Today I wrote the shell of a "Getting Started Guide" see attached. Is there anyone else doing this as I wouldn't want to step on any toes. I'll flesh it out if you approve. If you make comments etc. just bounce a changed copy back to me. If it's not wanted, please tell me and I'm not in the least offended.
This section of the forum is for snippets, should we communicate directly or by some other part of the forum? I'm at ' yahoo.com at bob.edwards50 '. (You can figure out my real address).
Then, you have unlimited time to figure out the ">",space button,esc button sequence.
Also, looks like you can insert "enter" button presses in there with no effect...
After a boot with the SD card, for the time being, it will report 64GB. If you do a .CID, it will still report 64GB. If you MOUNT, then do .CID, it should report the correct storage.
Peter indicates that he will change TAQOZ RELOADED to change that to look at the actual SD in a future change.
That's a great start Bob! Have read many of your projects over the years.
Tried a newly formatted SD card and BACKUP BIX worked fine! Saved NOTES just fine.