API de programación

API de programación

Para simplificar la programación de aplicaciones para la base de RMA (percepción y control de alto nivel) hemos creado una pequeña API que oculta al programador los detalles de implementación del sistema (ver "Arquitectura SW").

La API ha sido escrita en lenguaje C e implementada como una librería de programación (liboptimus_api.a). Se ha compilado con gcc y ejecutado con éxito en diferentes distribuciones de GNU/Linux (Debian y RedHat). A diferencia del código escrito para el microcontrolador, la API todavía se encuentra en una fase muy temprana de desarrollo. Por tal motivo, posee relativamente pocas funciones y algunos errores que poco a poco se irán subsanando.

Actualmente, la API proporciona tres tipos de funcionalidad básica:

De comunicaciones: constituida por las funciones que permiten ocultar al programador la forma de establecer conexión/desconexión de comunicaciones con la base de RMA.
De control: constituida por las funciones que permiten controlar el movimiento y velocidad de la base de RMA.
De estado: constituida por las funciones que permiten obtener e interpretar (cambio de unidades internas a unidades métricas) el valor de las variables de estado internas de la base de RMA.

A continuación se muestra la relación de funciones implementadas en la API clasificadas atendiendo a la clasificación anterior.

Familia	Prototipo	Descripción
Estado	int read_status(t_status_vector *sv)	Lee el vector de estado y lo almacena en una estructura de datos.
Estado	long int get_internal_time(t_status_vector *sv)	Recupera el tiempo interno de la estructura de datos sv.
Estado	int get_left_pwm(t_status_vector *sv)	Devuelve el ciclo de trabajo PWM del motor izquierdo.
Estado	int get_right_pwm(t_status_vector *sv)	Devuelve el ciclo de trabajo PWM del motor derecho.
Estado	int get_left_tics(t_status_vector *sv)	Devuelve la velocidad en tics/intervalo del motor izquierdo.
Estado	int get_right_tics(t_status_vector *sv)	Devuelve la velocidad en tics/intervalo del motor derecho.
Estado	int get_left_vel(t_status_vector *sv)	Devuelve la velocidad en m/s del motor izquierdo.
Estado	int get_right_vel(t_status_vector *sv)	Devuelve la velocidad en m/s del motor derecho.
Estado	int get_desired_v_tics(t_status_vector *sv)	Devuelve la velocidad deseada en tics/s.
Estado	int get_desired_v_tics(t_status_vector *sv)	Devuelve la velocidad deseada en m/s.
Estado	set_desired_w(t_status_vector *sv)	Devuelve la velocidad angular, w, deseada.
Estado	float get_pos_x(t_status_vector *sv)	Devuelve la posición respecto al eje X.
Estado	float get_pos_y(t_status_vector *sv)	Posición respecto al eje Y.
Estado	float get_pos_th(t_status_vector *sv)	Devuelve el ángulo respecto al eje X.
Estado	float get_logic_batt(t_status_vector *sv)	Devuelve el voltaje de las baterías.
Control	void set_time(long int time)	Reinicia el reloj interno al valor fijado.
Control	void set_pose(float x, float y, float th)	Fija la posición de referencia odométrica.
Control	void set_vel_tics(int v, int w)	Fija la velocidad actual en unidades de tics/intervalo.
Control	void set_vel(int v, int w)	Fija la velocidad actual especificada en m/s y grados/s.
Control	void stop()	Efectúa una parada inmediata de los motores.
Control	void free_stop()	Apaga los motores, pero los deja girar hasta que se detengan por sí solos.
Comunicaciones	int connect(char *device)	Establece una conexión con la base de RMA.
Comunicaciones	int disconnect(char *device)	Desactiva una conexión establecida con la base de RMA.

Y para terminar, se muestran un par de ejemplos de uso muy sencillos:

Ejemplo 01. Ejemplo de conexión/desconexión

// Prototipos y defines de liboptimus_api.a
#include ``optimus.h''

int main(int argc, char *argv[]) {

  t_status_vector sv;

  // Conexión.
  if (connect(argv[1]) < 0) {
    printf("Optimus Panic!");
    printf("(¿está encendido?)\n");
    exit(-1);
  }

  // OK.
  printf("Conectado con Optimus.\n");

  // Lectura del estado de Optimus.
  read_status(&sv);

  // desconexión.
  disconnect();

}

Ejemplo 02. Envío de comandos y gestión de variables de estado

...

  setvel(0.4, 0); // Avanza en línea recta a 0,4 m/s.

  sleep(1);

  read_status(&sv); // Lectura del estado.

  // Comprobamos si alcanzó la velocidad deseada.
  if ((get_left_vel(&sv) < 0.4) &&
      (get_right_vel(&sv) < 0.4))

    printf(``Todavía no alcanzó la velocidad deseada.\n'');

...