Doc Bot

File format

When a bot's blueprint and source code are compiled, the resulting data is stored in a file with the DocBot File format. This file format is either a text file or a binary file, with each line containing hexadecimal values encoding a sequence of data and their starting offset or absolute address, and the bot's hardware device configuration.

The file can either be an HEX plain text hexadecimal file or a BIN binary file. The only difference between them lies in how the actual data part of each line is stored. In an HEX file the data is stored as plain text, with the data translated into its hexadecimal values. In a BIN binary file the data is stored raw as its binary representation. The favored format is the BIN binary file format, and that is the default format used by the compiler. Both file formats have the extension .dbf, with the header letting the loader know what format variant the file is encoded as.

A DocBot File starts with a header in plain text detailing the format of the file. This header also includes the format version information for future scalability, which is always 1.0. The contents of the header is either DocBot BIN Bot File v1.0 or DocBot HEX Bot File v1.0, depending on whether the file is encoded as BIN (binary) or HEX (hexadecimal plain text). In both cases the file is split in lines, with each line having the same format, closely resembling the classic Intel HEX file format.

Each line of a DocBot file consists of six parts:

1. Start code, one plain text character, an ASCII colon ':'.
2. Byte count, two plain text hex digits, a number of bytes (hex digit pairs for HEX format, binary bytes for BIN format) in the data field. 16 (0x10) or 32 (0x20) bytes of data are the usual compromise values between line length and address overhead.
3. Address, four plain text hex digits, a 16-bit address of the beginning of the memory position for the data. Limited to 64 kilobytes. This address is big endian.
4. Record type, two plain text hex digits, 00 to 07, defining the type of the data field.
5. Data, a sequence of n bytes of the data themselves. 2n plain text hex digits (for HEX format) or n binary hex values (for BIN format).
6. Checksum, two plain text hex digits - the least significant byte of the two's complement sum of the values of all fields except fields 1 and 6 (start code ':' byte and two hex digits of the checksum). It is calculated by adding together the hex-encoded bytes (hex digit pairs for HEX format or raw binary bytes for BIN format), then leaving only the least significant byte of the result, and making a two's complement (either by subtracting the byte from 0x100, or inverting it by XOR-ing with 0xFF and adding 0x01). The overflow is supressed by AND-ing the result with 0xFF. The overflow may occur since both 0x100-0 and (0x00 XOR 0xFF)+1 equal 0x100. If the checksum is correctly calculated, adding all the bytes (the byte count, both bytes in address, the record type, each data byte and the checksum) together will always result in a value wherein the least significant byte is zero (0x00).

For example, the checksum on :0300300002337A1E is calculated as follows:
03 + 00 + 30 + 00 + 02 + 33 + 7A = E2 (two's complement is 1E)

There are four record types:

• 00, Data record, contains data and 16-bit address. The format described above.
• 01, End Of File record, a file termination record. No data. Has to be the last line of the file, only one per file permitted. Usually :00000001FF.
• 02-05, Unusued.
• 06, Hardware Device record, a list of hardware devices built into the bot, including the chassis and microcontroller. The address field points to the hardware mount point of the first device to be loaded from this line, and the data is a list of devices' serial numbers.
• 07, Port Connection record, a list of port connections detailing how each hardware device is connected to the microcontroller's external ports. The address field points to the external port of the first connection, and the data is a list of the mount points connected to each external port. Usually only one line for all connections, unless hardware devices are not sequentially connected.

Beware! The endianness (byte order) of the byte pairs for the data part of each record is big endian for the HEX variant, meaning that the value 0xD280 is stored as D280. In the BIN variant, on the other hand, endianness is little endian, meaning that 0xD280 is actually stored as the raw byte value 80 followed by the raw byte value D2.

Example

(example is in plain text HEX format for easier human reading)

DocBot HEX Bot File v1.0
:0200000601A113E261
:0400100666D666D666D666D6F6
:0200300613E711F1CC
:0400500631F280D3F1A1F1A10C
:0100700666E340
:070000070030005000510052005300700031DB
:08000000244500010002D28000AF34120004000C35
:110100007632000300027627000C00872416007F0088C3600089C32001352411000C0035320063
:00000001FF


    Header
    Start code
    Byte count
    Address
    Record type
    Data
    Checksum

Dissection of two records (lines) from this example will further clarify the file format.

The second line in the .dbf file is :0200000601A113E261. The record type here is 06, meaning it is a hardware device record detailing what kind of hardware is mounted on the bot. The address is 0000, so we start loading the devices from the first mount point (mount point 0), which is the special chassis mount point. The byte count is 02, so two hardware devices will be loaded, each one taking up four plain text hexadecimal digits on the data part of the line. The first hardware device is 01A1 (a Flexo chassis by Kellestar Inc.), and it is mounted on mount point 0x0000 (the special mount point for the chassis). The second hardware device on this record is 13E2 (a CP13E2 Microcontroller by Netter Handicrafts Ltd.), and it is mounted on the next mount point (0x0001), which is the special mount point for the microcontroller. The checksum is 61, which is the sum of 02 + 00 + 00 + 06 + 01 + A1 + 13 + E2 = 19F, then calculating the two's complement of the least significant byte (9F), which is 100 - 9F = 61.

The seventh line in the file is :070000070030005000510052005300700031DB. The record type here is 07, meaning it is a port connection record detailing what mount points are connected to which microcontroller external ports. The address is 0000, so we start connecting the mount points from the first microcontroller's external port (external port 0). The byte count is 07, so there will be seven connections to external ports, each one to a sequential external port starting at external port 0 (the address). Each connection will take up four plain text hexadecimal digits on the data part of the line, which will tell us which mount point will be connected to the corresponding external port. The first mount point to connect is 0030 (internal mount point 0), which is connected to external port 0. The second mount point is 0050 (external mount point 0), which is connected to the next external port, that is, external port 1. Mount point 0051 (external mount point 1) is then connected to external port 2, and so on. Finally, the checksum is DB, which is the sum of 07 + 00 + 00 + 07 + 00 + 30 + 00 + 50 + 00 + 51 + 00 + 52 + 00 + 53 + 00 + 70 + 00 + 31 = 225, then calculating the two's complement of the least significant byte (25), which is 100 - 25 = DB.