Software¶

This page describes the packets and software used for tooltron. We will cover both the board firmware and the server software. For the most up to date documentation and how the code works, refer to the Doxygen documentation or the comments within the code.

Error Codes¶

fast red blinking on toolbox power-up means eeprom ID cannot be read

Configuring tools¶

To set up a toolbox (or change timeouts) the code must be modified. Open toolbox/main.c and look at the #define config options near the top of the file. You must recompile the code and reprogram the board that you wish to configure for the changes to take effect.

tool ID¶

Open up main.c. Set ADDR to be the numeric ID of the tool. This cannot be 1 or 0 and does not need to be the same as the keypad which is pressed. The key which corresponds to a tool can be changed separately (see server config below). The tool ID must be an integer value.

Timeouts¶

There are three timeouts that can be configured. They are TWAIT, TWARN, and TMAX. They are all located in main.c. All units for the timeouts are in minutes.

TWAIT defines the amount of time to wait from when a tool turn on command has been sent from the server until the tool will return back to the idle state. This is the window of time that the user can turn power onto the tool and transition it to the ON state.

TWARN defines the amount of time from when the tool enters the ON state until it begins warning the user that their time is about to expire. It is during this time that the time can be extended by the user.

TMAX defines the amount of time from when the tool enters the WARN state until it turns off the tool due to time expiration (unless the tool is running, in which case power will not be shut off until the current draw is removed).

Packet Format¶

We send a simple packet as follows:

Start Delimitor

SRC

DEST

CMD

Check Sum

The start Delimitor is always '^'

SRC and DEST can be any number from 0-255. Here are the reserved values:

Address	User
0	Global
1	Server

Tool IDs start at 11.

Valid commands are:

Character	Meaning
a	Ack
n	Nack
o	On
t	Timeout
k	Get Key
r	Reset
b	Boot
p	Program Mode
d	Program Data

Checksums are the XOR of all the bytes excluding the start delimitor.

Cardbox Firmware¶

The cardbox contains the keypad and is connected to the server. To board will receive a Get Key request from the server. The board then illuminates the yellow light and waits for the user to press a button on the keypad. Should the user not press a key within the timeout time, a Timeout packet is returned to the server and the red light is shown. Otherwise, the last key pressed is sent to the server. The cardbox will then waits again. If an Ack is received, the green light is displayed indicating that the user has the permissions required to run the tool. Should the server return a Nack, the cardbox displays the red light indicating that the user does not have the correct permissions.

Toolbox Firmware¶

The toolbox interfaces the server to the tool. It simply sits in a loop waiting for data to come in. Should the address of the packet match, the tool will parse the packet. Otherwise it will be discareded. Once the packet is parsed, the toolboard checks for a On command. Should that be valid, the toolboard initiates the timers and waits for button presses. At this time the yellow light is on. If a red button is pressed the timer is disabled and the toolboard returns to waiting for packets. A red light is displayed briefly indicating ot the user that the tool is disabled. If the green button is pressed, the toolboard turns on the relay, giving power to the tool. The green light is now illuminated and the yellow light turned off.

While the tool is running the toolboard monitors the ac line. Should it detect that the tool is running, it will not turn off power to the tool for safety reasons. The timers will count down on the tool after the green button is pressed. Should the timer expire, the yellow light will blink, indicating to the user that the tool will turn off as soon as the tool is powered down. A green button will increase the time on the timer. If the tool is turned off while the timer still has power, it can be turned on again though the timer will not be refreshed. Finally, the timer cannot be extended unless the yellow light is blinking. Should the time expire and the user turn off the tool, the user must return to the cardbox and re-request the tool.

Note in the firmware that the buttons are labelled black and red. The green button is also the black button. This is a holdover from the original tooltron system that used black buttons.

Server Software¶

The server software sits in a loop waiting for input from the USB card reader. When a card is swiped, the server software parses out the Carnegie Mellon card ID number and stores that. It then sends the Get Key command to the cardbox. Once the key is received, the server queries the members database, passing in the card number and the requested tool number. Should the cardbox not return a tool, the request is discarded. If the user is allowed on the tool, the server sends an Ack to both the cardbox and to the toolboard to turn it on. If the user is not allowed the server sends a Nack to the cardbox.

Note that the server is not setup to handle concurrent requests. Users should only swipe one at a time.

State Transition Diagram¶

This is a diagram of the three state machines between the cardbox, server, and card reader.

CiviCRM¶

We simply read the civicrm database through mysql and parse the information needed. We use custom fields to store each users tool permissions which are queried.

The database is whitelisted. To grant access:

1. ssh in to roboclub8
2. run 'mysql -u tooltron -p'
3. enter the password (t..., the old one)
4. At the mysql prompt type: GRANT ALL ON civicrm.* TO tooltron@'_ip_' IDENTIFIED BY '_t..._';

Where ip is the ip of the system you want to add and t... is the t password

Network Bootloading¶

1. Server sends a reset packet to a specific tool
2. Tool reboots
3. Tool sends a boot packet to the server
4. Server responds with the program packet to tell the tool to prepare to receive a program, packet also contains number of bytes that the program will be
5. Tool acks packet to the server
6. Sever sends MAX_PACKET_SIZE in Data Packets
7. Tool writes each packet to flash after checksum verification, acks packet
8. Repeat until upto the final program size
9. Tool jumps to new code and begins execution

If there is ever an interruption of the stream, both the Tool and the Server must reset. The tool discard and program data received. The server should resend to the program, the tool shall attempt to be reprogrammed until successfully reprogrammed.