USING THE AMULET EASYGUI STARTER KIT WITH A PARALLAX BASIC STAMP AND AN ANALOG DEVICES ADXL202EB

Transcription

1 USING THE AMULET EASYGUI STARTER KIT WITH A PARALLAX BASIC STAMP AND AN ANALOG DEVICES ADXL202EB INTRO The Amulet EasyGUI Starter Kit not only works well for rapid prototyping, but also fast product implementation and easy, seamless development. In combination with another microprocessor and a peripheral I/O device, the Amulet GUI is a powerful technology. In this experiment, we will be using a Basic Stamp 2 as the externally interfaced microprocessor (because of its popularity and wide spread use in the embedded industry) and an Analog Devices accelerometer specifically part number ADXL202EB, which is a ±2 g dual-axis accelerometer. This app note will specifically highlight the hardware setup and software communications protocol, not the user interface created to demo this experiment.. HARDWARE CONNECTIONS The easiest way to set up this system is to use a Basic Stamp Carrier Board with the Basic Stamp (preferably a Basic Stamp 2 or faster due to timing issues which will be talked about later, click here to jump to that discussion) to talk to the Amulet EasyGUI board via a RS232 (serial) cable. This setup allows for easy connection of the ADXL202EB and Carrier Board for debugging and programming in addition to connecting to the Amulet unit once the Stamp has been programmed. The schematic for the connection between the Stamp and the board is shown below. Basic Stamp Super Carrier Board gnd self test x axis y axis +5 E B D C A ADXL202EB Figure 1. Schematic of Stamp connection to the accelerometer

2 Figure 2. Picture of Basic Stamp, Basic Super Carrier Board, and Analog Devices ADXL202EB accelerometer AMULET PROTOCOL (taken from The communications protocol is half-duplex, with the Easy GUI client acting as master. The Amulet GUI can send five different types of messages: A "Get" byte variable request (Amulet:UART.byteValue()) A "Get" word variable request (word = 2 bytes) (Amulet:UART.wordValue()) A "Get" string variable request (Amulet:UART.stringValue()) An "Invoke" Remote Procedure Call (RPC) (Amulet:UART.invokeRPC()) A "Set" byte variable command. (Amulet:UART.setByteValue()) If the message is valid, the Stamp should either return the requested data (if a "Get" request) or acknowledge the message (if an "Invoke" or "Set" command). If the message is not valid, the server should respond with an acknowledge (0x10). Table 1 in Appendix A defines the five types of messages that can be sent between the GUI and the Stamp. The valid range of variables and Remote Procedure Calls is 0-0xFF. The valid range for variable values returned from the Stamp (in response to the "Get" variable request) is also 0-0xFF. Since this is an ASCII protocol, it takes two bytes to send one-byte variables and RPCs. For example, the variable 0x1A would be transmitted as 0x31, 0x41, where 0x31 is the ASCII representation of the high nibble"1" and 0x41 is the ASCII representation of the low nibble "A". NOTE: The Stamp side must respond to every valid GUI command. It is always acceptable to respond with an acknowledgment. When commands are not responded to within 100ms, a time-out will occur, which then clears out all pending requests. This can result in unexpected behavior.

3 Synchronization--As master, the GUI initiates all communications by sending a message to the Stamp. All valid messages from the GUI to the Stamp start with one of five command bytes: [0x11], [0x12],[0x13],[0x14] or [0x15] -- these are considered the Client Start Of Message (CSOM) characters, with the GUI being the client. NOTE: These five CSOM bytes ALWAYS signify the start of a message and they are not allowed in the body of any message. The only valid characters in the body of a message are: ASCII 0-9 (0x31-0x39), and A-F (0x41-0x46), except in the body of the "Get string" response, where all ASCII characters from '0' -' ~' (0x30-0x7e) are valid. If the Stamp receives any character other than those specified, the message should be considered errant, and the Stamp should start over hunting for a new CSOM character. All Stamp responses must start with the counterpart of the CSOM character that began the message that is being responded to. The valid Server (Stamp) Start Of Message (SSOM) bytes are: [0x21], [0x22], [0x23], [0x24] or [0x25]. The body of the response message starts with the counterpart SSOM and is then followed by any optional response data (in ASCII format). As noted earlier, after receiving the last byte of a valid message from the GUI, the Stamp then has 100ms to respond to the message before the GUI times out. After 100ms, if there is no response, the GUI will consider the message dropped, flush its buffer, and then be ready to transmit any new messages. The GUI will NOT repeat a message after a TIME OUT. SOFTWARE INTERFACE An abbreviated version of the communication protocol used to make the GUI, Stamp, and accelerometer communicate is shown below. The software used to program the Stamp can be found at the following link: The following code snippets were taken from an actual server implementation based on the Basic Stamp 2 micro controller. The code simply polls the serial line with the SERIN command until a valid request is received, handles the request using the IF statements to determine what the GUI is asking for, and then returns to polling the serial line. This sample code, showing only the service routines, is meant to illustrate the workings of the Amulet protocol not implement it. The entire code can be found in Appendix B. serial_in: '*This function will poll the serial line looking for values. It will store the first byte in RxType, *the next in VarType1, the third in VarType2, the fourth in SetVar1, and the fifth in SetVar2. *RxType stores the client s request type, VarType1/2 store which variable is being used, and *SetVar1/2 store which setbyte parameter are being set and are uninitialized otherwise. The *program will hang until all of these variables are filled

4 SERIN 16, 84, [RxType, VarType1, VarType2, SetVar1, SetVar2] IF RxType = $13 THEN setbyte IF RxType = $11 THEN getbyte IF RxType = $12 THEN getstring IF RxType = $14 THEN RPC IF RxType = $15 THEN getword IF RxType > $15 THEN serial_in asking for a setbyte 'asking for a getbyte 'asking for a getstring 'asking for a RPC 'asking for a getword 'value on line is not a function, go back to wait for another command '* Handler for a getbyte function request '* Format of request string = 0x11xx, where xx = variable being requested '* Returns 0x21xxNN, where NN equals the HEX data of the variable xx getbyte: ServerResp1 = $21 IF VarType2 = "5" THEN RateReturn IF VarType2 = "6" THEN TimeReturn IF VarType2 = "7" THEN VariableReturn Variable 5 is being requested so return value stored for rate (in register B20) RateReturn: SEROUT 16,84,[ServerResp1, VarType1, VarType2, HEX2 B20] Variable 6 is being requested so return value stored for time (in register B22) TimeReturn: SEROUT 16,84,[ServerResp1, VarType1, VarType2, HEX2 B22] Variable 7 is being requested so return value stored for variable (in register B21) VariableReturn: SEROUT 16,84,[ServerResp1, VarType1, VarType2, HEX2 B21] '**************************************************************************** '* Handler for a getstring function request '* Format of request string = 0x12xx, where xx = index of string variable '* Returns 0x22xxString+Null to client '**************************************************************************** getstring: ServerResp1 = $22 IF VarType2 = "2" THEN Author_string IF VarType2 = "3" THEN Company_string IF VarType2 = "4" THEN Version_string Variable 2 is being requested, return string associated with that variable Author_string: SEROUT 16,84,[ServerResp1, VarType1, VarType2, "Jacob Horn", NULL] For brevity, the remainder of the string requests have been left out the remaining variables simply request different string values (in the same format as the Author_string)

5 '*********************************************************************** '* Handler for a setbyte function request '* Format of request string = 0x13xxNN, where xx = variable to be set '* and NN = HEX data '* Returns 0x23xxNN to client '*********************************************************************** setbyte: ServerResp1 = $23 IF VarType2 = "5" THEN Rate IF VarType2 = "6" THEN Time IF VarType2 = "7" THEN Variable Variable 5 has been called to be set Rate: Choose which parameter associated with rate is to be set, using NN values IF SetVar2 = "0" THEN one IF SetVar2 = "1" THEN two IF SetVar2 = "2" THEN five IF SetVar2 = "3" THEN ten one: two: five: ten: B20 = 1 B20 = 2 B20 = 5 B20 = 10 Variable 6 has been called to be set Time: Once again, choose which parameter is to be set using NN values IF SetVar2 = "0" THEN tenseconds IF SetVar2 = "1" THEN thirtyseconds IF SetVar2 = "2" THEN fourtyfiveseconds IF SetVar2 = "3" THEN sixtyseconds tenseconds: B22 = 10 thirtyseconds: B22 = 25 fourtyfiveseconds: B22 = 45 sixtyseconds: B22 = 60 Variable 7 has been called to be set

6 Variable: IF SetVar2 = "0" THEN x IF SetVar2 = "1" THEN y Note that GUI protocol send ASCII representations of numbers, so the format of the numbers upon appearance in the GUI will depend on the formatters used (i.e. decimal format of the ASCII X and Y will return 88 and 89, where as a hex format will return 58 and 59) x: B21 = "X" y: B21 = "Y" setbyteresp: SEROUT 16,84,[ServerResp1, VarType1, VarType2, SetVar1, SetVar2] '* Handler for a invoke function request '* Format of request string = 0x14xx, where xx = variable of function being requested '* Returns 0x24xx to client or 0x10 (and ACK) RPC: Invoke command calibrates the +1g and 1g values for both the X and the Y directions Only an ACK response is needed back ServerResp1 = $10 SEROUT 16,84,[ServerResp1] IF VarType2 = "8" THEN posx IF VarType2 = "9" THEN negx IF VarType2 = "A" THEN posy IF VarType2 = "B" THEN negy The user at this point would be prompted to position the accelerometer to read the positive X forces and a pulse on the X port pin here saves the value of +1g on the X axis posx: PULSIN 4,1,positiveX Data gathered for the 1g value on the Y axis, then subroutine called to calculate the numerical difference between the +1g and 1g values negx: PULSIN 4,1,negativeX GOSUB calc_deltax calc_deltax: deltax = positivex - negativex RETURN For brevity, the routine for calibrating the Y axis has been left out

7 '* Handler for a getword function request '* Format of request string = 0x15xx, where xx = variable being requested '* Returns 0x25xxPPNN, where PP = high byte of variable xx, and NN = low byte of variable xx getword: ServerResp1 = $25 IF VarType2 = "1" THEN YWORDvariable 'Pulse X port pin, read, and save out x acceleration values PULSIN 4,1,xWord 'calculate the scaled g-force value of xword 'xword = (20/deltaX)*(xWord - negativex) + 40 ServerResp2 = xword.highbyte ServerResp3 = xword.lowbyte 'server data sent out over RS232 to client SEROUT 16,84,[ServerResp1, Va rtype1, VarType2, HEX2 ServerResp2, HEX2 ServerResp3] For brevity, the Y acceleration data sampling has been left out. The only difference seen in the Y routine is the port pin number that is used to read and store out the acceleration values is changed to the pin associated with the Y axis of the accelerometer (pin 2 in this case Figure 3. Picture of Amulet GUI attached to the Basic board via a serial cable

8 IMPLEMENTATION OBSERVATIONS While implementing this system there where a few interesting issues that popped up, most dealing with timing concerns. Due to the fact that the serial communications done on the Stamp are done through a software UART (which means there is no serial buffer and that the Stamp can either be using the UART or doing some other type of processing, not both). The combination of the Stamp communication scheme with the Amulet GUI leads to race conditions. The most notable race condition occurs when the GUI requests information from the stamp. The Stamp must listen to the serial line until something is received and at that point process the data that it has received. In some cases GUI requests will be dropped because the Stamp is still processing the previous instruction. In addition to these race conditions we found it difficult to process multiple sized byte requests to be handled i.e. all the Amulet function requests are 3 bytes long, except the setbyte() which is 5 bytes. We would have liked to use a routine like the one that follows: SERIN 16,84,[RxType, VarType1, VarType2] IF RxType <> $13 THEN nomorebytes SERIN 16,84,[SetVar1, SetVar2] nomorebytes: IF RxType = $11 THEN getbyte IF RxType However, we found the routine above to be unable to handle the GUI requests properly, so we went with the code shown earlier. To alleviate these issues, the Amulet OS now supports the Basic Stamp. A META tag, BASICStamp, which inserts a 4ms pause between GUI requests and puts all the GUI requests in uniform 5 byte segments, was added between the Stamp response (ACK) and the next request. In other words, the request for information had to be slowed down. These fixes can be added simply by including the following line in the HTML of your UI: <META NAME="Amulet" Content="BASICStamp"> Once again, tag seen above invokes a 40 ms delay in the GUI requests to the Stamp, and initializes all GUI requests to have the same 5 bytes per request format. We also found that there is no need to interface it to another chip (i.e. something like a Maxim 233A) to provide true serial levels.

9 Appendix A Table 1. Five types of messages can be sent between the client and the server.

10 Appendix B ****** *The main loop of this code waits for valid Client Start of Message (CSOM) characters then jumps to *the appropriate service routine ****** '{$Stamp BS2} ********* '* Pin setup /********* LOW 8 'set PIN8 = GND HIGH 0 'set PIN0 = +5 INPUT 2 'set PIN2 (C on Accel) as Ay input INPUT 4 'set PIN4 (D on Accel) as Ax input LOW 6 'turn self test OFF ****************** '*Variable declarations ****************** NULL CON 0 'Null character for end of getstring ServerResp1 VAR BYTE 'ServerResp variables set up to contain the values that will ServerResp2 VAR BYTE 'be sent back to client (GUI) from the server (Stamp) ServerResp3 VAR BYTE xword VAR WORD 'This variable stores X axis accelerometer data RxType VAR BYTE 'This section of variables stores the data that comes in off the VarType1 VAR BYTE 'serial line from the GUI (RxType = function type, VarType1 VarType2 VAR BYTE and VarType2 = variable bits, and SetVar1/SetVar2 = SetVar1 VAR BYTE parameter bits) SetVar2 VAR BYTE positivex VAR WORD 'These variables are used by the invoke function to store the negativex VAR WORD g force configuration data that is collected during the config deltax VAR BYTE 'process '************* '* Main Loop '************* serial_in: '*This function will poll the serial line looking for values. It will store the first *byte in RxType, *the next in VarType and the third in VarType2. The program *will hang until all of these *variables are filled

11 SERIN 16, 84, [RxType, VarType1, VarType2, SetVar1, SetVar2] IF RxType = $13 THEN setbyte IF RxType = $11 THEN getbyte IF RxType = $12 THEN getstring IF RxType = $14 THEN RPC IF RxType = $15 THEN getword IF RxType > $15 THEN serial_in asking for a setbyte 'asking for a getbyte 'asking for a getstring 'asking for a RPC 'asking for a getword 'value on line is not a function, go back to wait for another command '* Handler for a getbyte function request '* Format of request string = 0x11xx, where xx = variable being requested '* Returns 0x21xxNN, where NN equals the HEX data of the variable xx getbyte: ServerResp1 = $21 IF VarType2 = "5" THEN RateReturn IF VarType2 = "6" THEN TimeReturn IF VarType2 = "7" THEN VariableReturn Variable 5 is being requested so return value stored for rate (in register B20) RateReturn: SEROUT 16,84,[ServerResp1, VarType1, VarType2, HEX2 B20] Variable 6 is being requested so return value stored for time (in register B22) TimeReturn: SEROUT 16,84,[ServerResp1, VarType1, VarType2, HEX2 B22] Variable 7 is being requested so return value stored for variable (in register B21) VariableReturn: SEROUT 16,84,[ServerResp1, VarType1, VarType2, HEX2 B21] '**************************************************************************** '* Handler for a getstring function request '* Format of request string = 0x12xx, where xx = index of string variable '* Returns 0x22xxString+Null to client '* Returns requested data back to the screen '**************************************************************************** getstring: ServerResp1 = $22 IF VarType2 = "2" THEN Author_string IF VarType2 = "3" THEN Company_string IF VarType2 = "4" THEN Version_string IF VarType2 = "4" THEN Version_string IF VarType2 = "C" THEN Accelerometer_string IF VarType2 = "D" THEN Stamp_string IF VarType2 = "E" THEN Board_string

12 Author_string: SEROUT 16,84,[ServerResp1, VarType1, VarType2, "Jacob Horn", NULL] Company_string: SEROUT 16,84,[ServerResp1, VarType1, VarType2, "Amulet Technologies", NULL] Version_string: SEROUT 16,84,[ServerResp1, VarType1, VarType2, "Version 2.0.1", NULL] Accelerometer_string: SEROUT 16,84,[ServerResp1, VarType1, VarType2, "Analog Devices ADXL202EB", NULL] Stamp_string: SEROUT 16,84,[ServerResp1, VarType1, VarType2, "Basic Stamp 2", NULL] Board_string: SEROUT 16,84,[ServerResp1, VarType1, VarType2, "Super Carrier Board", NULL] '*********************************************************************** '* Handler for a setbyte function request '* Format of request string = 0x13xxNN, where xx = variable to be set '* and NN = HEX data '* Returns 0x23xxNN to client '*********************************************************************** setbyte: ServerResp1 = $23 IF VarType2 = "5" THEN Rate IF VarType2 = "6" THEN Time IF VarType2 = "7" THEN Variable Variable 5 has been called to be set Rate: Choose which parameter associated with rate is to be set, using NN values IF SetVar2 = "0" THEN one IF SetVar2 = "1" THEN two IF SetVar2 = "2" THEN five IF SetVar2 = "3" THEN ten one: two: B20 = 1 B20 = 2

13 five: ten: B20 = 5 B20 = 10 Variable 6 has been called to be set Time: Once again, choose which parameter is to be set using NN values IF SetVar2 = "0" THEN tenseconds IF SetVar2 = "1" THEN thirtyseconds IF SetVar2 = "2" THEN fourtyfiveseconds IF SetVar2 = "3" THEN sixtyseconds tenseconds: B22 = 10 thirtyseconds: B22 = 25 fourtyfiveseconds: B22 = 45 sixtyseconds: B22 = 60 Variable 7 has been called to be set Variable: Choose parameter to be set IF SetVar2 = "0" THEN x IF SetVar2 = "1" THEN y Note that GUI protocol send ASCII representations of numbers, so the format of the numbers upon appearance in the GUI will depend on the formatters used (i.e. decimal format of the ASCII will return 88 and 89, where as a hex format will return 58 and 59) x: B21 = "X" y: B21 = "Y" setbyteresp: SEROUT 16,84,[ServerResp1, VarType1, VarType2, SetVar1, SetVar2]

14 '* Handler for a invoke function request '* Format of request string = 0x14xx, where xx = variable of function being requested '* Returns 0x24xx to client or 0x10 (and ACK) RPC: Invoke command simply calibrates the +1g and 1g values for both the X and the Y directions Only an ACK response is needed back ServerResp1 = $10 SEROUT 16,84,[ServerResp1] IF VarType2 = "8" THEN posx IF VarType2 = "9" THEN negx IF VarType2 = "A" THEN posy IF VarType2 = "B" THEN negy The user at this point would be prompted to position the accelerometer to read the positive X forces and a pulse on the X port pin here saves the value of +1g on the X axis posx: PULSIN 4,1,positiveX Data gathered for the 1g value on the X axis, then subroutine called to calculate the numerical difference between the +1g and 1g values for scaling purposes negx: PULSIN 4,1,negativeX GOSUB calc_deltax Now gather +1g value on Y axis posy: PULSIN 2,1,positiveY Gather 1g value on Y axis, then go to subroutine to calculate difference in +1g and 1g values for scaling reasons negy: PULSIN 2,1,negativeY GOSUB calc_deltay calc_deltax: deltax = positivex - negativex RETURN calc_deltay: deltay= positivey - negativey

15 '* Handler for a getword function request '* Format of request string = 0x15xx, where xx = variable being requested '* Returns 0x25xxPPNN, where PP = high byte of variable xx, and NN = low byte of variable xx getword: ServerResp1 = $25 IF VarType2 = "1" THEN YWORDvariable 'Pulse X port pin, read, and save out x acceleration values PULSIN 4,1,xWord 'calculate the scaled g-force value of xword 'xword = (20/deltaX)*(xWord - negativex) + 40 ServerResp2 = xword.highbyte ServerResp3 = xword.lowbyte 'server data sent out over RS232 to client SEROUT 16,84,[ServerResp1, VarType1, VarType2, HEX2 ServerResp2, HEX2 ServerResp3] YWORDvariable: PULSIN 2,1,yWord calculate the scaled g-force value of yword yword = (20/deltaY)*(yWord negativey) + 40 ServerResp2 = yword.highbyte ServerResp3 = yword.lowbyte SEROUT 16,84,[ServerResp1, VarType1, VarType2, HEX2 ServerResp2, HEX2 ServerResp3] END