Kilolib
Kilobot Library
|
Go to the source code of this file.
Functions | |
uint8_t | estimate_distance (const distance_measurement_t *d) |
Estimate distance in mm based on signal strength measurements. More... | |
void | delay (uint16_t ms) |
Pauses the program for the specified amount of time. More... | |
uint8_t | rand_hard () |
Hardware random number generator. More... | |
uint8_t | rand_soft () |
Software random number generator. More... | |
void | rand_seed (uint8_t seed) |
Seed software random number generator. More... | |
int16_t | get_ambientlight () |
Read the amount of ambient light. More... | |
int16_t | get_voltage () |
Read the amount of battery voltage. More... | |
int16_t | get_temperature () |
Read the temperature of the kilobot. More... | |
void | set_motors (uint8_t left, uint8_t right) |
Set the power of each motor. More... | |
void | spinup_motors () |
Turn motors at full-speed for 15ms. More... | |
void | set_color (uint8_t color) |
Set the output of the RGB led. More... | |
void | kilo_init () |
Initialize kilobot hardware. More... | |
void | kilo_start (void(*setup)(void), void(*loop)(void)) |
Start kilobot event loop. More... | |
uint16_t | message_crc (const message_t *msg) |
Function to compute the CRC of a message struct. More... | |
Data Structures | |
struct | message_t |
Message structure. More... | |
struct | distance_measurement_t |
Distance measurement. More... | |
Variables | |
volatile uint32_t | kilo_ticks |
Kilobot clock variable. More... | |
uint16_t | kilo_uid |
Kilobot unique identifier. More... | |
uint8_t | kilo_turn_left |
Calibrated turn left duty-cycle. More... | |
uint8_t | kilo_turn_right |
Calibrated turn right duty-cycle. More... | |
uint8_t | kilo_straight_left |
Calibrated straight (left motor) duty-cycle. More... | |
uint8_t | kilo_straight_right |
Calibrated straight (right motor) duty-cycle. More... | |
message_rx_t | kilo_message_rx |
Callback for message receiption. More... | |
message_tx_t | kilo_message_tx |
Callback for message transmission. More... | |
message_tx_success_t | kilo_message_tx_success |
Callback for successful message transmission. More... | |
void delay | ( | uint16_t | ms | ) |
Pauses the program for the specified amount of time.
This function receives as an argument a positive 16-bit integer ms
that represents the number of milliseconds for which to pause the program.
ms | Number of milliseconds to pause the program (there are 1000 milliseconds in a second). |
uint8_t estimate_distance | ( | const distance_measurement_t * | d | ) |
Estimate distance in mm based on signal strength measurements.
This function receives as an argument the signal strength measurements d
taken during message reception, and returns a positive integer that respresents the distance estimate in mm towards the robot that originated the message.
d | Signal strength measurement for a message. |
int16_t get_ambientlight | ( | ) |
Read the amount of ambient light.
This function returns a 10-bit measurement (0 to 1023) that represents the amount of ambient light detected by the photo diode available in the kilobot. When the analog-to-digital converter is unavailable and the voltage cannot be measured, this function will return -1.
int16_t get_temperature | ( | ) |
Read the temperature of the kilobot.
This function returns a 10-bit measurement (0 to 1023) that represents the temperature of the board of the kilobot. This sensor is only capable of detecting large temperature changes (in the order of 2 Celsius degrees or more). When the analog-to-digital converter is unavailable and the voltage cannot be measured, this function will return -1.
As such, it is only useful only to detect drastic changes in the operating environment of the kilobot.
int16_t get_voltage | ( | ) |
Read the amount of battery voltage.
This function returns a 10-bit measurement (0 to 1023) that represents the amount of voltage that remains in the battery. It can be used to determine if the kilobot should be recharged. When the analog-to-digital converter is unavailable and the voltage cannot be measured, this function will return -1.
void kilo_init | ( | ) |
Initialize kilobot hardware.
This function initializes all hardware of the kilobots. This includes calibrating the hardware oscillator, setting hardware timers, configuring ports, setting up analog-to-digital converters, registering system interrupts and the initializing the messaging subsystem.
It is recommended that you call this function as early as possible inside the main
function of your program.
void kilo_start | ( | void(*)(void) | setup, |
void(*)(void) | loop | ||
) |
Start kilobot event loop.
This function receives two parameters. The first parameter setup
is a function which will be called once to perform any initialization required by your user program. The second parameter loop
is a function that will be called repeatedly to perform any computations required by your user program.
Using the overhead controller it is possible to interrupt the event loop to trigger events such as program start/resume, program pause, and program restart.
setup | put your setup code here, to be run only once |
loop | put your main code here, will be run repeatedly |
uint16_t message_crc | ( | const message_t * | msg | ) |
Function to compute the CRC of a message struct.
This function receives as input a pointer to a message structure msg
, and uses the message data and type to compute and return a uint16_t
CRC value.
msg | Pointer to an input message. |
uint8_t rand_hard | ( | ) |
Hardware random number generator.
This function uses the analog-to-digital converter to generate an 8-bit random number. Specifically, the robot measures its own battery voltage and extracts randomness from the least significant bit by using Von Neumann's fair-coin algorithm. By its nature, this function is slow, use rand_soft() if you want a faster alternative, and you can seed the software random generator using the output of rand_hard().
void rand_seed | ( | uint8_t | seed | ) |
Seed software random number generator.
This function changes the seed used by the software random number generator implemented by rand_soft().
8-bit | random seed. |
uint8_t rand_soft | ( | ) |
Software random number generator.
This function implements a linear-shift-register to implement an 8-bit pseudo-random number generator. The seed of the random number generator can be controlled through rand_seed().
void set_color | ( | uint8_t | color | ) |
Set the output of the RGB led.
This function receives an 8-bit unsigned integer whose bits are used to determine the output of the RGB led mounted on the kilobot. Each color has a 2-bit resolution which allows set each color channel independently from off (0) to full-brightness (3).
The convenience macro RGB
can be used to set the individual bits. For instance RGB(0,0,0)
turns all color channels off, and therefore the RGB led remains off. Meanwhile RGB(0,3,0)
turns the green channel to full intensity and turns all other channels off, which results in an RGB led displaying a bright green color.
color | Output of the led. The recommended usage is through the RGB macro. |
void set_motors | ( | uint8_t | left, |
uint8_t | right | ||
) |
Set the power of each motor.
The power received by the left and right motor is controlled using hardware pulse-width-modulation (PWM) and can be set using this function.
The parameter left
and right
are 8-bit unsigned integers (0 to 255) that control the duty-cycle of the PWM signal from 0% to 100%. In other words, setting a motor to 0% duty-cycle equates to running off the motor, and setting a motor to 100% duty-cycle equates to running the motor at full power. For the most part, motors should only be set to the calibrated values kilo_turn_left
, kilo_turn_right
, kilo_straight_left
and kilo_straight_right
.
When a motor transitions from being off (0% duty cycle) to being on (> 10% duty cycle) it must first be turned on at full-speed for 15ms to overcome the effects of static friction.
left | 8-bit integer to control left motor duty-cycle. |
right | 8-bit integer to control right motor duty-cycle. |
void spinup_motors | ( | ) |
Turn motors at full-speed for 15ms.
When the robot transitions from being stationary (motors off) to being mobile (one or both motors on) it must overcome the effects of static friction. For that purpose, the motors can be turned-pn at full-speed during 15ms. This function does precisely that, and is equivalent to the following code:
spinup
of a motor. See set_motors() for an example.message_rx_t kilo_message_rx |
Callback for message receiption.
This callback is triggered every time a message is succesfully decoded. The callback receives two parameters, a pointer to the message decoded, and a pointer to the distance measurements from the message originator.
message_tx_t kilo_message_tx |
Callback for message transmission.
This callback is triggered every time a message is scheduled for transmission (roughly twice every second). This callback returns a pointer to the message that should be sent; if the pointer is null, the no message is sent.
message_tx_success_t kilo_message_tx_success |
Callback for successful message transmission.
This callback is triggered every time a message is sent successfully. It receives no parameters and returns no values.
uint8_t kilo_straight_left |
Calibrated straight (left motor) duty-cycle.
This variable holds an 8-bit positive integer which is the calibrated duty-cycle used for the left motor to go straight. This must be used in conjuction with kilo_straight_right.
uint8_t kilo_straight_right |
Calibrated straight (right motor) duty-cycle.
This variable holds an 8-bit positive integer which is the calibrated duty-cycle used for the right motor to go straight. This must be used in conjuction with kilo_straight_left.
volatile uint32_t kilo_ticks |
Kilobot clock variable.
This variable holds a 32-bit unsigned positive integer. This variable is initialized to zero whenever the program run at the kilobot is reset (or when the kilobot is first turned on). It is incremented approximately 32 times per second, or once every 30ms.
uint8_t kilo_turn_left |
Calibrated turn left duty-cycle.
This variable holds an 8-bit positive integer which is the calibrated duty-cycle for turning left.
uint8_t kilo_turn_right |
Calibrated turn right duty-cycle.
This variable holds an 8-bit positive integer which is the calibrated duty-cycle for turning right.
uint16_t kilo_uid |
Kilobot unique identifier.
This variable holds a 16-bit positive integer which is designated as the kilobot's unique identifier during calibration.