RCodePlus Array features

This page describes the array extensions provided in RCodePlus.

These AP_ extensions provide simple arrays.

Array rules:

You can have up to 20 arrays, numbered from 1 to 20.

Numbers 21 to 25 are special and reserved for telemetry.

Before using an array, you must dimension it with AP_DIM (set its size).

Arrays are zero based, single dimension arrays of 16 bit numbers.

The maximum size is 32767 elements.

All array operations have error checking. If you pass invalid arguments, or index beyond the array bounds an error will be trapped.

Argument and indexing errors will stop the RCODE interpreter, print an error message on the LAN console and log it to the ERROR.LOG file.

There are special features for automatic or manual saving and loading of arrays

There are advanced features for using arrays as data structures for advanced mucking of AIBO's internals

Array syntax summary

All 'size's, 'offset's, 'index's and 'count's are in terms of 16-bit values.

    // creating, dimensioning
    AP_DIM array size [1]
    AP_NEWARRAY array_var size
    AP_FREEARRAY array_var

    // old style access
    AP_GET var array offset [index2] // var = array[offset+index2]
    AP_SET val array offset [index2] // array[offset+index2] = val

    // move and find
	AP_BMOVE array read_index write_index count
	AP_SCANFIND var array start_index scan_count find_value
	AP_SCANCOUNT var array start_index scan_count find_value

    // using arrays as structures

    AP_SETW array offset val1 [val2 [val3 [val4]]]
    AP_GETW array offset var1 [var2 [var3 [var4]]]
    AP_SETB array offset val1 [val2 [val3 [val4]]]
    AP_GETB array offset var1 [var2 [var3 [var4]]]
	AP_SETDBL array offset intval fractval_times_10000

    AP_PEEK array offset peekpoke_type dindex
    AP_POKE array offset peekpoke_type dindex

	AP_SAVEARRAY array "filename" [format_value]
	AP_LOADARRAY array "filename_format" [format_value [actual_size_var]]

    // special case for telemetry
    AP_SETVARADDR array var_offset var1 [var2 [var3 [var4]]]

    // special case for synvoice
    AP_GETSYNVOICE array actual_size_var vcmd_number
    AP_SETARRAYASRAM array offset actual_size

NOTE: all 'offset's are word offsets (2 bytes per element). 'var_offset' is for variable pointers (4 bytes per element).

Array basics: AP_DIM, AP_SET, AP_GET

AP_DIM - create/dimension an array

Assign each array a number (from 0 to 19). Call "AP_DIM" and specify the size of the array. New arrays are filled with zeros. You can call "AP_DIM" again to resize and zero out the array.

    SET my_array 1  // convenient name for the array
    AP_DIM my_array 1000        // 1000 elements (indexed 0 .. 999)

AP_GET, AP_SET - accessing elements

Use AP_SET and AP_GET to set and get individual elements of an array. Invalid calls (missing args) or trying to access an element out of bounds will cause the statement to be ignored (no error report right now).

    AP_GET var array offset [index2] // var = array[offset+index2]
    AP_SET val array offset [index2] // array[offset+index2] = val

        // 'index2' is optional

  Examples:
    AP_SET 55 my_array 10           // my_array[10] = value
    AP_GET local1 my_array 10       // local1 = my_array[10]

AP_DIM - auto-save arrays

AP_DIM can be used to specify an "auto-save" array. You specify "1" as the auto-save flag after the size.

    SET saved_array 2  // convenient name for the array
    AP_DIM saved_array 100 1

Normally AP_DIM will zero fill the initial elements of the array. Auto-save arrays will load their data from the memory stick, if there is any. The current data will be saved to memory stick when AIBO's chest light is pressed.

Block Move

AP_BMOVE

This is a block move of data within an array.

	
	AP_BMOVE array, read_index, write_index, count

	PSEUDO CODE:
	if (read_index > write_index)
	{
		// typically for deleting an element
		for (int di = 0; di < count; di++)
			array[write_index + di] = array[read_index + di]
	}
	else
	{
		// typically for inserting an element
		for (int di = count-1; di >= 0; di--)
			array[write_index + di] = array[read_index + di]
	}

Fast Search

AP_SCANFIND

Find the first occurance of a value in an array range (or -1 if not found)

	AP_SCANFIND var, array, start_index, scan_count, find_value

	PSEUDO CODE:
	var = -1;
	for (int i = start_index; i < start_index + scan_count; i++)
		if (array[i] == find_value)
			{ var = i; break }

AP_SCANCOUNT

Count up the occurances of a value in an array range

	AP_SCANCOUNT var, array, start_index, scan_count, find_value

	PSEUDO CODE:
	var = 0;
	for (int i = start_index; i < start_index + scan_count; i++)
		if (array[i] == find_value)
			var++

Arrays in place of structures

TO BE DOCUMENTED

// Example: C data structure looks something like this
    
    struct MY_STRUCT
    {
		WORD field_w1;       // 2 bytes - offset = 0
        WORD field_w2;       // 2 bytes - offset = 1
        BYTE field_b1;       // 1 byte - offset = 2
        BYTE field_b2;       // 1 byte
        BYTE pad[2];         // 2*1=2 bytes - offset = 3
        double field_d[2];   // 2*8=16 bytes - offset = 4, 8
    }; // total of 24 bytes = 12 WORDs


    // MY_STRUCT myst = { 0, 0, 0, ..., 0 };
    SET myst 15     // some available array number
    AP_DIM myst 12
		// NOTE: array size (in bytes) is size of AP_DIM times two.

    // myst.field_w1 = 10
    // myst.field_w2 = 20
    AP_SETW myst 0 10
    AP_SETW myst 1 20       // byte offset = 2
    AP_SETW myst 0 = 10

    // myst.field_b1 = 30; myst.field_b2 = 40
    AP_SETB myst 2 30 40       // byte offset = 4,5 [set bytes together]

    // myst.field_d[1] = 2.5
	AP_SETDBL myst 8 2 5000
		// NOTE: AP_SETDBL use 8 byte doubles, and word indexes

    // notice all "AP_SET*" variants are slightly different be careful!


AP_SETDBL

	AP_SETDBL array offset intval fractval_times_10000

    // array is an array of 16 bit words
    // doubles are 8 bytes (4 words)
    // array[offset,offset+3] = (double) intval + fractval_times_10000 / 10000;

AP_SETW, AP_GETW
AP_SETB, AP_GETB
Set or get up to 4 values in one line.
Arrays are treated as word arrays for figuring out 'offset's (even when accessing bytes).

    AP_SETW array offset val1 [val2 [val3 [val4]]]
    AP_GETW array offset var1 [var2 [var3 [var4]]]
    AP_SETB array offset val1 [val2 [val3 [val4]]]
    AP_GETB array offset var1 [var2 [var3 [var4]]]



AP_PEEK, AP_POKE

    // new 2.51 format
    AP_PEEK array offset peekpoke_type dindex
    AP_POKE array offset peekpoke_type dindex

    array_offset is a word offset

	peekpoke_type:
    1 : Locomotion Parameters, dindex = 0 to 44, array size = 392 bytes
            [PEEK, or POKE if you are careful]
    2 : Walk Parameters, dindex = 0 to 11, array size = 256 bytes
            [PEEK, or POKE if you are careful]

    [others TBD]
    NOTE: only supported on the 2x0 AIBOs at the current time

    Support structures:
    LOCOPARAM
        email me for info

    WALKPARAM
        email me for info



AP_SAVEARRAY, AP_LOADARRAY

	AP_SAVEARRAY array "filename"
	AP_SAVEARRAY array "filename_format" format_value
	AP_LOADARRAY array "filename"
	AP_LOADARRAY array "filename_format" format_value [actual_size_var]

    NOTE: "filename_format" should only include one sprintf() format
        for an integer (eg: "%d", "%04d" or "%x").
    NOTE: "filename" or "filename_format" must start with "/MS/"




Array data telemetry (2.51)
You can use arrays to transfer data quickly across the LAN.
See the sample code in the new AiboRemote.

Notes

You can send the array commands via the LAN telnet socket to initialize the array.
Use array numbers 21 to 25 for arrays created on the PC.
There are two kinds of arrays, raw and variables.
Raw arrays are typically filled in by your RCODE program. The PC program can send a telemetry request to get the current array data.
Variable arrays require a little setup, but after that don't require any running RCODE to operate.
You place the variable addresses in the array using AP_SETVARADDR.
When the PC sends a telemetry request to get the data, AIBO will build a reply based on the current values of those variables.
Only use global variables with AP_SETVARADDR. System variables (like "Pink_Ball") can be used as well.