.. include:: header.txt .. comment Heading levels: *** top and bottom , === bottom , --- bottom, +++ bottom ********************* EBTKS Getting Started ********************* What's in the box ================= Depending on how you ordered your EBTKS, it is supplied as just the assembled Printed Circuit Board (PCB) or the PCB with Guide Rails attached .. image:: _images/EBTKS_V3.0_thumb.jpg :height: 400px :align: center :target: _images/EBTKS_V3.0.jpg .. centered:: **EBTKS without Guide Rails** |br| .. image:: _images/EBTKS_Rails_Assembled.jpg :height: 400px :align: center :target: _images/EBTKS_Rails_Assembled.jpg .. centered:: **EBTKS with Guide Rails** Guide Rails =========== PVC or HDPE plastic guide rails are CNC machined out of gray PVC type 1 or black HDPE. The left and right guide rails are sized to match the guide slots in the backplane of your Series80 computer. These come standard with your EBTKS. They are easily removed if you want to use a 3D printed case. .. image:: _images/SD_card_side_rail.jpg :height: 200px :align: center :target: _images/SD_card_side_rail.jpg .. centered:: **Left Guide Rail** |br| .. image:: _images/Both_rails.jpg :height: 400px :align: center :target: _images/Both_rails.jpg .. centered:: **Both Guide Rails** 3D Printed Case =============== The design files for a 3D printed case are now available on :ref:`this page `. Getting the case printed will be your responsibility, the EBTKS team does not provide these cases |clearer| There will be a 16 GB MicroSD Card preloaded with software installed in the Teensy 4.1 module. In case you may want to do additional development on the Teensy module, or maybe remove it from EBTKS to use in another project, the standard Teensy 4.1 reference card is included. If you do unplug the Teensy module (never needed for normal EBTKS use), do it very carefully by slowly levering up each end of the module with a plastic tool, to avoid damaging the module and the PCB beneath it. The pins on the Teensy 4.1 module are very thin and easily bent or broken. .. note: Lastly, your EBTKS includes a 10 cm cable with 4 colored wires and beige connectors at each end. This cable matches the `QWIIC standard `_ and matches the mating small connector on the back edge of EBTKS. At this time, EBTKS has no support for QWIIC, but may have support at a later date. If that happens, you will have a cable to get you started with the huge library of sensor, displays, GPS, and other products that are available from `many vendors `_ . Google will help you find them. EBTKS is Pre Configured ======================= Based on information you provided at the time of your order, EBTKS has been preconfigured to match your system. This is done with the `CONFIG.TXT file `_ which you can edit to change configurations. Please note that this file has a very specific format, and if you edit it, you must verify that you do not mess up the formatting. On the just referenced page, there is information about a syntax checker that is easy to use, to check your changes. There are no user jumpers on EBTKS, every configuration option is controlled by CONFIG.TXT, which is located in the root directory of the MicroSD Card. .. image:: _images/Directory_Tree.png :align: center .. centered:: **MicroSD Card Directory Tree** .. image:: _images/Root_Directory.png :align: center .. centered:: **MicroSD Card Root Directory** Moving EBTKS to a different computer ==================================== In the root directory, as well as the CONFIG.TXT file, there are 6 other configuration files, with hopefully informative names. If you want to change the computer your EBTKS is plugged into another computer that is not the same model and same configuration, the CONFIG.TXT file will need to be changed to match the new computer. The easiest way to do this is to delete the CONFIG.TXT file, and make a copy of one of the other 6 files, naming the copy CONFIG.TXT. You should never edit these 6 files, only copies of them. If you do mess things up, you can always get a pristine copy of the MicroSD Card image from the :ref:`Download page ` Time to start playing ===================== (All of the following assumes the standard MicroSD Card file set. The example screen displays are from a HP85B.) EBTKS is preconfigured to provide 5 floppy disk drives and one 5 MB Winchester drive (all emulated, the actual storage is files on the MicroSD Card). When you start your computer with EBTKS for the first time, it will show the following two screens (the second one by using the Shift-Roll to scroll up) .. image:: _images/initial_CRT_1.png :align: center .. centered:: First page .. image:: _images/initial_CRT_2.png :align: center .. centered:: Second page These two pages show how the CONFIG.TXT file was processed as the system started, and you should review the display carefully if you make any changes to CONFIG.TXT . Briefly it shows the following - Starting on the first page above, for which model of Series80 computer the CONFIG.TXT file is configured. - Whether emulation of the tape drive is enabled (the original goal of EBTKS). Note that for tape drive emulation to work correctly, the physical tape drive must be disabled by unplugging the two flat flex cables. - Whether EBTKS provides extended memory, and how much - Whether ROMs are loaded for HP85 (or 83 or 9915) or for HP86/87 - Which ROMs are enabled - Seen on the second page above, the association between Mass Storage Unit Specifiers (abbreviated in HP Mass Storage Manual as msus) and the files that store the Floppy or Winchester disk image. This startup display can be disabled in the CONFIG.TXT file by changing the line: .. code-block:: text "CRTVerbose": true, to "CRTVerbose": false, The disk image file associated with msus 300 is the initial default Mass Storage device (in the EBTKS situation, an emulated device), which is shown on the second page above is **/disks/EBTKS_1.0_85.dsk** Typing **CAT** will list the contents of this emulated floppy disk (/disks/EBTKS_1.0_85.dsk) .. image:: _images/initial_CAT_of_msus_300.png :align: center .. centered:: Catalog of msus 300 *Some of these programs will run without problems, and some will need editing to match your computer's configuration* Here are some simple examples: The DATE program retrieves the current time and date from the on-board battery backed up clock. It is set to California time, PDT time zone. It uses a new keyword :ref:`DATETIME ` . LIST the program to see how it works. .. image:: _images/running_DATE.png :align: center .. centered:: The DATE Program The DF program shows the amount of total unused disk space and the largest unused space. (in a PACKed disk, these are the same). This is an example of a program that needs to be edited depending on your system. On an HP85B, which always has at least a small EDISK, no editing is needed. On all other systems, if there is no EDISK, line 110 must be changed as shown in the third image below. .. image:: _images/running_DF_1.png :align: center .. centered:: The DF Program (Disk free space) .. image:: _images/running_DF_2.png :align: center .. centered:: Running DF on an HP85B .. image:: _images/running_DF_3.png :align: center .. centered:: Running DF on an HP85A, after editing of line 110 The SINE program is as boring as you would expect it to be, and is not worthy of a screen capture. The programs are used to test the two RGB LEDs on the back edge of EBTKS. |br| You can turn the LEDs off with :ref:`SETLED ` 3,0,0,0 .. code-block:: text LED LEDTEST1 LEDTEST2 Two disk speed benchmarking programs .. code-block:: text RWBENCH85A RWBENCH85B (this can also be used on HP86 and HP87) were used to get the performance data presented at the end of `this forum article `_ . The program will probably need editing depending on whether you have EDISK enabled, and whether you have an HP9121 floppy disk drive attached via an HPIB interface with a msus of 700 The **EBTKS-TEST** program checks multiple parts of EBTKS, and does not need any editing. On an HP85B it takes about 45 seconds to run. Here are the expected two screen pages: .. image:: _images/running_EBTKS-TEST_1.png :align: center .. centered:: Running EBTKS-TEST on an HP85B, page 1 .. image:: _images/running_EBTKS-TEST_2.png :align: center .. centered:: Running EBTKS-TEST on an HP85B, page 2 Pressing CONT will repeat the test and increment the PASS count. .. _MicroSD_Card_Summary: What else is on the MicroSD Card ================================ The :ref:`Directory Tree diagram ` near the top of this page shows many directories. |br| This is documented in detail here :ref:`A Guided tour of the MicroSD Card` Here is a brief summary. .. csv-table:: :widths: 10,70 :align: left "root", "covered above" "BAS", "BASIC programs in ASCII source form. |br| :ref:`SDSAVE ` /BAS/DF.BAS stores the DF program in source form |br| :ref:`SDGET ` /BAS/DF.BAS loads the source file DF.BAS |br| If these .BAS files are transferred to a PC, they can be edited with a text editor" "disks", "This is where the disk image files reside" "EK_Disks", "This is a copy of all the disk images found in Everett Kaser's Series80 emulator" "help85", "All the help text for HP85A/B are in this subtree. This is still a work in progress" "help87", "All the help text for HP86A/B and 87/87XM are in this subtree. This is still a work in progress" "Original_images", "Disk and tape images of blank media. Used when creating a new Disk or Tape" "Printers", "Output that would normally go to the printer can be redirected to a file in this directory" "roms85", "All of the available ROMs compatible with HP85A/B" "roms87", "All of the available ROMs compatible with HP86A/B and HP87/87XM" "tapes", "This is where the tape image files reside. unused on HP86A/B and 87/87XM" "testfiles", "A test directory used during development, and by EBTKS-TEST" "TOK", "BASIC programs in tokenized form. Functionally the same as saved programs in the emulated disks. |br| :ref:`SDLOAD ` /TOK/DF.TOK loads the DF program. |br| :ref:`SDSTORE ` /TOK/DF.TOK saves the DF program in tokenized form." EBTKS Configuration =================== The **checklist page** that is included with your EBTKS lists the initial settings for your EBTKS. These are included in the CONFIG.TXT file that is in the root directory of the provided SD Card. |br| See :ref:`Working with CONFIG.TXT` for details of how to make changes to this file. |br| The checklist also lists the expected configuration of your system, with regard to the following: * Is the tape drive connected (for HP85A and HP85B) * It is expected that there is no ROM module or other ROM card installed as EBTKS should be able to provide all the ROMs you need * On HP85A, don't install an extra 16 kb memory module as EBTKS can provide this memory. * On HP85B, EMC memory modules can be used for EDisk. See :ref:`EMC ` for details. * Typically, a HP85B has 3 option ROMs pre-installed on the main board: * I/O |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| (Octal 300 ) * Mass Storage |_| |_| |_| |_| (Octal 320) * EDisk |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| |_| (Octal 321) Do not enable these ROMs on EBTKS on an HP85B system, as it will cause incorrect operation. |br| A similar constraint exists for HP86A/B and HP87/87XM pre-installed ROMs. * EBTKS uses module select code 3 for an emulated HPIB interface that is the gateway to emulated floppy disk drives and emulated hard disk drives. It is also used for an emulated printer Therefore, if you have a real HPIB interface module plugged in for * Other real disk drives * Test and Measurement equipment * Data acquisition * Printers * Plotters * Emulated disks that connect over real HPIB the real HPIB interface must not use select code 3. By default, HP ships HPIB interface modules with select code 7. As you will see on the :ref:`Working with CONFIG.TXT` page you can make edits to the file by putting the SD Card into a PC and using a simple text editor like notepad. This allows changing the initial disk and tape drive assignments to various LIF image files. Even though it looks like you can add new additional sections following the existing format, please don't, as things will probably break. At a later time, hopefully an EBTKS owner will write a utility program that runs on the HP85 and automates simple changes to the CONFIG.TXT file. **Note:** CONFIG.TXT is an ASCII text file in JSON format. Editors like WordPad and MSWord add additional information like character height, font selection, and other formatting control. This will corrupt the file. |br| While Notepad can be used for editing CONFIG.TXT, another far superior free editor that does not add formatting is Notepad++ which can be found with Google Search. |br| For Linux/Unix systems, suitable editors include VI, VIM, EMACS, Nano, Atom, Gedit. .. comment: this text might be useful else where RAM16KTOG ^^^^^^^^^ | **LOAD "RAM16KTOG"** | **RUN** The standard HP85A comes with 16 kb of memory, and can have at most one 16 kb RAM module (HP82903A) plugged into the back of the computer. With the EBTKS installed, the HP82903A should not be plugged in, as EBTKS can provide the additional 16 kb, thus saving a slot in the backplane. The control for this capability is a parameter in CONFIG.TXT named **ram16k** which usually is set to true for an HP85A and *must* be set to false for the HP85B, and all models of HP86 and HP87. This RAM16KTOG program will change the parameter from true to false and from false to true. A few New Keywords ================== The following are useful initial keywords to check the firmware and AUXROM versions, and which ROMs have been loaded. These are all just typed at the BASIC prompt. See :ref:`AUXROM Keywords` for the full list of over 57 new keywords, with more detailed explanations and examples :ref:`AUXREV ` Returns the AUX ROMs revision# (from ROM 361) :ref:`EBTKSREV$ ` Returns a string containing date and time of building the EBTKS firmware :ref:`LISTROMS ` 0 Displays all the possible ROMs for HP85/86/87 and their Octal/Decimal ID number :ref:`LISTROMS ` 1 Displays currently installed ROMs and their Octal/Decimal ID number. AUXROMS are loaded as a set with Octal IDs 361, 362, 363, 364. LISTROMS will only list the first one .. comment: NEED TO COME BACK TO THIS Loading and Storing files ========================= There are 6 keywords involved with Loading and Storing files. The first two are already well known to HP85 users. Here is a little refresher. Files on Emulated Disks and Tape: --------------------------------- **LOAD \"Filename\"** This is the standard HP85 LOAD keyword. The specified program is LOADed from the default storage device (the tape drive if there are no disks, or a disk drive). With EBTKS, the Tape Drive and Disk Drives are emulated and the data is LOADed from a file that is in LIF format and thus contains an internal directory, and possibly, many programs. From the HP85 user's point of view, the LOAD behaves as if there is a real tape or disk drive. The LIF file resides on the SD Card, with an initial set of such LIF files in the /DISKS/ directory. The LIF files are in the same format as the LIF files used with Everett Kaser's Series 80 emulator, and they are interchangeable. You can thus develop a program on Everett's emulator, STORE the program to an emulated disk (a LIF file), copy the LIF file to the SD Card, and then LOAD the file on an HP85 with EBTKS. If the LIF file that you want to access is not on the default drive, the standard Mass Storage extension of the LOAD command works as expected: **LOAD \"FILENAME:D321\"** If the LIF file is not currently associated with an emulated Disk drive, it can be :ref:`MOUNTed ` **STORE \"Filename\"** This is the standard HP85 STORE keyword. The specified program is STOREd to the default storage device (the tape drive if there are no disks, or a disk drive). With EBTKS, the Tape Drive and Disk Drives are emulated and the data is STOREd to a file that is in LIF format and thus contains an internal directory, and possibly, many programs. From the HP85 user's point of view, the STORE behaves as if there is a real tape or disk drive. The LIF file resides on the SD Card, with an initial set of such LIF files in the /DISKS/ directory. The LIF files are in the same format as the LIF files used with Everett Kaser's Series 80 emulator, and they are interchangeable. You can thus develop a program on and HP85 with EBTKS STORE the program to an emulated disk (a LIF file), copy the LIF file from the SD Card to a computer that has Everett's Emulator installed, and then LOAD the file in the emulator and run it in the emulator. If the LIF file that you want to access is not on the default drive, the standard Mass Storage extension of the STORE command works as expected: **STORE \"FILENAME:D321\"** If the LIF file is not currently associated with an emulated Disk drive, it can be :ref:`MOUNTed ` Files that are LOADed and STOREd with the standard keywords are stored within the LIF file in a tokenized form. See various HP85 documentation for more information about tokenized programs. When a tokenized program is loaded into memory, it remains in that form. When the LIST command is issued the tokenized form is decompiled to text and listed as the basic text you are used to reading. The opposite happens when you type a line of BASIC. When you type END LINE at the end of you line of program, it is compiled into tokenized form and stored into memory, ready to be RUN. LOADing and STOREing to the SD Card, in tokenized form: ------------------------------------------------------- **SDLOAD \"/path/Filename.TOK\"** As described above, the internal way that BASIC programs exist within the memory of an HP85, is in a tokenized rather than text form. So the standard LOAD and STORE move files in and out of LIF images on EBTKS, in tokenized form. But what if you want to directly access a tokenized file, without all the rest of what is stored in a LIF disk/tape image? SDLOAD can fetch a tokenized file from the SD Card file system, including long file names, and from sub-directories. By convention, to recognize such files on the SD Card, we append .TOK to the filename. Like the normal LOAD command, the tokenized file is loaded into memory in tokenized form. An example: **SDLOAD \"/BASIC_TOK/BOARD-T.TOK\"** **SDSTORE \"/path/Filename.TOK\"** SDSTORE is the complement of SDLOAD. It stores the current program in memory (which is in tokenized form) to the SD Card, including a path that may include sub-directories. By convention, to recognize such files on the SD Card, we append .TOK to the filename. Like the normal STORE command, the tokenized file is STOREd to the specified location in tokenized form. An example: **SDSTORE \"/BASIC_TOK/BOARD-T.TOK\"** SDLOAD and SDSTORE are supported by Everett Kaser's emulator, so these name.TOK files can be interchanged with the emulator, bypassing the disk/tape LIF files. These TOK files will also be a good way to pass programs between other EBTKS owners. LOADing and STOREing to the SD Card, in TEXT form: -------------------------------------------------- **SDSAVE \"/path/Filename.BAS\"** SDSAVE is the complement of SDGET. It stores the current program in memory (which is in tokenized form) by first de-compiling it to text (like the LIST command) and then saving it on the SD Card, including a path that may include sub-directories. By convention, to recognize such files on the SD Card, we append .BAS to the filename. A .BAS file can be edited on a non HP85 computer, as it is just normal text. Editors like NOTEPAD and NOTEPAD++ on the Windows PCs are example editors. I use and recommend ULTRAEDIT, but there are many options. Microsoft WordPAD and Microsoft Word are not suitable. Like all BASIC programs, the line order is controlled by the line numbers. If you depend on using the REN (renumber) command, you will not enjoy the experience, as external editors as just described, do not have this capability. SDSAVE may take a while to complete. When it does, it displays DONE, so you should wait for that to occur before typing any new commands. An example: **SDSAVE \"/BASIC_BAS/Test_program_1.BAS\"** **SDGET \"/path/Filename.BAS\"** SDGET fetches a BASIC program in text format from the SD Card, and tokenizes it and stores it into the HP85 memory. **UNLIKE LOAD AND SDLOAD, SDGET DOES NOT ERASE THE MEMORY BEFORE PROCESSING THE FILE THAT IT IS GETting. THIS ALLOWS MERGING TWO PROGRAMS IN TEXT FORM, WHICH ONLY WORKS IF NONE OF THE LINE NUMBERS ARE COMMON OR END UP INTERLEAVING. UNDER MOST SITUATIONS, YOU SHOULD ENTER THE SCRATCH COMMAND BEFORE DOING AN SDGET** SDGET Can take a while to complete. While it is running, it indicates progress with a percentage display. Wait for it to complete before typing any new commands. An example: **SCRATCH** |br| |_10| |_10| |_| **SDGET \"/BASIC_BAS/BOARD-T.BAS\"** SDSAVE and SDGET are supported by Everett Kaser's emulator, so these name.BAS files can be interchanged with the emulator, bypassing the disk/tape LIF files. These BAS files will also be a good way to pass programs between other EBTKS owners. An example of using these commands together ------------------------------------------- To create the initial SD Card file set, each of the example programs were developed and debugged on the HP85. Once the program was debugged, it was written to the SD card in all 3 formats described above to provide examples to the Beta testers. Here are the commands: **STORE \"LEDTEST-1\"** |br| **SDSTORE \"/BASIC_TOK/LEDTEST-1.TOK\"** |br| **SDSAVE \"/BASIC_BAS/LEDTEST-1.BAS\"** Links ===== :ref:`EBTKS Downloads` :ref:`Updating the EBTKS Firmware` :ref:`AUXROM Keywords` Connecting the serial diagnostic port ===================================== Highlights ---------- There are several help pages that list the available commands. Just type the number 0 to 6 and enter to get a short help page. The serial diagnostic port Help ------------------------------- This section of EBTKS is likely to change since it is primarily a debug tool for the EBTKS developers Here are the 7 pages of help .. code-block:: text EBTKS> 0 EBTKS Control commands - not case-sensitive 0 Help for the help levels 1 Help for Display Information 2 Help for Diagnostic commands 3 Help for Directory and Time/Date Commands 5 Help for Developers 6 Help for Demo .. code-block:: text EBTKS> 1 Commands to Display Information show ----- Show commands have a parameter after exactly 1 space log Show the System Logfile boot Show the messages from the boot process, sent to Serial port CRTboot Show the messages sent to the CRT at startup config Show the CONFIG.TXT file media Show the Disk and Tape assignments mb Display current mailboxes and related data CRTVis Show what is visible on the CRT CRTAll Show all of the CRT ALPHA memory key85_O Display HP85 Special Keys in Octal key85_D Display HP85 Special Keys in Decimal key87_O Display HP87 Special Keys in Octal key87_D Display HP87 Special Keys in Decimal other Anything else is a file name path .. code-block:: text EBTKS> 2 Commands for Diagnostic la setup Set up the logic analyzer la go Start the logic analyzer addr Instantly show where HP85 is executing kbdcode Show key codes for next 10 characters in the keyboard byffer clean log Clean the Logfile on the SD Card sdreadtimer Test Reading with different start positions SDCID Display the CID information for the SD Card PSRAMTest Test the 8 MB PSRAM. You probably should do the PWO command when test has finished ESP32 Prog Activate a passthrough serial path to program the ESP32 pwo Pulse PWO, resetting HP85 and EBTKS .. code-block:: text EBTKS> 3 Directory and Date/Time Commands dir tapes Directory of available tapes dir disks Directory of available disks dir roms Directory of available ROMs dir root Directory of available ROMs Date Show current Date and Time SetDate Set the Date in MM/DD/YYYY format SetTime Set the Time in HH:MM 24 hour format adj min The U and D command will adjust minutes adj hour The U and D command will adjust houres U Increment the time by 1 minute or hour D Decrement the time by 1 minute or hour .. code-block:: text EBTKS> 4 Commands for Auxiliary programs .. code-block:: text EBTKS> 5 Commands for Developers (mostly Philip) crt 1 Try and understand CRT Busy status timing crt 2 Fast CRT Write Experiments crt 3 Normal CRT Write Experiments crt 4 Test screen Save and Restore crt 5 Test writing text to HP86/87 CRT .. code-block:: EBTKS> 6 Commands for Demo graphics test Set graphics mode first jay pi Jay's Pi calculator running on Teensy Boot logging ------------ Every time EBTKS starts up it creates three logs. - Short list of ROM and Disk Mounts can be sent to the CRT. Can be disabled in CONFIG.TXT from being displayed - A detailed report on the processing of the CONFIG.TXT file. Always sent to the serial diagnostic port. - A similar report to the report that is sent to the serial diagnostic port, is appended to a log file on the MicroSD Card