... "StampDock" software Copyright 2008-2010 by Arend-Paul Spijkerman

Email: ap@apsdev.com Site: www.apsdev.com/stampdock/


"StampDock" is software that offers services to "BASIC Stamps", "Javelin Stamps" or microcontrollers through the
existing serial connection to the PC used to program the "BASIC Stamp".
A "BASIC Stamp" can use it to for instance display graphics, or store/read data on harddisk or in PC memory.
Also the software can be used as an input/output device as it can provide virtual switches, potmeters,
indicators and meters. Also it can be used for sound with MP3 files, video files or provide digitized speech.

It was made because i wanted to display measurements in graphics, but the LCD displays available
where too limited and expensive. Also it was not that easy to store data collected by a "BASIC Stamp".
I realized there was a PC connected to the "BASIC Stamp", so i decided to make a graphics display emulator.
You can use line commands to draw graphs, but also plot dots in full color to do a "scan".

So you can show, store and control a measurement or process while you only need hardware
for the measurement or process besides the "BASIC Stamp".


Features:

-Provides a big full color graphical display, which can be saved to disk as picture on command.
-Provides an editable GUI for "BASIC Stamps" with buttons, indicators, regulators, meters etc etc.
-Provides an ANSI (color) text window for debug text output.
-Can use the harddisk of a computer to store or load data.
-Provides a 64KB ramdisk.
-Has a system so a "BASIC Stamp" can detect if it is connected (docked) to a PC to store collected data.
-Can play MP3 and video files or streams in the window started from the "BASIC Stamp".
-Can generate synthesized voice sound and beep sounds.
-Can send text messages to a log file with time and date.
-Provides a Real time clock.
-Runs on Windows and Macintosh (should also run on Linux).
-Remembers the last used serial port and speed from a previous run.


Functionality has be expanded over time.
There is a command to check if a "BASIC Stamp" is connected to the software, so the "BASIC Stamp" can check if
it is "docked" and then send all its collected data to the PC for storage.
Also the "BASIC Stamp" can read data files from PC.
It can display graphics, using colored plot, lines and rectangle commands.
It can even save the graph to disk using the IFF file format.
It is also capable of reporting mouse clicks in the graphics screen, so you could
use it to control you application via a drawn GUI in the graphics pane.
The software is able to make sound, like digitized voice or simple "beep" through the PC speaker.
It can even play sound and video files like MP3, WMV or MPEG using DirectX and Quicktime.
The "BASIC Stamp" can request the time from the PC like it is a Real Time Clock.

So using this software makes using a "BASIC Stamp" a little easier as you don't
need to connect a graphical display, speaker or storage chip .. so you save
a lot of I/O pins which you can use to collect data, or drive hardware.

It also has a regular debug window for text, in which ANSI color codes can
be used. The GUI of the program is completely configurable with a text file.
The fields can be enlarged, parts can be removed, it can be made fullscreen etc.
Als the GUI has a button to reset the "BASIC Stamp", which sets the DTR line for 1/50th of
a second.


Stampdock works by sending command strings from the "BASIC Stamp" using the 'Debug' command to the PC.
There are two types of command strings, one starting with a ! that does not
give a response from PC .. and a type starting with a ? which is more like
a Request as the PC is sending back data over the serial connection which
can be read with the 'Serin' command.
After the ! and ? which can considered an escape character follows a letter
which is the funcionality (command) of the string. After the command
a text or a list of numbers can be given depending on the command.
The string is ended with a ; character.

Examples:

Draw a line from 10,80 to 80,10:

DEBUG "!l10,180,80,110;"

Draw a line from x,180 to 80, 110:

DEBUG "!l",DEC x,",180,80,110;"

Check if the software is running:

DEBUG "?x;"
SERIN 16, 16624, [x] ' for "BASIC Stamp" BS2p 24
PAUSE 1
if x <> 170 THEN skip 17
DEBUG "!h200,120;!tError;" ' write Error to positon 200,120
skip17:
if x = 170 THEN skip 18
DEBUG "!h200,120;!tCorrect;" ' write Correct to positon 200,120
skip18:


There exists Windows, Mac and linux versions of the software.



===================( usage )=================

Note that you need to select a serial port and speed in the GUI of the program of
the "BASIC Stamp" you want to use.
Note that if you change the default port and speed, the program will store it in
a human editable/readable file on disk. So you need to set it only once.

For a "BASIC Stamp" select 9600 baud, and for a "Javelin Stamp" 28800 baud.

On a PC the build in serial port seems to be COM1 or COM2.
I tried a USB-Serial adapter on windows and it seems to appear as COM8.

Note that on Mac at the moment the port number settings have no influence,
to software will use the first USB-serial adapter it finds in the system.

Note that the Mac PPC version seems to run better as the Mac Intel version on Intel Macs.

Note that the software has a "Scan" button that will try to locate the "BASIC Stamp"
port by sensing the connected DSR and RTS pins.
But if you have a bluetooth adapter that has a port number lower as the "BASIC Stamp"
port that might be detected instead of the "BASIC Stamp" port.

The software also has a "Reset" button that resets the "BASIC Stamp".


================ GUI ======================

The GUI of the program is defined in the stampdock/stampdock.rsrc text file.
Note that the file was edited on a Mac, which might have influence if you try to edit it on a PC.

The default GUI has some GUI elements of every type, so you can start developing without
the need of adding GUI elements. You can add or remove elements later.

You can edit the GUI file so some elements like the video element can be made bigger,
also parts can be removed or added or put on another place.

In the GUI you can use pictures, background colors or patterns, tabs or triangles.
The window can even be made fullscreen.

Note that GUI development is described in another document.


===================( technology )=================


The software uses the serial connection normally used to program a "BASIC Stamp".
As "BASIC Stamps" have some commands to use the serial connection for debugging,
those commands can be used to encode commands for the stampdock software in the
debug output.


"BASIC Stamp":

To send data from a "BASIC Stamp" to the software set the baudrate at 9600 and
use the debug command.

DEBUG "!i21,10;" (sets the value of GUI element 21 to 10)
DEBUG "?i21;" (requests the value of GUI element 21)

Use something like this to send values of variables:

DEBUG "!i41,",DEC x,";" (sets the value of GUI element 21 to 'x')


To read data from the software you need the SERIN command.
With the SERIN command you need to specify a number which is the baudrate,
but the number for 9600 baud is different for some "BASIC Stamp" types.

x VAR Byte
SERIN 16, 16468, [x] ' 9600 baud for BS2 , BS2e and BS2pe
SERIN 16, 16624, [x] ' 9600 baud for BS2sx , BS2p
SERIN 16, 16780, [x] ' 9600 baud for BS2px


In more modern pbasic compilers you can use the DEBUGIN command, which is a
special case of SERIN where you dont need to specify baudrate.


DEBUGIN x ' requires pbasic 2.5 compiler .. special case of serin
DEBUGIN DEC x ' requires pbasic 2.5 compiler .. special case of serin


If you need to use the SERIN command you can put a macro at the start of your
program which determines the value you need to put for baudrate:


' {$PBASIC 2.5}
' set Baud for 9600-N81
#IF ($STAMP = BS2sx) OR ($STAMP = BS2p) #THEN
Baud CON 16624
#ELSE
#IF ($STAMP = BS2px)
Baud CON 16780
#ELSE
Baud CON 16468
#ENDIF
#ENDIF

So you can use something like this:


SERIN 16, Baud, [DEC x] ' read byte from serial port


Important !!

Note that you need to put a "pause" of a millisecond between SERIN and DEBUG so the
serial bus can settle. As the "BASIC Stamp" uses the receive data line as a 12v supply
for the send line, which means you cant receive and send at the same time.


SERIN 16, 16486, [X] ' read byte from serial port
PAUSE 2 ' pause some millisecs
DEBUG "!i41,",DEC x,";" ' write value x to indicator with id 1041





"Javelin Stamp":

for "Javelin Stamps" set the serial speed to 28800.
Use the println or print commands to send data to the software:

System.out.println("!a123;");
System.out.print("!a123;");

If you need to send variable values to the software use a couple
of print commands to send all parts of the command.

int x = 123;
System.out.print("!a");
System.out.print( x );
System.out.print("," );
System.out.print( y );
System.out.print(";" );

In theory you could also put the whole command in one print command, but as the
javelin has no garbage collection, its memory will fill up, as string build can not be recovered.
So if you use to much of these commands the javelin will not be able anymore to send commands.

int x = 123;
System.out.println("!a"+x+";"); // DONT USE THIS !

To read data from the stampdock software you can probably use the getChar command, but i have
not tested that yet.
But as the getChar command does not return until it actually reads a character you might want to use
the byteAvailable command to check first if there is data set ready before doing any reading.

Terminal.byteAvailable() return true

char c;

System.out.print("?a123;"); // request data
CPU.delay(10); // wait 1 milliSec
c = Terminal.getChar() // read data

Or maybe it is possible to use the UART class ?



MicroControllers:

The Software should work with microcontrollers too, but i have not tried it yet so you need to find
out yourself how to send or receive serial data.
However, I might try it with a scenix/ubicom SX28 in the near future.




Commands are loosly based on the old ANSI codes which where used to have color in old terminals.
So commands are in human readable text form.

Commands start with an escape character, then a command character, followed by numbers separated by commans and terminated
with a semicolon.
Some commands can have a textstring instead of numbers.

The escape character is either a '!' for commands, or '?' for a request of data. So in the last
case the software will be sending data back over the serial port.

The command character is a letter from 'a' to 'z', right now it is case independant .. so you can
user lowercase and uppercase character but they give the same result.
It might be wise to only use lowercase characters, as in the future uppercase characters
might be used for new commands.


Give a command: "!i21,10;" sends command 'i' with parameters 21 and 10.
Give a command with string: "!zText\r\n;" sends command 'z' with "Text\r\n" as argument.
Request data: "?i21;" request data with command 'i' and parameter 21.








==================( commands )=======================



Available Commands:

(try to use lowercase commands, as the next version will probably be case sensitive)

As of version 2.10 commands are case sensitive, which means old commands are lower case
and newer commands are upper case.


================ General ====================


check if software is running ?x; reply is one byte with value 170

quit the software !q27; value must be 27 or else it is ignored

Get time/ticks ?t0; returns 4 bytes with ticks (1/50th of a sec) MSB first
?t1; returns 8 bytes with the time

Time is encoded as following : first 2 bytes is year, followed by bytes with month, day, hour, minute, second and tick


================ File I/O ====================

There can be 2 files open at the same time, one for reading, one for writing
To open a file the !oN; or ?oN; command is used, where N stands for the functionality.
Use a ? for opening a file for reading, and a ! for opening a file for writing.
If N is zero it means close file, 1 means open file add timestamp to the name,
2 means add value NNN to the name, and 3 means no number in name.

Open or Close file for reading ?o1; open file using timestamp
?o2,nnn; open file using nnn in name,
?o3; open file with no number in name
?o0; close file

Open or Close file for reading ?Oname; open file with file name
?O; close file

reply is 4 bytes with file size MSB first

Read data from disk ?eNNN; read n bytes
?e; read one byte


Open or Close file for writing !o1; use timestamp
!o2,nnn; use nnn in name,
!o3; no number
!o0; close file

Open or Close file for writing !Oname; open file with file name
!O; close file

Write data to disk !e123,211; !eNNN,NNN,NNN,NNN; (up to 40 numbers per 'e' command)
Write text to disk !zText\r\n;

================ Graphics ======================

You can control your "BASIC Stamp" through a GUI, with the graphics commands you can draw buttons,
and then you can "poll" the software to check if there was a mouse click.

Report mouse click ?m; returns 3 bytes , byte 1=clicked, byte 2=x, byte 3=y

save screendump as IFF file to disk !y;
windowsize/mode !m101,101;
draw grid/array voor scope in current color !a10,10; xspace,yspace,xlines,ylines,xoffset,yoffset
home (or set plot position) !hXXX,YYY; !h10,10; (for position 10,10)
!h; (for position 0,0)
text to graphics display !tText\r\n;
bell ? !t\a;
Sound (System beep for now) !k;

A command for clearing the output in current col !c;
A command to set current plot color !s100,200,300; !sRRR,GGG,BBB; !sRRR,GGG; !sRRR; !s; (is black)
A command to set current gray shade !f123; !fGGG;
A command to plot a dot in current color !p123,321; !pXXX,YYY;
A command to plot a line in current color !l123,321,0,0; !lXXX,YYY,XXX,YYY;
A command to draw a rectangle !r10,20,30,40; !rXXX,YYY,XXX,YYY;

The following commands draw on current position and increase x position, so to draw a "scan"
you first set the start position, and then you can send a stream of plot commands where you
only need to send the color wanted.

plot in color !d100,200,150; !dRRR,GGG,BBB;
next pixel in a certain grey shade like !g125; !gGGG;
the next N pixels in white !w10; !wNNN; (nnn pixels) !w; (1-pixel)
the next N pixels in black !b16; !bNNN; (nnn pixels) !b; (1-pixel)


================ Version 2 ======================

Digitized voice (set) !nText;

start mp3/video (set) !Vfile.mp3;
stop mp3/video (set) !V;

log file (set) !Ltologfile;


Gui commands:

From version 2, the software has GUI elements.
GUI Elements are input or output elements that can be placed in the GUI, they can
be read or set from the "BASIC Stamp".
The GUI can be redesigned by editing the stampdock.rsrc file, which means elements
can be moved around, added or removed.
Up to 256 active GUI elements can be used in a GUI at the moment (probably more).
Note that GUI elements have an ID in the stampdock.rsrc of 1000 and higher.
But from the "BASIC Stamp" they are called with an ID of 0-255 .. so you have to subtract 1000.

Current GUI Elements are:

indicators: RGB LEDS , Analog meters, bar graphs, text fields.

Regulators: slide switches, potentio meters, toggle switches, buttons, checkmarks, string gadgets.
(slide switches and potentio meters can be horizontal or vertical)

(note that regulators can not only be used for input but also for output as the
"BASIC Stamp" can control their position.

There are a couple of commands to control GUI elements, with the command 'j' you can set color of an RGB LED.
the first number after the j is the ID in the GUI resource file minus 1000.
Followed by 3 numbers for Red, Green and Blue values. Or one value that indicates the state.
Where 0 is black, 1=red, 2=green, 3=blue and 4 is white.

To control the other GUI elements the 'i' command is used.
The i is followed by the the ID number in the GUI resource file minus 1000.
After that you place the value you want to set it too, which can be from 0 to 255.
Note that the value of most GUI elements can also be read.



RGB LED (set) !j123,rrr,ggg,bbb; // set LED color to R,G,B
!j123,nnn; // n=0 black, n=1 red, n=2 green, n=3 blue, n=4 white
Meter (switch,pot,text) (set) !i123,vvv; // sets value to 'v'
!i123; // sets value to zero
Switch, Potentio (read) ?i123; // returns 1 byte with value

A little example .. to read Potmeter with ID 1040, and write that position to potmeter with ID 1041, so
if you slide one potmeter the other will follow its position if used in a loop:

x VAR Byte
DEBUG "?i40;"
SERIN 16, 16486, [X]
PAUSE 2 ' millisecs
DEBUG "!i41,",DEC x,";"


GUI elements that currently support the 'i' command:

Checkmarks:
These are basically on/off switches from which the state can be read with the 'i' request,
they can also be set or reset with the 'i' command from the "BASIC Stamp".
You can also use them as a sort of start button if you reset the state to 0 with the 'i' command
if they where set by the 'i' request.

Switches:
These are 'slide' switches that can have 2 or more positions, they can be read with the the 'i' request.
You can also put them in another position from a "BASIC Stamp" with the 'i' command.

Potmeters:
These are regulators that return a value of 0-255 depending on the position of the slider.
You can also set them by a "BASIC Stamp" to send to them a value of 0-255.

analog meters:
These are analog indicators that of which the position can be set by sending them a value of 0-255.

text numbers:
These are text fields in which you can display a number by sending a number value from a "BASIC Stamp" with the 'i' command.

number stringgadget:
These are text fields with manual input that can be read and written from a "BASIC Stamp".

balans:
These are indicators that can display 3 colored up, middle or down arrows or block.
The first three bits of the value send indicate of the arrows or block are 'on'.

buttons:
A "BASIC Stamp" can use the 'i' request to check if a button has been clicked, if a button
has been clicked one or more times the value '1' is returned.
Note that buttons remember the number of times they are clicked, so if a button was clicked
twice .. before a read it will still return twice with the value '1'.



Element ID numbers used in the default GUI definition:

LEDS: IDs 1000-1009 (use 0- 9 as ID in 'j' commands)
Checkmarks: IDs 1010-1019 (use 10-19 as ID in 'i' commands)
horizontal switches: IDs 1020-1029 (use 20-29 as ID in 'i' commands)
vertical switches: IDs 1030-1039 (use 30-39 as ID in 'i' commands)
horizontal potmeters: IDs 1040-1049 (use 40-49 as ID in 'i' commands)
vertical potmeters: IDs 1050-1059 (use 50-59 as ID in 'i' commands)
analog meters: IDs 1060-1069 (use 60-69 as ID in 'i' commands)
text numbers: IDs 1070-1074 (use 70-74 as ID in 'i' commands)
number stringgadget: IDs 1075-1079 (use 75-79 as ID in 'i' commands)
balans: IDs 1080-1089 (use 80-89 as ID in 'i' commands)
Buttons: IDs 1090-1099 (use 90-99 as ID in 'i' commands)



Ramdisk commands:

To access the ramdisk of 64Kbyte you first set the address of the byte you want to access,
and then you give read or write commands. Note that the read and write commands increase
the address counter of the ramdisk .. so you only need to set the address for a sequence
of reads or writes once .. which increases throughput on the serial port.

RamDiskaddress (set) !u768; // set address to 768
!u123,4; // set address to 123 + 4 x 256
!u; // set address to zero
RamDiskWrite (set) !v123; !vnnn,nnn; // (up to 40 numbers per 'v' command)
RamDiskRead (read) ?v; // read a byte from the ramdisk






================ Changes ======================


Changes:

Put all the internal data like GUI resources in a directory called stampdock
Added buttons for higher serial speed, for use with microcontrollers with high speed serial connection.
Added offset and number of lines parameters to the grid command
fixed triangles in the GUI not opening


Todo:

finish internet support
sin, cos and random commands ?
command to change GUI files
enhance sound command
command for more control over mp3/video player

Setup used to test software.

[ click to enlarge ]

This is a "BASIC Stamp" from Parallax it is a tiny controller which can be programmed very easily from a PC. It has space for kilobytes of program code and dozens of bytes for variables.