Capítulo 2 DESCRIPCIÓN DE ROVIO Y SU API - …bibing.us.es/proyectos/abreproy/11954/fichero/3+-+CAP.2+-+Descripc... · CONTROL E INTEGRACIÓN DE ROVIO BAJO UPNP Descripción de

CONTROL E INTEGRACIÓN DE ROVIO BAJO UPNP Descripción de ROVIO y su API

15

Capítulo 2 DESCRIPCIÓN DE ROVIO Y SU API

En este capítulo se describen, de forma general, las características del robot

ROVIO. Se indican sus partes más significativas y se enumeran los sensores y

actuadores que posee.

También se presenta y analiza la API9 publicada [12] por el fabricante

WowWee™. Se hace hincapié en aquellos comandos que han sido utilizados en la

programación de la aplicación de control.

2.1 CARACTERÍSTICAS GENERALES DEL ROBOT ROVIO

ROVIO es un robot con capacidad de movimiento y controlado de forma remota

mediante una conexión inalámbrica WiFi. En la Figura 2-1 se muestran algunos

de sus componentes y su disposición.

Figura 2-1: ROVIO (esquema)

9 Application Programming Interface.


16

Dispone de los siguientes sensores:

Cámara VGA.

Micrófono.

Sensor IR (TrueTrack) para el posicionamiento.

Sensor IR para la detección de colisiones.

Monitor de la intensidad de señal WiFi.

Monitor de la carga de las baterías.

Y cuenta con los siguientes actuadores:

Controlador de la posición del cuello del robot.

Altavoz.

3 ruedas omnidireccionales.

Luz frontal.

En la Figura 2-2 se muestra la parte inferior de ROVIO y su estación base.

Figura 2-2: ROVIO (esquema inferior) y estación base

2.1.1 SISTEMA DE POSICIONAMIENTO Y ESQUEMA DE COORDENADAS

ROVIO dispone un sensor de infrarrojos (tipo NorthStar), que en términos de

WowWee™ es llamado TrueTrack. Este sensor permite al robot navegar de forma

autónoma siguiendo caminos previamente grabados. El sistema TrueTrack realiza

la lectura de los 2 puntos de infrarrojos proyectados en el techo por la baliza de

la estación base o proyectados por una baliza individual (baliza adicional que se

adquiere por separado). La información recibida por el sensor NorthStar le


17

proporciona la posición mediante coordenadas (X,Y) y una coordenada angular

(Theta).

De forma experimental, se ha determinado el origen de las coordenadas del

sistema de posicionamiento y su orientación. En la Figura 2-3 se presentan los

resultados obtenidos.

Figura 2-3: Sistema de coordenadas de ROVIO

Este sistema de posicionamiento proporciona valores para las coordenadas (X,Y)

en unas unidades no especificadas. En el apartado 4.1.3 se realizan pruebas y un

análisis estadístico que permite relacionar los valores proporcionados por los

sensores del robot y mediciones reales de los desplazamientos. La coordenada

angular se proporciona en radianes.

2.1.2 ACERCA DEL FABRICANTE

WowWee™ es una empresa independiente fundada en 1988 que diseña,

desarrolla, comercializa y distribuye productos de tecnología de consumo y

entretenimiento.


18

En 2004 lanzaron su exitoso Robotsapiens, un robot lúdico del que vendieron

más de 6 millones de unidades en todo el mundo. En 2005 lanzaron la segunda

versión que añadía nuevas funciones, como la capacidad de reproducir sonidos.

Actualmente disponen de varias líneas de productos (Figura 2-4): Robotics

(juguetes robots), Paper Jamz (instrumentos musicales), Alive (mascotas

virtuales), FlyTech (juguetes voladores) y Technologies (a la que pertenece ROVIO

y otros productos como el proyector Cinemin).

Figura 2-4: Productos WowWee

2.2 INTERFAZ DE PROGRAMACIÓN DE APLICACIONES (API)

Debido a que la comunicación con ROVIO se hace a través de una interfaz WiFi y

que el cliente que se utiliza para acceder a él es un navegador (cliente basado en

la web), la API se basa en una serie de llamadas HTTP10 a un servidor web que

incorpora el robot. Esto significa que para crear una aplicación de control en

10 Hypertext Transfer Protocol.


19

algún lenguaje de programación sólo es necesario poder crear una conexión

TCP/IP con el servidor web y poder realizar peticiones HTTP así como recibir las

respuestas a estas peticiones. Por tanto la comunicación con ROVIO es

independiente de la plataforma, lo que permite hacer uso de esta API desde

distintos sistemas operativos (Windows, Linux, Mac) así como desde diversos

lenguajes de programación (C#, Visual Basic, Java, Python, LISP) que únicamente

deben poder trabajar con el protocolo HTTP.

Por ejemplo, para obtener un informe sobre el estado de ROVIO se ha de enviar,

por algún medio, el siguiente URI HTTP mediante una conexión TCP/IP

establecida con el servidor web del robot:

HTTP://192.168.1.2/rev.cgi?Cmd=nav&action=1

En este ejemplo 192.168.1.2 es la dirección IP de ROVIO. El resto es un comando

CGI11 que es transportado mediante el método GET de HTTP. El resultado de esta

petición es la obtención de un informe del estado del robot.

CGI es una tecnología de la World Wide Web que permite a un cliente (basado en

la web) enviar y solicitar datos de un programa ejecutado en un servidor web.

Esta tecnología especifica un estándar para transferir datos entre el cliente y el

programa. Es por tanto un mecanismo de comunicación entre el servidor web y

una aplicación CGI (a veces llamada script CGI).

En nuestro caso, el servidor web de ROVIO se comunica con una aplicación CGI

que controla el robot. El cliente hace uso de esta aplicación de control a través

de peticiones HTTP, que transportan los comandos CGI, enviadas al servidor web.

11 Common Gateway Interface.


20

2.3 COMANDOS CGI

En la Tabla 2-1 se listan todos los comandos CGI que figuran en la API publicada

por el fabricante, agrupados por las categorías definidas en el propio documento.

CATEGORÍA COMANDO CGI DESCRIPCIÓN Movimiento Rev.cgi Ver Tabla 2-2

Imagen y Sonido GetData.cgi Adquiere MJPEG

GetImage (no es un comando CGI)

Adquiere Imagen

VideoStreaming (no es un comando CGI)

Flujo de vídeo

ChangeResolution.cgi Cambia la resolución de la cámara

ChangeCompressRatio.cgi Cambia la calidad de las imágenes de la cámara

ChangeFramerate.cgi Cambia los fotogramas por segundo de la cámara

ChangeBrightness.cgi Cambia el brillo de la cámara

ChangeSpeakerVolume.cgi Cambia el volumen del altavoz

ChangeMicVolume.cgi Cambia el volumen del micrófono

SetCamera.cgi Cambia la configuración del sensor de la cámara

GetCamera.cgi Recupera la configuración del sensor de la cámara

Gestión del usuario GetMyself.cgi

Recupera el nombre de usuario que envía la petición

SetUser.cgi Añade usuario o cambia contraseña

DelUser.cgi Elimina usuario

GetUser.cgi Recupera la lista de usuarios

SetUserCheck.cgi Activa/Desactiva la autorización de usuario

Horario SetTime.cgi Establece la hora

GetTime.cgi Recupera la hora

SetLogo.cgi Coloca un logo en las imágenes

GetLogo.cgi Recupera el logo Red SetIP.cgi Establece la dirección IP

GetIP.cgi Recupera la dirección IP

SetWlan.cgi Establece la configuración de LAN inalámbrica

GetWlan.cgi Recupera la configuración de LAN inalámbrica

SetDDNS.cgi Establece la configuración DDNS

GetDDNS.cgi Recupera la configuración DDNS

Mac SetMac.cgi Establece la dirección MAC

GetMac.cgi Recupera la dirección MAC


21

Servidor HTTP SetHTTP.cgi

Establece la configuración del servidor HTTP

GetHTTP.cgi Recupera la configuración del servidor HTTP

Correo SetMail.cgi

Establece email para el envío de imágenes

GetMail.cgi Recupera el email establecido

SendMail.cgi Envía email

Otros SetName.cgi

Establece un nombre para la cámara

GetName.cgi Recupera el nombre de la cámara

GetStatus.cgi Recupera el estado de ROVIO

GetLog.cgi Recupera la información del registro del sistema de ROVIO

GetVer.cgi Recupera la versión del firmware de ROVIO

SetFactoryDefault.cgi Retorna el sistema a la configuración por defecto

Reboot.cgi Reinicia el ROVIO

GetData.cgi Recupera datos MIME de tipo “multipart/x-mixed-replace”

GetAudio.cgi Reproduce audio en el ROVIO

SetMediaFormat.cgi Establece el tipo de formato de los medios

GetMediaFormat.cgi Recupera el tipo de formato para los medios

Upload.cgi Carga un archivo de firmware

Cmd.cgi Combina varios comandos en una única petición HTTP

Tabla 2-1: Comandos CGI

Nº DE ACCIÓN FUNCIÓN DESCRIPCIÓN

1 GetReport() Recupera un informe con el estado actual

2 StartRecoding() Comienzo a grabar un camino

3 AbortRecording() Cancela la grabación de un camino

4 StopRecording(string PathName) Detiene la grabación de un camino

5 Deletepath(string PathName) Borra un camino

6 GetPathList() Recupera la lista de caminos

7 PlayPathForward(string PathName) Ejecuta un camino

8 PlayPathBackward (string PathName) Ejecuta un camino

9 StopPlaying() Detiene la ejecución de un camino

10 PausePlaying() Pausa la ejecución de un camino

11 RenamePath(string OldPathName, Renombra un camino


22

string NewPathName)

12 GoHome() Conduce a la estación base sin atracar

13 GoHomeAndDock() Conduce a la estación base y atraca

14 UpdateHomePosition() Actualiza la posición de la estación base

15 SetTuningParameters() Configura parámetros de movimiento

16 GetTuningParameters() Recupera parámetros de movimiento

17 ResetNavStateMachine() Detiene y pasa a estado ocioso

18 ManualDrive() Acepta órdenes de movimiento

19 RESERVED TestCommand()

20 GetMCUReport() Recupera informe MCU

21 ClearAllPaths() Borra todos los caminos

22 GetStatus() Recupera el estado de navegación

23 SaveParameter( long index, long value ) Guarda parámetros del robot

24 ReadParameter( long index ) Recupera parámetros del robot

25 GetLibNSVersion() Recupera la versión del sensor NS y libNS

26 EmailImage( string email ) Envía imagen en email (ejecutando camino)

27 ResetHomeLocation() Borra la posición de la estación base

Tabla 2-2: Comandos de movimiento

Nº DE CÓDIGO

CÓDIGO DE RESPUESTA DESCRIPCIÓN

0 SUCCESS Éxito

1 FAILURE Fallo

2 ROBOT_BUSY El robot está ejecutando una tarea

3 FEATURE_NOT_IMPLEMENTED Comando CGI no implementado

4 UNKNOWN_CGI_ACTION Acción requerida desconocida

5 NO_NS_SIGNAL Sin señal NS

6 NO_EMPTY_PATH_AVAILABLE Memoria para caminos llena

7 FAILED_TO_READ_PATH Fallo al leer memoria FLASH

8 PATH_BASEADDRESS_NOT_INITIALIZED Error en la memoria FLASH

9 PATH_NOT_FOUND No existe el camino

10 PATH_NAME_NOT_SPECIFIED Nombre de camino no especificado

11 NOT_RECORDING_PATH Comando de guardar camino no procedente


23

12 FLASH_NOT_INITIALIZED Fallo del subsistema de la memoria FLASH

13 FAILED_TO_DELETE_PATH Fallo de operación en la memoria FLASH

14 FAILED_TO_READ_FROM_FLASH Fallo de operación en la memoria FLASH

15 FAILED_TO_WRITE_TO_FLASH Fallo de operación en la memoria FLASH

16 FLASH_NOT_READY Fallo de operación en la memoria FLASH

17 NO_MEMORY_AVAILABLE NA

18 NO_MCU_PORT_AVAILABLE NA

19 NO_NS_PORT_AVAILABLE NA

20 NS_PACKET_CHECKSUM_ERROR NA

21 NS_UART_READ_ERROR NA

22 PARAMETER_OUTOFRANGE Parámetro fuera de rango

23 NO_PARAMETER Parámetro no especificado

Tabla 2-3: Códigos de respuesta

2.3.1 DESCRIPCIÓN DE COMANDOS RELEVANTES

En esta sección se describen en detalle algunos de los comandos más

significativos para el desarrollo de este proyecto.

Estas funciones corresponden a los métodos implementados en la clase que

permite el control de ROVIO. Para una mayor claridad se expone a continuación

parte del código (en lenguaje C#) de esta clase en el que aparece el constructor

y, a modo de ejemplos, 2 métodos, GetReport() que solicita un informe con el

estado del robot y ManualDrive(int drive, int speed) que permite enviar órdenes

de movimiento. En estos métodos se pueden apreciar los correspondientes

comandos CGI que se envían para su ejecución en el propio ROVIO.

public class RovioController {

private RovioWebClient rwc; // Objeto que permite trabajar con el protocolo HTTP private RovioSettings rovioSettings; // Objeto que encapsula la información del usuario

// Constructor de la clase. Crea el objeto que permite la comunicación con ROVIO

public RovioController(string username, string password, string address) {

this.rovioSettings = new RovioSettings(username, password, address); this.rwc = new RovioWebClient(this.rovioSettings);


24

} // Método que permite recuperar un informe con el estado de ROVIO

public string GetReport() {

return rwc.Request("rev.cgi?Cmd=nav&action=1"); // Envío del commando CGI }

// Método que permite el envío de comandos de movimientos a ROVIO

public void ManualDrive(int drive, int speed) {

rwc.Request("rev.cgi?Cmd=nav&action=18&drive=" + drive.ToString() + "&speed=" + speed.ToString()); // Envío del commando CGI

}

}

Agrupados en las categorías definidas en el documento del propio fabricante, se

proporciona una descripción del método, la gramática concreta del comando CGI

junto con los parámetros de entrada y el valor de retorno si procede. De forma

general, los comandos devuelven un código (Tabla 2-3) que describe el resultado

de la operación realizada.

2.3.1.1 Movimiento

GetReport()

o Descripción: Recupera un informe que describe el estado actual del

robot ROVIO.

o Gramática: /rev.cgi?Cmd=nav&action=1

o Valor de retorno: cadena de texto con los parámetros y sus valores

(Tabla 2-4).

PARÁMETRO DESCRIPCIÓN VALOR responses Error verificando estado 0 – no error

x, y, theta x,y = -32767 – 32768 theta = -PI – PI

room Identificador de la habitación 0 = Base. 1-9 = ID habitación

ss Intensidad de la señal de navegación

0 – 65535 (16bit)

beacon Intensidad de la señal de la baliza de la base

0 – 65535 (16bit)

beacon_x Posición horizontal de la baliza

-32767 – 32768

next_room ID de la baliza con mayor intensidad de señal

-1 = ninguna encontrada 1-9 = ID habitación


25

next_room_ss Intensidad de la señal de la baliza anterior

0 – 65535 (16bit)

state Estado de ROVIO

0 (idle) 1 (hacia la base) 2 (atracando en base) 3 (ejecutando ruta) 4 (grabando ruta)

resistance SIN USO

sm Máquina de estados (uso en depuración)

pp Punto de ruta actual (ejecutando camino)

1 - 10

flags Banderas 1 = posición base 2 = obstáculo detectado 4 = detector IR activado

Resolution Resolución de la cámara

0 = [176x144] 1 = [320x240] 2 = [352x240] 3 = [640x480]

video_compression Compresión del video 0 = Low 1 = Med 2 = High

frame_rate Tasa de fotogramas 1 - 30

user_check Configuración para la autorización de usuarios

0 = se necesita usuario y contraseña 1 = no se necesita

speaker_volume Volumen del altavoz 0 – 31

mic_volume Volumen de micrófono 0 – 31

WiFi_ss Intensidad de señal WiFi 0 - 254

show_time Configuración para mostrar la hora

0 = No mostrando hora 1 = Mostrando hora

ddns_state Estado de la actualización DDNS

0 = sin actualizar 1 = actualizando 2 = actualización correcta 3 = fallo actualizando

email_state SIN USO

battery Carga de la batería < 100 = apagar 100-106 = regresar a base 106 – 127 = normal

charging Estado de la batería 0 – 79 = no cargando 80 = cargando

head_position Posición de la cabeza de ROVIO

204 = baja 135-140 = media 65 = alta

ac_freq Frecuencia del proyector 0 = no detectado 1 = 50 Hz 2 = 60 Hz

Tabla 2-4: Comando GetReport

StartRecording()

o Descripción: Comienza a graba una ruta.


26


o Notas:

Se detendrá la grabación si se pierde la cobertura o la

conexión del usuario.

AbortRecording()

o Descripción: Detiene la grabación de una ruta sin almacenarla en la

memoria flash.


StopRecording (string PathName)

o Descripción: Detiene la grabación y la almacena en la memoria flash.

o Gramática: /rev.cgi?Cmd=nav&action=3&name=(PathName)

DeletePath(string PathName)

o Descripción: Elimina el camino especificado.


GetPathList()

o Descripción: Recupera la lista de los caminos almacenados.


PlayPathFoward(string PathName)

o Descripción: Ejecuta el camino indicado hasta el punto final del

mismo. Si la señal NorthStar se pierde el robot se detiene.


PlayPathBackward(string PathName)

o Descripción: Ejecuta el camino indicado hasta el punto inicial del

mismo. Si la señal NorthStar se pierde el robot se detiene.


StopPlaying()

o Descripción: Detiene la ejecución de un camino.


PausePlaying()

o Descripción: Suspende la ejecución de un camino y espera una nueva

orden de pausa (reanudación) o detención definitiva (StopPlaying()).


RenamePath(string OldPathName, string NewPathName)

o Descripción: Renombra un camino almacenado.

o Gramática: /rev.cgi?Cmd=nav&action=11&name=(OldPathName)

&newname=(NewPathName)


27

GoHome()

o Descripción: El robot se desplaza hasta la estación base sin atracar.


GoHomeAndDock()

o Descripción: El robot se desplaza hasta la estación base e intenta

atracar.


UpdateHomePosition()

o Descripción: Define la posición actual como la posición de estación

base (típicamente frente a la base de recarga).


ResetNavStateMachine()

o Descripción: Detiene cualquier acción en curso y pone al robot en

estado ocioso (idle).


ManualDrive(int Drive, int Speed)

o Descripción: Ordenes manuales de movimiento. Se especifica un tipo

de movimiento y la velocidad deseada (Tabla 2-5).

o Gramática: /rev.cgi?Cmd=nav&action=18&drive=(Drive)

&speed=(Speed)

o Notas: Nótese que la mayor velocidad posible corresponde con el

menor valor para el parámetro (Speed).

(Drive) MOVIMIENTO (Drive) MOVIMIENTO

0 Parar 11 Cámara posición alta

1 Adelante 12 Cámara posición baja

2 Atrás 13 Cámara posición media

3 Deplazamiento lateral izquierda 14 (resevado)

4 Deplazamiento lateral derecha 15 (resevado)

5 Rotación izquierda 16 (resevado)

6 Rotación derecha 17 Rotación izquierda (20°)

7 Diagonal adelante-izquierda 18 Rotación derecha (20°)

8 Diagonal adelante-derecha

9 Diagonal atrás-izquierda (Speed)

10 Diagonal atrás-derecha 1(rápida), 2, 3, 4, 5, 6, 7, 8, 9, 10(lenta)

Tabla 2-5: Comando ManualDrive

ClearAllPaths()


28

o Descripción: Elimina todos los caminos almacenados en la memoria

flash.


2.3.1.2 Control de la cámara

GetImage(int Valor)

o Descripción: Captura una imagen con la cámara.

o Gramática: /Jpeg/Camimg(Valor).jpg

o Notas:

(Valor) = número aleatorio de 4 dígitos.

El valor de retorno de la orden es la imagen jpg.

ChangeResolution(int Valor)

o Descripción: Establece la resolución (4 posibilidades) de la cámara

para la captura de imágenes.

o Gramática: /ChangeResolution.cgi?ResType=(Valor)

(Valor) RESOLUCIÓN (píxeles) (Valor) RESOLUCIÓN (píxeles)

0 176 * 144 2 320 * 240

1 352 * 288 3 640 * 480

Tabla 2-6: Comando ChangeResolution

ChangeBrightness(int Valor)

o Descripción: Establece el brillo para las capturas de imágenes.

o Gramática: /ChangeBrightness.cgi?ResType=(Valor)

o Notas:

(Valor) = 0 (menor brillo)|1|2|3|4|5|6 (mayor brillo).

2.3.1.3 Gestión de usuarios

GetMyself(bool Muestra)

o Descripción: Recupera el nombre de usuario de quién realiza la

petición.

o Gramática: /GetMyself.cgi?ShowPrivilege=(Muestra)

o Notas:

(Muestra) = true | false.

Devuelve el nombre de usuario y su tipo si se ha solicitado (0

para invitado, 1 para administrador).

SetUser(string Nombre, string Contraseña, int Valor)


29

o Descripción: Añade un nuevo usuario o modifica la contraseña de un

usuario existente.

o Gramática:

/SetUser.cgi?User=(Nombre)&Pass=(Contraseña)&Privilege=(Valor)

o Notas:

Se ha de especificar el nombre de usuario a crear o modificar,

la contraseña asociada y el tipo de usuario. (Valor)=0 para

invitado o (Valor)=1 para administrador.

Esta orden sólo puede ser ejecutada por un usuario

administrador.

DelUser(string Nombre)

o Descripción: Elimina el usuario especificado.

o Gramática: /DelUser.cgi?User=(Nombre)

o Notas:


administrador.

GetUser(bool Muestra)

o Descripción: Recupera la lista completa de usuarios definidos.

o Gramática: /GetUser.cgi? ShowPrivilege=(Muestra)

o Notas:

Si se especifica (Muestra) = true se recupera, además de los

nombres de usuario, su tipo.


administrador.

SetUserCheck(bool Activa)

o Descripción: Activa o desactiva la solicitud de contraseña al establecer

la conexión con el robot.

o Gramática: /SetUserCheck.cgi? Check=(Activa)

o Notas:

(Activa) = true | false


administrador.

2.3.1.4 Otras órdenes

GetVer()

o Descripción: Obtiene la versión del firmware del robot.

o Gramática: /GetVer.cgi


30

SetFactoryDefault()

o Descripción: Establece la configuración por defecto.

o Gramática: /SetFactoryDefault.cgi

o Notas:


administrador.

Reboot()

o Descripción: Reinicia el robot.

o Gramática: /Reboot.cgi

o Notas:


administrador.

Documents

Capítulo 2 DESCRIPCIÓN DE ROVIO Y SU API - …bibing.us.es/proyectos/abreproy/11954/fichero/3+-+CAP.2+-+Descripc... · CONTROL E INTEGRACIÓN DE ROVIO BAJO UPNP Descripción de