Droplet API

!!! OUT OF DATE !!!

See droplet_code/docs/DropletAPI.h for more up-to-date API information

System Initialization and Status

Function Name	Hardware	Simulator	Returns	Args	Notes & Description
init_all_systems	Yes	Yes	void	void	Initializes/resets all of the Droplet's subsystems.
reset_rgb_led	No	Yes	void	void	Resets the rgb led.
reset_rgb_sensor	No	Yes	void	void	Resets the rgb sensor
reset_ir_sensor	No	Yes	void	uint8_t sensor_num	sensor_num - The sensor number to reset (0 to 5).
reset_motors	No	Yes	void	void	Resets the Droplet's motor subsystem.
reset_timers	No	Yes	void	void	(Should be Deprecated) Resets all the droplet timers in the simulator. Would like to replace timers in sim with callback functions.
leg1_status	Yes	Yes	int8_t	void	(Replace with leg_status(uint8_t leg)). Returns 0 if floating, +1 if powered, -1 if grounded.
leg2_status	Yes	Yes	int8_t	void	(Replace with leg_status(uint8_t leg)). Returns 0 if floating, +1 if powered, -1 if grounded.
leg3_status	Yes	Yes	int8_t	void	(Replace with leg_status(uint8_t leg)). Returns 0 if floating, +1 if powered, -1 if grounded.
cap_status	Yes	No	int8_t	void	Returns 0 if capacitor is with normal range (2.8v - 5v), +1 if cap is too high, -1 if cap is too low.
droplet_reboot	Yes	No	void	void	Resets the droplet.

Motion Subsystem

Function Name	Hardware	Simulator	Returns	Args	Notes & Description
move_steps	Yes	Yes	(sim) void, (hw) uint8_t	uint8_t direction, uint16_t num_steps	direction - Between 1 and 6 (or macros NORTH, SOUTH, etc.). In hardware, returns 1 on success and 0 on failure.
move_duration	Yes	Yes	(sim) void, (hw) uint8_t	uint8_t direction, uint16_t duration	direction - Between 1 and 6 (or macros NORTH, SOUTH, etc.). duration - In ms. In hardware, returns 1 on success and 0 on failure.
is_moving	Yes	Yes	uint8_t	void	Returns 1 if Droplet is currently moving, 0 o/w.
cancel_move	Yes	Yes	uint16_t	void	Ceases linear motion if Droplet is currently moving. Returns the number of steps taken since last move_steps or move_duration was called.
rotate_steps	Yes	Yes	(sim) void, (hw) uint8_t	uint8_t direction, uint16_t num_steps	direction - 1 for clockwise, 2 for counter-clockwise, or use macros. num_steps - the number of rotation steps to take.
rotate_duration	Yes	Yes	(sim) void, (hw) uint8_t	uint8_t direction, uint16_t duration	direction - 1 for clockwise, 2 for counter-clockwise, or use macros. duration - In ms. Rate is about 26ms per degree of rotation.
rotate_degrees	No	Yes	void	uint8_t direction, int16_t degrees	direction - 1 for clockwise, 2 for counter-clockwise, or use macros. degrees - In degrees (-180 to +180 recommended). Rate is about 26ms per degree of rotation.
is_rotating	Yes	Yes	uint8_t	void	Returns 1 if Droplets is currently rotating, 0 o/w
cancel_rotate	Yes	Yes	uint16_t	void	Returns the number of steps taken since last rotate_steps, rotate_duration or rotate_degrees was called.

RGB LED Subsystem

Function Name	Hardware	Simulator	Returns	Args	Notes & Description
set_rgb_led	Yes	Yes	void	uint8_t r, uint8_t g, uint8_t b	Sets rgb led color saturation (0 to 255 for each color).
set_red_led	Yes	Yes	void	uint8_t r	Sets rgb led red color saturation (0 to 255).
set_green_led	Yes	Yes	void	uint8_t g	Sets rgb led green color saturation (0 to 255).
set_blue_led	Yes	Yes	void	uint8_t b	Sets rgb led blue color saturation (0 to 255).
get_red_led	Yes	No	uint8_t	void	Returns the current red color saturation value for the rgb led.
get_green_led	Yes	No	uint8_t	void	Returns the current green color saturation value for the rgb led.
get_blue_led	Yes	No	uint8_t	void	Returns the current blue color saturation value for the rgb led.
led_off	Yes	No	void	void	Turns off the rgb led on the Droplet.

RGB Sensing Subsystem

Function Name	Hardware	Simulator	Returns	Args	Notes & Description
get_rgb_sensor	No	Yes	void	uint8_t *r, uint8_t *g, uint8_t *b	Returns the brightness values read from the rgb sensor for red, green and blue light respectively.
get_red_sensor	Yes	No	uint8_t	void	Returns the brightness values read from the rgb sensor for red light.
get_blue_sensor	Yes	No	uint8_t	void	Returns the brightness values read from the rgb sensor for red light.
get_green_sensor	Yes	No	uint8_t	void	Returns the brightness values read from the rgb sensor for red light.

Communication Subsystem

Function Name	Hardware	Simulator	Returns	Args	Notes & Description
ir_send	Yes	In Progress	uint8_t	uint8_t channel, const char *send_buf, uint8_t length	Uses directional IR channel (0 to 5) to send the message in send_buf (with length). Returns 1 on success, 0 on failure.
ir_broadcast	Yes	Yes	uint8_t	const char *send_buf, uint8_t length	Broadcast the message in all directions. Returns 1 on success, 0 on failure.
check_for_new_messages	Yes	Yes	uint8_t	void	Checks all the IR channels for arrived messages and puts a message in the global_ir_buffer. Returns 1 if there is a new message, 0 if there are no new messages, o/w returns an error number (not 1).

Utility Functions

Function Name	Hardware	Simulator	Returns	Args	Notes & Description
set_timer	No	Yes	uint8_t	uint16_t time, uint8_t index	(In simulator only, Deprecated) Sets one of the 5 Droplet alarms to ring in time milliseconds.
check_timer	No	Yes	uint8_t	uint8_t index	(In simulator only, Deprecated) Returns 1 if the alarm index is not set. Returns 0 if the alarm index has been set but hasn't gone off, and flips back to 1 when the alarm goes off.
get_current_time	Yes	No	uint16_t	void	Get the Droplet's current system time (in ticks since it was started).
set_current_time	Yes	No	void	uint16_t	Set the Droplet's current system time (in ticks).
rand_byte	Yes	Yes	uint8_t	void	Returns a pseudo-random value between 0 and 255 (inclusive).
get_droplet_id	Yes get_id_number	Yes	uint16_t	void	Returns the droplet's unique identifier.

New API Function Requests

Function Name	Status	Returns	Args	Description
reset_motor	requested	void	uint8_t motor	motor - Reset this motor (0 to 2)
reset_timer	requested in sim	void	uint8_t timer	timer - Reset this timer (0 to MAX_TIMERS). Note that timers in the sim will eventually be deprecated but having this functionality will be useful till then.
leg_status	requested	int8_t	uint8_t leg	leg - The leg to return status for (0, 1 or 2). Returns 0 if floating, +1 if powered, -1 if grounded.
move_distance	requested	uint8_t	uint8_t direction, uint16_t distance	Move a certain distance (in cm) in the given direction. Requires fine motor calibration in hardware.
get_rgb_led	requested	void	uint8_t *r, uint8_t *g, uint8_t *b	Returns (by reference) the rgb values currently set for the led.