Extended API

Files
file	apix.h

Device Registration
enum	v5_device_e {   E_DEVICE_NONE = 0 , E_DEVICE_MOTOR = 2 , E_DEVICE_ROTATION = 4 , E_DEVICE_IMU = 6 ,   E_DEVICE_DISTANCE = 7 , E_DEVICE_RADIO = 8 , E_DEVICE_VISION = 11 , E_DEVICE_ADI = 12 ,   E_DEVICE_OPTICAL = 16 , E_DEVICE_GPS = 20 , E_DEVICE_AIVISION = 29 , E_DEVICE_SERIAL = 129 ,   __attribute__ =((deprecated("use E_DEVICE_SERIAL instead"))) = E_DEVICE_SERIAL , E_DEVICE_UNDEFINED = 255 }
	List of possible v5 devices. More...
typedef enum v5_device_e	v5_device_e_t
int	registry_bind_port (uint8_t port, v5_device_e_t device_type)
int	registry_unbind_port (uint8_t port)
v5_device_e_t	registry_get_bound_type (uint8_t port)
v5_device_e_t	registry_get_plugged_type (uint8_t port)

RTOS Facilities
typedef void *	queue_t
typedef void *	sem_t
bool	task_abort_delay (task_t task)
void	task_notify_when_deleting (task_t target_task, task_t task_to_notify, uint32_t value, notify_action_e_t notify_action)
task_t	mutex_get_owner (mutex_t mutex)
sem_t	sem_create (uint32_t max_count, uint32_t init_count)
void	sem_delete (sem_t sem)
sem_t	sem_binary_create (void)
bool	sem_wait (sem_t sem, uint32_t timeout)
bool	sem_post (sem_t sem)
uint32_t	sem_get_count (sem_t sem)
queue_t	queue_create (uint32_t length, uint32_t item_size)
bool	queue_append (queue_t queue, const void *item, uint32_t timeout)
bool	queue_peek (queue_t queue, void *const buffer, uint32_t timeout)
bool	queue_recv (queue_t queue, void *const buffer, uint32_t timeout)
uint32_t	queue_get_waiting (const queue_t queue)
uint32_t	queue_get_available (const queue_t queue)
void	queue_delete (queue_t queue)
void	queue_reset (queue_t queue)

Startup options
void	enable_banner (bool enabled)
#define	PRE_PROS_INIT_PRIORITY   101
#define	ENABLE_BANNER(enabled)

Filesystem
int32_t	fdctl (int file, const uint32_t action, void *const extra_arg)
int32_t	motor_set_reversed (int8_t port, const bool reverse)
int32_t	motor_is_reversed (int8_t port)
#define	SERCTL_ACTIVATE   10
#define	SERCTL_DEACTIVATE   11
#define	SERCTL_BLKWRITE   12
#define	SERCTL_NOBLKWRITE   13
#define	SERCTL_ENABLE_COBS   14
#define	SERCTL_DISABLE_COBS   15
#define	DEVCTL_FIONREAD   16
#define	DEVCTL_FIONWRITE   18
#define	DEVCTL_SET_BAUDRATE   17

Detailed Description

Note

Also included in the Extended API is LVGL.

Macro Definition Documentation

DEVCTL_FIONREAD

#define DEVCTL_FIONREAD   16

Action macro to check if there is data available from the Generic Serial Device

DEVCTL_FIONWRITE

#define DEVCTL_FIONWRITE   18

Action macro to check if there is space available in the Generic Serial Device's output buffer

DEVCTL_SET_BAUDRATE

#define DEVCTL_SET_BAUDRATE   17

Action macro to set the Generic Serial Device's baudrate.

The extra argument is the baudrate.

ENABLE_BANNER

#define ENABLE_BANNER

(

enabled

)

Value:

        static_assert(                                                                             \
            !__builtin_strcmp(__FUNCTION__, "top level"),                                          \
            "Cannot use ENABLE_BANNER inside a function!"                                          \
        );                                                                                         \
        __attribute__((constructor(PRE_PROS_INIT_PRIORITY))) static void _enable_banner_impl() {   \
            enable_banner(enabled);                                                                \
        }

Enable/disable the PROS banner printed to the serial stream.

Warning

This macro must be used in global scope, outside of any function.

Parameters

enable

Whether the banner should be enabled or disabled.

PRE_PROS_INIT_PRIORITY

#define PRE_PROS_INIT_PRIORITY   101

This priority value, when used with attribute((constructor( ))), is guaranteed to run before PROS initializes.

SERCTL_ACTIVATE

#define SERCTL_ACTIVATE   10

Action macro to pass into serctl or fdctl that activates the stream identifier.

When used with serctl, the extra argument must be the little endian representation of the stream identifier (e.g. "sout" -> 0x74756f73)

SERCTL_BLKWRITE

#define SERCTL_BLKWRITE   12

Action macro to pass into fdctl that enables blocking writes for the file

The extra argument is not used with this action, provide any value (e.g. NULL) instead

SERCTL_DEACTIVATE

#define SERCTL_DEACTIVATE   11

Action macro to pass into serctl or fdctl that deactivates the stream identifier.

When used with serctl, the extra argument must be the little endian representation of the stream identifier (e.g. "sout" -> 0x74756f73)

SERCTL_DISABLE_COBS

#define SERCTL_DISABLE_COBS   15

Action macro to pass into serctl that disables advanced stream multiplexing capabilities

The extra argument is not used with this action, provide any value (e.g. NULL) instead

SERCTL_ENABLE_COBS

#define SERCTL_ENABLE_COBS   14

Action macro to pass into serctl that enables advanced stream multiplexing capabilities

The extra argument is not used with this action, provide any value (e.g. NULL) instead

SERCTL_NOBLKWRITE

#define SERCTL_NOBLKWRITE   13

Action macro to pass into fdctl that makes writes non-blocking for the file

The extra argument is not used with this action, provide any value (e.g. NULL) instead

Enumeration Type Documentation

v5_device_e

enum v5_device_e

List of possible v5 devices.

This list contains all current V5 Devices, and mirrors V5_DeviceType from the api.

Enumerator
E_DEVICE_NONE	No device is plugged into the port.
E_DEVICE_MOTOR	A motor is plugged into the port.
E_DEVICE_ROTATION	A rotation sensor is plugged into the port.
E_DEVICE_IMU	An inertial sensor is plugged into the port.
E_DEVICE_DISTANCE	A distance sensor is plugged into the port.
E_DEVICE_RADIO	A radio is plugged into the port.
E_DEVICE_VISION	A vision sensor is plugged into the port.
E_DEVICE_ADI	This port is an ADI expander.
E_DEVICE_OPTICAL	An optical sensor is plugged into the port.
E_DEVICE_GPS	A GPS sensor is plugged into the port.
E_DEVICE_AIVISION	An AI Vision sensor is plugged into the port.
E_DEVICE_SERIAL	A serial device is plugged into the port.
E_DEVICE_UNDEFINED	The device type is not defined, or is not a valid device.

Function Documentation

enable_banner()

void enable_banner

(

bool

enabled

)

Enable/disable the PROS banner printed to the serial stream.

Warning

This function must be called BEFORE the PROS daemon starts. The easiest way to acheive this is to NOT call this function directly, and instead use the BANNER_ENABLE macro.

Parameters

enable

Whether the banner should be enabled or disabled.

fdctl()

int32_t fdctl	(	int	file,
		const uint32_t	action,
		void *const	extra_arg )

Control settings of the serial driver.

Parameters

action	An action to perform on the serial driver. See the SERCTL_* macros for details on the different actions.
extra_arg	An argument to pass in based on the action

Example:

   void opcontrol(void) {
     serctl(SERCTL_SET_BAUDRATE, (void*) 9600);
   }
  /
int32_t serctl(const uint32_t action, void* const extra_arg);
 
/*
 * Control settings of the microSD card driver.
 *
 * \param action
 *          An action to perform on the microSD card driver. See the USDCTL_* macros
 *      for details on the different actions.
 * \param extra_arg
 *          An argument to pass in based on the action
 */
// Not yet implemented
// int32_t usdctl(const uint32_t action, void* const extra_arg);

motor_is_reversed()

int32_t motor_is_reversed

(

int8_t

port

)

Gets the operation direction of the motor as set by the user.

This function uses the following values of errno when an error state is reached: ENXIO - The given value is not within the range of V5 ports (1-21). ENODEV - The port cannot be configured as a motor

Parameters

port	The V5 port number from 1-21

Returns

1 if the motor has been reversed and 0 if the motor was not reversed, or PROS_ERR if the operation failed, setting errno.

Example

motor_set_reversed()

int32_t motor_set_reversed	(	int8_t	port,
		const bool	reverse )

Sets the reverse flag for the motor.

This will invert its movements and the values returned for its position.

This function uses the following values of errno when an error state is reached: ENXIO - The given value is not within the range of V5 ports (1-21). ENODEV - The port cannot be configured as a motor

Parameters

port	The V5 port number from 1-21
reverse	True reverses the motor, false is default

Returns

1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

Example

mutex_get_owner()

task_t mutex_get_owner

(

mutex_t

mutex

)

Returns a handle to the current owner of a mutex.

Parameters

mutex

A mutex handle

Returns

A handle to the current task that owns the mutex, or NULL if the mutex isn't owned.

Example:

queue_append()

bool queue_append	(	queue_t	queue,
		const void *	item,
		uint32_t	timeout )

Posts an item to the front of a queue. The item is queued by copy, not by reference.

Parameters

queue	The queue handle
item	A pointer to the item that will be placed on the queue.
timeout	Time to wait for space to become available. A timeout of 0 can be used to attempt to post without blocking. TIMEOUT_MAX can be used to block indefinitely.

Returns

True if the item was preprended, false otherwise.

Example:

queue_create()

queue_t queue_create	(	uint32_t	length,
		uint32_t	item_size )

Creates a queue.

Parameters

length	The maximum number of items that the queue can contain.
item_size	The number of bytes each item in the queue will require.

Returns

A handle to a newly created queue, or NULL if the queue cannot be created.

Example:

queue_delete()

void queue_delete

(

queue_t

queue

)

Delete a queue.

Parameters

queue

Queue handle to delete

Example:

queue_get_available()

uint32_t queue_get_available

(

const queue_t

queue

)

Return the number of spaces left in a queue.

Parameters

queue

The queue handle.

Returns

The number of spaces available in the queue.

Example:

queue_get_waiting()

uint32_t queue_get_waiting

(

const queue_t

queue

)

Return the number of messages stored in a queue.

Parameters

queue

The queue handle.

Returns

The number of messages available in the queue.

Example:

queue_peek()

bool queue_peek	(	queue_t	queue,
		void *const	buffer,
		uint32_t	timeout )

Receive an item from a queue without removing the item from the queue.

Parameters

queue	The queue handle
buffer	Pointer to a buffer to which the received item will be copied
timeout	The maximum amount of time the task should block waiting for an item to receive should the queue be empty at the time of the call. TIMEOUT_MAX can be used to block indefinitely.

Returns

True if an item was copied into the buffer, false otherwise.

Example:

queue_recv()

bool queue_recv	(	queue_t	queue,
		void *const	buffer,
		uint32_t	timeout )

Receive an item from the queue.

Parameters

queue	The queue handle
buffer	Pointer to a buffer to which the received item will be copied
timeout	The maximum amount of time the task should block waiting for an item to receive should the queue be empty at the time of the call. queue_recv() will return immediately if timeout is zero and the queue is empty.

Returns

True if an item was copied into the buffer, false otherwise.

Example:

queue_reset()

void queue_reset

(

queue_t

queue

)

Resets a queue to an empty state

Parameters

queue

Queue handle to reset

Example:

registry_bind_port()

int registry_bind_port	(	uint8_t	port,
		v5_device_e_t	device_type )

Registers a device in the given zero-indexed port

Registers a device of the given type in the given port into the registry, if that type of device is detected to be plugged in to that port.

This function uses the following values of errno when an error state is reached: ENXIO - The given value is not within the range of V5 ports (0-20), or a a different device than specified is plugged in. EADDRINUSE - The port is already registered to another device.

Parameters

port	The port number to register the device
device	The type of device to register

Returns

1 upon success, PROS_ERR upon failure

Example:

registry_get_bound_type()

v5_device_e_t registry_get_bound_type

(

uint8_t

port

)

Returns the type of device registered to the zero-indexed port.

This function uses the following values of errno when an error state is reached: ENXIO - The given value is not within the range of V5 ports (0-20).

Parameters

port	The V5 port number from 0-20

Returns

The type of device that is registered into the port (NOT what is plugged in)

Example:

registry_get_plugged_type()

v5_device_e_t registry_get_plugged_type

(

uint8_t

port

)

Returns the type of the device plugged into the zero-indexed port.

This function uses the following values of errno when an error state is reached: ENXIO - The given value is not within the range of V5 ports (0-20).

Parameters

port	The V5 port number from 0-20

Returns

The type of device that is plugged into the port (NOT what is registered)

Example:

registry_unbind_port()

int registry_unbind_port

(

uint8_t

port

)

Deregisters a devices from the given zero-indexed port

Removes the device registed in the given port, if there is one.

This function uses the following values of errno when an error state is reached: ENXIO - The given value is not within the range of V5 ports (0-20).

Parameters

port	The port number to deregister

Returns

1 upon success, PROS_ERR upon failure

Example:

sem_binary_create()

sem_t sem_binary_create

(

void

)

Creates a binary semaphore.

Returns

A newly created semaphore.

Example:

sem_create()

sem_t sem_create	(	uint32_t	max_count,
		uint32_t	init_count )

Creates a counting sempahore.

Parameters

max_count	The maximum count value that can be reached.
init_count	The initial count value assigned to the new semaphore.

Returns

A newly created semaphore. If an error occurred, NULL will be returned and errno can be checked for hints as to why sem_create failed.

Example:

sem_delete()

void sem_delete

(

sem_t

sem

)

Deletes a semaphore (or binary semaphore)

Parameters

sem	Semaphore to delete

Example:

sem_get_count()

uint32_t sem_get_count

(

sem_t

sem

)

Returns the current value of the semaphore.

Parameters

sem	A semaphore handle

Returns

The current value of the semaphore (e.g. the number of resources available)

Example of sem_get_count:

sem_post()

bool sem_post

(

sem_t

sem

)

Increments a semaphore's value.

Parameters

sem	Semaphore to post

Returns

True if the value was incremented, false otherwise. If false is returned, then errno is set with a hint about why the semaphore couldn't be taken.

Example:

sem_wait()

bool sem_wait	(	sem_t	sem,
		uint32_t	timeout )

Waits for the semaphore's value to be greater than 0. If the value is already greater than 0, this function immediately returns.

Parameters

sem	Semaphore to wait on
timeout	Time to wait before the semaphore's becomes available. A timeout of 0 can be used to poll the sempahore. TIMEOUT_MAX can be used to block indefinitely.

Returns

True if the semaphore was successfully take, false otherwise. If false is returned, then errno is set with a hint about why the sempahore couldn't be taken.

Example:

task_abort_delay()

bool task_abort_delay

(

task_t

task

)

Unblocks a task in the Blocked state (e.g. waiting for a delay, on a semaphore, etc.).

Parameters

task	The task to unblock

Returns

True if the task was unblocked, false otherwise

Example:

task_notify_when_deleting()

void task_notify_when_deleting	(	task_t	target_task,
		task_t	task_to_notify,
		uint32_t	value,
		notify_action_e_t	notify_action )

Notify a task when a target task is being deleted.

Parameters

target_task	The task being watched for deletion
task_to_notify	The task to notify when target_task is deleted
value	The value to supply to task_notify_ext
notify_action	The action to supply to task_notify_ext

Example: