kMatlab -- Matlab commands for Kameleon K376SBC =============================================== by Yves Piguet, 8/1998 Skye Legon, 2/1999 Copyright (c) 1998/99, K-Team SA kMatlab is a set of Matlab routines that permit the user to interact with Kameleon over a serial connection. It includes Windows DLLs to perform the system-level serial-port communication, and a library of useful Matlab .m files to read analog inputs, set LEDs, etc. NOTE: these have been tested for Matlab 5.3, compatibility with earlier versions of Matlab is not guaranteed. ============================================================================== Install (for Win95/98/NT, but similar process for Mac) ------------------------------------------------------ Extract all "kMatlab" files to a directory on your hard disk. Run Matlab. To use the commands, you can simply change the local directory to your kMatlab directory (e.g. ª cd d:\path\to\kMatlab). To avoid performing this step every time you load Matlab (or to run the kMatlab commands from another directory) you can add the kMatlab directory to the Matlab path. From the Matlab menu, choose File, Set Path, and enter (or Browse for) your kMatlab directory. Choose "Add to Path". Make sure the Kameleon is connected to your computer and powered on. You are now ready to use the commands! ============================================================================== Usage ----- You must first OPEN the serial port using the KOPEN command, which is of the form: ª port_reference = kopen([ com_port, baud_rate, timeout]) e.g. use first serial device (COM1), at 19200 baud, with 1 second timeout: ª ref = kopen([0,19200,1]) or for COM2 at 38400 baud: ª ref = kopen([1,38400,1]) If you receive the response: ??? Undefined function or variable 'kopen'. then you are not in the correct directory, or you have not set up your path correctly. Note that 0=COM1, 1=COM2! Also, do not forget to assign kopen's return value to some variable; it is required for all subsequent commands. We will use 'ref' as our return variable for the following examples. When you are done you must CLOSE the serial port: ª kclose(ref) Sending commands ---------------- To send a command that returns a SINGLE line response: ª return_value = kcmd( port_reference, 'khepera_command') To send a command that returns a MULTIPLE line response, you add a '1': ª return_value = kcmd( port_reference, 'khepera_command', 1) Notes: The single-line command returns everything it receives from the Kameleon until it receives a newline character. The multi-line command, however, doesn't know how long your multi-line response it, and so it waits for 'timeout' seconds, and then returns everything in the buffer. The choice of timeout is therefore important. Too small, and multi-line responses will be truncated; too long, and the command will take a long time to return. One second (timeout = 1) is recommended, and corresponds to 48 lines of 80-column text at 38400 baud. The use of the return value is optional. Use the 'port_reference' that was returned by kopen. Examples: To return the system bios version (single-line): ª kcmd(ref,'B') ans = b,1.00,1.00 To list currently running processes (multi-line): ª kcmd(ref,'process',1) ans = Process N. 00000000 IDLE process for the micro-kernel, EF-99: Rev. 1.00 Process N. 00000001 Start-up process of the K376SBC board, EF-99: Rev. 1.00 Process N. 00000002 ALIVE process: everything is OK, EF-99: Rev. 1.00 ============================================================================== kMatlab Command Library ----------------------- Although kopen, kcmd, and kclose are all you need to fully control Kameleon from Matlab, for convenience we have also provided a library of useful matlab commands. They are described briefly below, but for more information please read the .m files. For explanation of the actual Kameleon commands sent by these Matlab routines, please consult Appendix A of the Kameleon User Manual. These commands are provided as a starting point. You are encouraged to modify and/or create your own new functions to suit your application. The commands are not case sensitive. They are written in mixed-case for clarity, but for example kGetAnalog and kgetanalog are equivalent. If an error is detected, most of the functions will return -1 as an error code. The equivalents for all of the Kameleon commands listed in Appendix A of the Kameleon User Manual are listed at the end of this document. Demo: ------ kVoltageG(ref) - Graphical display of Kameleon supply voltage System Commands: ---------------- kopen([port, baud_rate, timeout]) - opens serial port, supports baud rates up to 115200 bps. kcmd(ref, text_string) - sends a command to Kameleon for a SINGLE-LINE response kcmd(ref, text_string, 1) - sends a command to Kameleon for a MULTI-LINE response kclose(ref) - closes the serial port kFlush(ref) - empties the buffer. This is useful if you issue a multi-line command but forget the '1' parameter. (see sample session below) A "command not found" message will be returned by Kameleon--ignore this. Information Commands: --------------------- kBios(ref) - kBios(ref); displays the bios and protocol versions - [a,b] = kBios(ref); does not display, but assigns the values to a and b kList(ref) - lists available ROM modules kTeam(ref) - lists the K-Team Miscellaneous Commands: ----------------------- kGetAnalog(ref, channel) - read an analog input channel via the 10-bit A/D converter kLED(ref, n, action) - set the two LEDs. 'n' and/or 'action' can be vectors, e.g. kLED(ref, [0 1], [2 0]) will toggle LED0, and turn off LED1. kReadByte(ref, address) - reads a byte from the extension bus kWriteByte(ref, address) - writes a byte to the extension bus kTurret(ref, turretID, textString) - sends a text string command to an extension turret kTurretBios(ref, turretID) - provided as an example of possible turret commands, this displays the bios version of an extension turret ============================================================================== kMatlab equivalents to Kameleon commands (as listed in Appendix A of the User Manual) Kameleon Command kMatlab equivalent ------------------------------------------------------------------------ B - Read software version kBios I - Read A/D input kGetAnalog L - Change LED state kLED T - Send a message to an extension turret kTurret R - Read a byte on the extension bus kReadByte W - Write a byte on the extension bus kWriteByte ============================================================================== Sample session (has been edited for clarity): --------------------------------------------- % open COM1 at 38400 baud, 1 second timeout ª ref = kopen([0, 38400, 1]); ª kBios(ref); Kameleon K376SBC BIOS version: 1.00 Kameleon K376SBC protocol version: 1.00 % read the power supply voltage (in 20mV units) and convert to volts % note your results may vary depending on the power supply used ª kGetAnalog(ref,15) / 50 ans = 8.8000 % try a multi-line command using the '1' parameter ª kcmd(ref,'process',1) ans = Process N. 00000000 IDLE process for the micro-kernel, EF-99: Rev. 1.00 Process N. 00000001 Start-up process of the K376SBC board, EF-99: Rev. 1.00 Process N. 00000002 ALIVE process: everything is OK, EF-99: Rev. 1.00 % but if we forget the '1', we only receive the first line of the buffer ª kcmd(ref,'process') ans = Process N. 00000000 IDLE process for the micro-kernel, EF-99: Rev. 1.00 % subsequent commands will receive incorrect responses stored in the buffer % Here we ask for the system bios, but receive part of the previous response ª kcmd(ref,'B') ans = Process N. 00000001 Start-up process of the K376SBC board, EF-99: Rev. 1.00 % flushing the buffer will let us continue normally (ignore the % "Command not found" message) ª kFlush(ref) Buffer contents: Process N. 00000002 ALIVE process: everything is OK, EF-99: Rev. 1.00 b,1.00,1.00 Command not found % we can now continue... ª kcmd(ref,'B') ans = b,1.00,1.00 % when we are finished, we can close the connection ª kclose(ref)