Project Logs

Collapse

• Hackaday BASIC Interpreter

  Mike Szczys • 05/14/2018 at 21:55 • 9 comments

  The Hackaday BASIC interpreter is based on the uBASIC project by Adam Dunkels. This provided a tokenizer and the most rudimentary words needed for the language to operate. From there, Jaromir Sukuba greatly expanded the word set to take advantage of the best the badge hardware has to offer.

  The reference for all of the words is listed below. You may also see examples of these words in use by viewing the example code project log.

  Of Note:

  • Code in the program buffer can be viewed one page at a time by typing more. You can overwrite lines just by typing the line number at the prompt along with your new commands. It is recommended that you number every 10 lines or more so that you can add commands in between them as you develop your code.
  • The memclr word will clear the code currently in the program buffer.
  • There are two print commands. print will not include a line feed, println will include a line feed

  BASIC Word List:

  Standard Words:

  • print
  • println
  • if
  • goto
  • gosub
  • return
  • for
  • next
  • end
  • let<br>
  • rem

  Badge Custom Words

  • led X,Y - control LED, X[0..2] RGB, Y[0..1] on/off
  • tune A,B,C,D - plays tones A, B, C for duration D
  • clrscr - clear screen
  • setxy X,Y - set cursor at X,Y
  • wait X - wait for X ms
  • color X,Y - X=Foreground, Y=Background using EGA 16-color palette
  • chr X - prints character with ASCII representation X
  • termt X - sets VT100 terminal on or off (1-on, 0-off)
  • termup - forces screen refresh, if VT100 terminal is off
  • rnd X - function to return random number 0..X
  • ein X - function to return value of expansion pin X
  • eout X,Y - control expansion pin, X[0..3], Y[0..1] on/off
  • edr X,Y - sets expansion pin function X[0..3], Y[0..1] output/input
  • uin X - function to return received byte from serial port, if X=0, function is non-blocking, if X=1, function is blocking
  • uout X - outputs value X to serial port as single byte
  • input "string" - prints string and returns user entered value
  • peek X - returns value from memory location X
  • poke X,Y - write value Y into memory, on location X
  • cursor X - turns cursor on (X=1) or off (X=0)
  • kin X - function to return byte from keyboard, if X=0, function is non-blocking, if X=1, function is blocking

  BASIC CLI commands

  • run - runs program
  • save X - Save program buffer to flash. There are 16 slots: X[0..15]
  • load X - Load program into buffer from flash. There are 16 slots: X[0..15]
  • list - list whole program
  • more - list program by pages
  • memclr - clears all code from the program buffer
  • free - prints amount of free program buffer
  • sload - load new program into buffer from serial port
  • ssave - output program buffer via serial port
  • help - short help

  Aliases

  In order to save you some typing, we defined some aliases for functions
  

  • print - pnt
  • println - ptl

  • clrscr - cls,clr
  • input - inp
  • setxy - sxy
  • return - ret
  • cursor - cur

• BASIC Program Examples

  Mike Szczys • 05/14/2018 at 21:47 • 0 comments

  Print out all possible characters:

  10 for i=32 to 255
  20 chr i
  30 next i

   Bling the LEDs randomly (d is diode [0..2], s is state [0..1])

  10 d = rnd 2
  20 s = rnd 1
  30 led d,s
  40 print “Press BRK to return to BASIC prompt”
  50 wait 100
  60 goto 10

   Play random Major triads:

  10 let i = rnd,77
  20 if i<53 then goto 10
  30 tune i,i+4,i+7,400
  40 goto 10

   Scroll some text. The space before the text erases the previous character in that position:

  10 let i=0
  20 color 14,12
  30 clrscr
  40 setxy i,0
  50 print " Scroller"
  60 i=i+1
  70 wait 150
  80 if i<32 then goto 40
  90 color 15,0

   Bounce ball on screen. Shows moving to different areas on screen, changing color, using delays and subroutines, and manual screen refresh (term 0 shuts off automatic scanning, termup triggers manual refresh) for a smoother animation than the scroll text example:

  5 termt 0
  10 let x = 39
  20 let d = 0
  30 clrscr
  40 color 11,0
  50 setxy x,10
  60 chr 32
  70 if d = 1 then gosub 200
  80 if d = 0 then gosub 300
  90 chr 254
  95 termup
  100 if x = 0 then d = 1
  110 if x = 39 then d = 0
  120 wait 50
  130 goto 50
  200 x = x + 1
  210 return
  300 x = x - 1
  310 setxy x,10
  320 return

  Function to read byte from serial port and print it out

  10 println uin 0
  20 wait 500
  30 goto 10

  This one starts printing zero every 500ms, if there is any incoming byte from serial port, it gets written out.

  If you change uin parameter from 0 to 1, function gets blocking, ie. execution doesn't continue until serial byte is received. In that case, only when byte is received interpreter prints anything out.

  The same example can be used to read data from keyboard, the function used is called kin.
  

• Music Syntax and Guide

  Mike Szczys • 05/14/2018 at 21:46 • 0 comments

  This badge has a built-in speaker and you can compose music for 3 voices using a simple scripting language. Use the BASIC interpreter to access these features with the syntax: 
  

  tune voice1,voice2,voice3,duration

  Duration is the number of milliseconds this chord should be held. The voice values use Scientific Pitch Notation (https://hac.io/hGf7) where middle C is 60. Do a C major chord held for 1 second would look like this tune 60,64,67,1000 -- below is a cheat sheet.

  PRO TIP: Remember BASIC programs can be saved in any of 16 slots (0..15) using the save/load commands.
  

  As an example, try typing this into your BASIC interpreter (you may want to type clr before your start to clear any existing code):
  

  10 tune 0,0,72,131
  20 tune 0,0,74,131
  30 tune 0,0,77,131
  40 tune 0,0,74,131
  50 tune 70,74,81,262
  60 tune 0,0,0,131
  70 tune 70,74,81,393
  80 tune 60,76,79,524
  90 tune 0,0,0,131
  100 tune 0,0,72,131
  110 tune 0,0,74,131
  120 tune 0,0,77,131
  130 tune 0,0,74,131
  140 tune 69,72,79,262
  150 tune 0,0,0,131
  160 tune 69,72,79,393
  170 tune 62,69,77,393
  180 tune 62,69,76,131
  190 tune 62,69,74,655

• Serial Communications with Badge

  Mike Szczys • 05/14/2018 at 21:46 • 9 comments

  Badge to Badge

  Remember those TI graphic calculators that had a cable to transfer programs? The badges can work in the same way.

  • Connect the GND pins on the expansion header.
  • Connect C14<-->C13 and C13<-->C14 on the two badges.
  • On receiving badge type "sload" and it will wait for program to arrive
  • On sending badge type "ssave". Program will be sent. Receiving badge will report 1 byte more than sending badge to indicate the zero terminator
  • Type list on receiving badge to see new code in the program buffer.

           IMPORTANT TIP: If the receiving badge doesn't react, reset that badge (shift-reset) and try again.                                                   Sometimes this is necessary after first connecting the cables.

  Computer-to-Badge

  A serial-to-TTL cable will allow you to communicate between the badge and a computer. If you own one of this cables we highly recommend you bring it with you! We will have cables on hand but it will be necessary to share them so extras are great!

  Wiring Diagram:

  • Badge Pin Ground (GND) --> Ground on serial cable
  • Badge Pin TX (C14) --> RX on serial cable (White in this example)
  • Badge Pin RX (C13) --> TX on serial cable (Green in this example)
  • Important: Leave voltage disconnected (Red in this example)

  Serial Connection Info:

  • Baud: 19200 8N1
  • In basic, use command ssave to send program buffer as string
  • In BASIC, use command sload to recieve string into buffer
  • CP/M includes xmodem. Check your computer's serial program to ensure it supports this protocol. In the Z80 Emulator, switch to b: drive and run command similar to this: xmdm r d:FILENAME.EXT

  Linux: Simple Instructions for Transferring BASIC Programs

  This quick walkthrough assumes that USB to TTL serial cable will enumerate as /dev/ttyUSB0. Look at dmesg output after plugging cable to ensure this is true.

  Setup simple Linux serial connection:
  

  • dmesg and look for where the serial cable is mounted
  • sudo chmod 777 /dev/ttyUSB0 #Make sure you have access to the USB port
  • stty -F /dev/ttyUSB0 19200 #Set proper baud rate
  • stty -F /dev/ttyUSB0 #Check to make sure rate was set correctly

  Send a File to Badge

  • On the badge, type sload into BASIC
  • On computer type: cat basic.txt > /dev/ttyUSB0
  • On the badge, press BRK

  Receive a File from Badge

  • On computer type: cat /dev/ttyUSB0 > newbasic.txt
  • On the badge, type ssave
  • On computer type CTRL-C

• Guide for Programming in C

  Mike Szczys • 05/14/2018 at 21:46 • 2 comments

  Setting Up the Toolchain

  You will need a PIC programmer to write your own HEX files onto the badge. PICkit 3 and PICkit 4 have both been tested to work as programmers via the pin header on the badge.

  The BASIC badge is based around a PIC32MX370F512H. Software is compiled using MPLABX, XC32 compiler, and legacy peripheral libraries from Microchip.

  1. Download three packages:
     • Navigate to the Downloads" tab at the bottom of the Microchip Compilers page.
     • Download MPLAB® XC32/32++ Compiler v2.05 for your operating system
     • Download PIC32 Legacy Peripheral Libraries for your operating system
     • Navigate to the "Downloads" tab part way down the screen at the Microchip MPLAB X IDE page.
  2. Install the packages:
     • Install the XC32 compiler first
     • Install the peripheral libraries next. IMPORTANT: You must specify the same directory as the XC32 compiler. This will likely not be the default option during install. For Linux installation this director was: /opt/microchip/xc32/v2.05/
     • Install MPLABX IDE
  3. Open the MPLABX project from this repository
     • A PIC programmer like the PICKIT3 is required to program your badge
     • On the PIC programmer, pins 1-5 correspond to RES, V+, GND, B0, and B1 on the badge

  User Examples for C Programming

  The stock firmware includes an example program that has both a menu entry, and many of the commands that will commonly be needed to write your own C code.

  • Selecting user program will run void user_program_init(void) first.
    • This is where you should do all of your program setup. This is a good function to call from your program when you want it to start over again.
  • After the init function is called, void user_program_loop(void) will be called
    • This is where the main functionality of your program should be stored.
    • If this function returns, it will immediately be called again.
  • millis() is a 32-bit upcounting millisecond timer. Non-blocking delays are a matter of setting a variable as millis()+1000 and then polling millis() until it is larger than this variable.

  Advanced

  • The screen defaults to scanning a 40x20 character array (screen will automatically update when array data changes). For direct control of the screen:
    • enable_display_scanning(0); //Turns off auto  screen scanning, value of 1 turns back on
    • view disp.h for screen manipulation functions to use in manual mode

  • When directly controlling the screen, you will want to perform a screen refresh after badge wakes up from sleep
    • There is function pointer in hw.h that will call your screen refresh function on wake. Here is the example for setting which function will be executed (do this in the initialization function of your program):
    • start_after_wake = &you_refresh_function;

• Hardware Hacking

  Mike Szczys • 05/14/2018 at 21:44 • 0 comments

  Front view of expansion Header:

  Here is a rear view diagram of the pin header taken from the badge schematic.

  These pins can be controlled from BASIC using the edir, ein, and eout commands. The UART on pins C13 and C14 can be accessed from BASIC using uin and uout commands. 

  G2 and G3 are 5V tolerant but all other pins should be interfaced at 3V.

• Image Compression Challenge

  Mike Szczys • 05/14/2018 at 21:42 • 1 comment

  As part of the Hacker Village at Hackaday Belgrade we want you to use your best compression tricks to put these images on the badge. Anyone who has an interesting solution to this problem is invited to get up on stage in the evening and give a lightning talk about how small their solution is and how they did it.

  Backstory

  I wanted to include these images as an Easter Egg on the badge (when you type Voja, or Jaromir the image would be displayed). But these 320x240 two-color images are pretty big at 9.6k each as binary arrays and I didn't think we should occupy that much space for this task. I did some preliminary test at run-length encoding but didn't find a great way to make the image information small. Can you do something interesting to take up less space on the badge?

  Compress Compress Compress

  How small can you go? Start a Hackaday.io project to show off your solution and leave the link in the comments below. Anyone who wants to give this a try is welcome to do so, even if you're not at the conference. 

  Images:

  Updated: Originally the image of Voja wasn't binary but this has been corrected.

• CP/M on badge, quick guide

  Mike Szczys • 05/14/2018 at 21:41 • 0 comments

  After you start Z80 emulator with CP/M, the machine boots up on A drive greeting you by prompt

  A>

  There is not much to do with this drive, as it is 22kB RAM disk. It is empty after boot, as you can try with command

  dir

  that prints what is in current directory. You can switch to disk B, where is more to be found

  b:

  and system will respond with

  B>

  meaning you are there. You can now list content of this directory again and discover a few executable (.COM) files, like XMDM, MBASIC or FORTH. You can play around with those; notice that some of them expect different line (CR) end than what badge uses (LF). You can do CR line end by hitting SHIFT+ENTER. Exit MBASIC by typing system<CR>.

  On disk C you have some more goodies, namely famous ZORK game and SARGON chess game.

  Disk D is empty, with 512kB of capacity. You can copy files to/from disks utilizing PIP program, with syntax of

  pip d:=c:zork1.com

  that will copy file zork1.com to drive d. Notice you should run this one from disk B, where pip resides, or explicitly set path to pip program.
  

  If you want to erase the file, just type

  era d:zork1.com

  If you happen to need to list ASCII file, invoke command

  type file.txt

  or dump binary file in hexa form by running

  dump file.bin

  Stat command is used to display statistics of a file or drive; you can run
  

  b:stat
  

  to display info of drives or

  b:stat *.*
  

  to display information about all files on particular drive. Notice the wildcards - you can use it when copying or erasing the files too.

  If you want to transfer files from computer (or perhaps another badge), you may use XMODEM program. Run

  b:xmdm r d:filename

  to start saving received file on D drive, and start XMODEM transfer on other side. The transfer speed is 19200 baud. You may try to archive files into ARC format and un-arc it on CP/M side with dedicated software, if you want to transfer more files. On linux, you may want to use sx to transfer files, or moserial or cutecom for GUI access, with windows, teraterm is good option.
  

  You may want to try assembler toolchain consisting of ED editor, ASM assembler, LOAD program to convert hex to .COM file and DDT debugger. There is quite a lot of Z80 CP/M software on the interwebs, you may want to look for "walnut creek CP/M CD". Be prepared that a lot of CP/M software was designed for modified machines, sidetracking BIOS, so it may not run on this particular machine.

  Notice badge has option to switch from local standard input/output (keyboard/display) to serial port (on pins C13 and C14 on expansion port, 3,3V levels, don't forget ground) by pressing LSHIFT+RSHIFT+BRK; with the same combination taking you back to local access. You may access the command line using terminal emulator on your PC, gaining somehow more comfortable access.
  

  You can find more details about the CP/M commands and programs here and here.
  

• Reserved for Future Use

  Mike Szczys • 05/14/2018 at 21:41 • 0 comments

  There's a lot to document so we're keeping a few logs as placeholders.

View all 9 project logs