Proyecto Butiá - Contribuciones del usuario [es]

Usb4all shield butia

2011-12-26T13:23:01Z

Edgardo:

Este shield fue realizado para utilizarse con la placa de entrada/salida [[usb4all]], la cual puede realizarse con materiales disponibles en el mercado local. Dado que el circuito es muy sencillo y los componentes se obtienen en tamaños que permiten ser manipulados es posible realizarla manualmente por personas no expertas, bajando considerablemente los costos en relación a otras placas como arduino. Cabe destacar que la placa implementa el protocolo USB, no siendo necesario incluir un conversor USB/serial en el circuito. El proyecto USB4all es libre y se encuentra bajo licencia GNU/GPL 2.0 en el [http://sourceforge.net/projects/usb4all/ repositorio de sourceforge].
USB4all surge como un [http://www.fing.edu.uy/inco/grupos/mina/pGrado/pgusb proyecto academico de grado de la UdelaR]. 
Lo primero que necesitamos para realizar un shield butiá USB4all es descargar el diseño del mismo, esto puede realizarse obteniendo los fuentes desde el [http://sourceforge.net/projects/usb4all/ repositorio en sourceforge]. 
[[Archivo:shield_usb4all1.jpg|720px]] 
Los fuentes pueden encontrarse en el directorio ''shield_butia_rj45_rj11'', están realizados utilizando [http://www.lis.inpg.fr/realise_au_lis/kicad/ Kicad] el cual posee licencia GPL. 
Al igual que otros programas de diseño de circuitos, Kicad permite exportar a formato ''gerber''. Este formato permite su utilización por maquinas de producción de circuitos impresos, en el mercado local existen varias empresas brindan este servicio utilizando el formato gerber. También existen sitios en internet que fabrican y envían por correo el producto. Hay que tener en cuenta que el circuito cuenta con dos capas, lo que hace más complejo la realización con métodos manuales. La lista de componentes necesarios para realizar un shield es la siguiente: 
* 1 PCB shield butiá USB4all
* 2 Conector tira zócalo 40 terminales
* 1 Bornera 2p BR102A through hole
* 8 Jack RJ45 para impreso TFN188P
* 1 MC14051BD S016
* 8 resistencias de 10K
* resistencias de diferentes valor para sensores

Este shield busca solucionar los problemas indentificados en el [[Construccion_shield_v1.0|shieldv1]], como ser el gasto innecesario de pines para realizar la identificación del dispositivo conectado, asi como ser más robusto mecánicamente con los conectores. Pistas y ruteo más amplio para evitar la introducción de corto circuitos debido a la imprecisión que muchas casas manejan a la hora de fabricar circuitos. También intenta homogeneizar los conectores, utilizando para los motores el mismo tipo de conector que para el resto de los sensores/actuadores. Por otro lado, mantiene muy buenas ideas que fueron incorporadas en el [[Construccion_shield_v1.0|shieldv1]] como ser la identificación de dispositivos mediante pines dedicados a esa tarea. Este mecanismo de plug&play permite conectar cualquier sensor/actuador en cualquier puerto del shield, evitando etapas de configuración en el software. 
La idea fundamental del shield es reducir la cantidad de pines de identificación a un solo pin del microcontrolador. Para esto se utiliza un multiplexor analógico [http://www.ee.mut.ac.th/datasheet/doc/MC14051.pdf MC14051]. El multiplexor recibe como entrada los 8 pines de identificación (uno por cada conector físico), y mediante 3 pines de direccionamiento se multiplexa los valores de identificación de cada puerto. Para esta tarea se usan 4 bits de microcontrolador, uno para el pin de identificación multiplexado y tres para direccionamiento en el multiplexor.

== Pasos ==
Fabricación del PCB: 
[[Archivo:shield_usb4all2.jpg|720px]] 
[[Archivo:shield_usb4all3.jpg|720px]] 
Se utilizan conectores RJ45, lo que permite aumentar la robustez del conector y facilidad de fabricación. 
Se colocan en el circuito: 
[[Archivo:shield_usb4all4.jpg|720px]] 
[[Archivo:shield_usb4all5.jpg|720px]] 
Se sueldan: 
[[Archivo:shield_usb4all6.jpg|720px]] 
Se utilizan headers para permitir conexión con la placa USB4all: 
[[Archivo:shield_usb4all7.jpg|720px]] 
[[Archivo:shield_usb4all8.jpg|720px]] 
Bornera para alimentación de motores: 
[[Archivo:shield_usb4all9.jpg|720px]] 
[[Archivo:shield_usb4all10.jpg|720px]] 
[[Archivo:shield_usb4all12.jpg|720px]] 
Resistencias de 10K en cada uno de los puertos para permitir medir la tensión de cada uno de los id de los sensores: 
[[Archivo:shield_usb4all14.jpg|720px]] 
[[Archivo:shield_usb4all15.jpg|720px]] 
Dado que la distancia entre los pines del multiplexor es muy pequeña utilizamos el procedimiento de estañar los pads. 
[[Archivo:shield_usb4all13.jpg|720px]] 
Colocamos el multiplexor sobre los pads estañados y aproximando el soldador vamos soldando cada uno de los pines del multiplexor. 
[[Archivo:shield_usb4all11.jpg|720px]] 
Finalmente se conecta el shield a la placa USB4all, el pin marcado con un cuadradito en el shield corresponde con el pin 1 de la USB4all y el microcontrolador pic18f4550 utilizado por la misma. 

== Divisor resistivo ==
Para poder identificar los distintos elementos que se van a utilizar, usamos un divisor resistivo como identificador. 
[[Archivo:divisor_resistivo.png]] 
La resistencia R2 va conectada a tierra, la misma se encuetra en la placa ''USB4all shield butia'' y su valor es de 10kΩ. 
En cambio la resistencia R1 es variable lo que nos brinda un margen de acción que nos permite tener diferentes identificadores, lo que nos permite reconocer que sensor ha sido conectado. 
Esta resistencia se conecta a VCC(5V) y se encuentra en el lado del sensor. 
La tensión aproximada del identificador esta dada por la siguiente ecuación: 
[[Archivo:divresistivo.png]] 
 
Ese voltaje es medido por el pin 10 de la PIC18f4550. 
El diseño e implementación de este circuito no hubiera podido ser realizado sin la ayuda e ideas aportadas por Santiago Reyes.

Usb4all

2011-10-31T14:15:59Z

Edgardo: /* 4. Grabando el Firmware */

== 1. Motivación ==

La motivación de este proyecto se centra en lograr de una manera sencilla, la comunicación entre un sistema computador y un conjunto de dispositivos electrónicos no necesariamente pensados para interactuar con una computadora.
Durante muchos años la única forma de interactuar con dispositivos externos desde a un computador personal (Personal Computer) (PC) fueron los puertos seriales y paralelos, esto llevo a que se utilizaran ampliamente en multiplicidad de dispositivos. Sus principales carácteristicas son su simplicidad de manejo vía software y facilidad de inclusión en distintos dispositivos. En la última década han aparecido nuevos medios o canales de comunicación, tales como Bluetooth, Fidelidad Inalámbrica (Wireless Fidelity) (WiFi), FireWire, Bus Universal en Serie (Universal Serial Bus) (USB), etc. Estos permitieron mejorar las velocidades de comunicación y calidad de datos y lentamente tornaron a los puertos paralelos y seriales en obsoletos, hasta llegar al día de hoy en que se obtienen sólo de manera opcional en los nuevos PC.
Dentro de todas estas nuevas tecnologías que aparecieron la que tuvo mayor aceptación y difusión entre los usuarios fue el USB, debido a su facilidad y versatilidad de escenarios de uso. Esta simplicidad desde el punto de vista del usuario de los dispositivos USB tiene como contrapartida una mayor complejidad para los desarrolladores de software y hardware, lo cual es un gran problema al momento de interactuar con dispositivos electrónicos.
Frente a estas adversidades que presenta el entorno actual aparece la necesidad de buscar una forma de reducir el grado de complejidad y conocimientos necesarios para poder desarrollar
software que utilice la tecnología USB. Al mismo tiempo, se requiere una plataforma base que incorpore componentes de hardware reutilizables y que en conjunto formen una solución genérica
para la comunicación con dispositivos electrónicos diversos.
En el contexto de lo antedicho aparecen un conjunto de desafíos como son el desarrollo de controladores (drivers) y construcción de piezas de hardware que brinde una solución genérica
reutilizable, desplazando el manejo de los casos particulares a componentes específicos. Esto proporciona el beneficio de evitar que cada vez que se necesite conectar un nuevo dispositivo,
se comience desde cero. A su vez permite recuperar y potenciar la característica de facilidad de manejo que poseían los puertos seriales y paralelos, explotando todas las capacidades brindadas
por USB.

== 2. Arquitectura (Firmware/Hardware)==

La arquitectura esta compuesta por diferentes componentes, los cuales van a permitir el funcionamiento del sistema desde lo relativo al hardware como las abstracciones necesarias para manejarlo mediante software. 
Los componentes principales son:

'''2.1 USB4all ''Baseboard'''''

[[Archivo:usb4all2.png|thumb|Fig.2.1.1: USB4all Baseboard 2.0]]
Es una placa de entrada/salida(E/S) configurable que se conecta por USB con un sistema computador. El proyecto USB4all es mucho más que una placa de E/S, en sí es una forma de modelar sistemas embebidos, siendo la placa de E/S un componente que fue necesario construir para desarrollar la solución completa. Para la construcción de esta placa se utilizó un microcontrolador PIC18F4550 de Microchip. Entre las características más destacadas en lo que concierne al proyecto se encuentra el soporte completo del estándar USB, pudiéndose utilizar varias de sus características, como ser diferentes tipos de transferencias y varios canales de comunicación (endpoints).

'''2.2 USB4all ''base firmware'''''

Es el firmware más estático, brinda servicios a los usermodules para que puedan utilizar los recursos presentes en la baseboard (timmers, puerto USB, conversores A/D, etc) además de brindar las primitivas para el intercambio de mensajes entre el computador y el usermodule y realiza la gestión de los ''usermodules''. Establece las bases para que los usermodules sean independientes del protocolo de comunicación computador/placa y de los detalles de hardware del microcontrolador utilizado. A su vez oferce un entorno de ejecución concurrente que permite instanciar de forma dinámica varios ''usermodules''.

'''2.3 USB4all ''usermodule'''''
Son los componentes intercambiables del sistema que permiten encapsular la lógica de un dispositivo especifico y su protocolo de comunicación con las aplicaciones de usuario. Permite al usuario dar rápidamente soporte a un nuevo dispositivo de forma genérica, expandiendo de ésta manera las funcionalidades del USB4all ''basefirmware''. Los ''user modules'' son los bloques principales sobre los que se construye la arquitectura USB4all. Exponen una API uniforme que es utilizada a modo de callbacks por el ''base firmware'' y también exponen los servicios que brindan los dispositivos. Es recomendable modelar cada uno de los dispositivos electrónicos conectados a la ''baseboard'' como un ''usermodule'' donde los servicios a exponer se mapean con las características del mismo, como ejemplo en el caso de un motor, sería esperable que expusiera servicios para moverse, cambiar la velocidad y el sentido.

Del lado del sistema computador se dispone de diferentes formas de interacción: Todas ellas implementan el protocolo USB4all, su objetivo es abstraer al usuario del mismo brindando una forma sencilla de utilizar el sistema, existiendo soporte para diferentes lenguajes de programación. El objetivo principal de las bibliotecas utilizadas en el computador son las de permitir utilizar los servicios de los ''usermodules''. Esta forma de trabajo permite desarrollar la lógica de interacción entre los diferentes dispositivos electrónicos dentro del sistema computador, con lenguajes de mayor abstracción, mejores herramientas de desarrollo, permitiendo generar un código con un nivel de mantenibilidad y abstracción mayor al que se lograría si todo estuviera embebido en el microcontrolador.

Uno de los componentes más usados actualmente es el bobot que persigue un enfoque genérico al igual que el proyecto USB4all y permite acompañar la extensibilidad de la placa USB4all mediante el uso de ciertos componentes propios de la arquitectura llamados drivers.

== 3. Protocolo de Comunicación ==

El protocolo está formado por un stack de protocolos que permiten abstraer al usuario de los detalles subyacentes de la arquitectura.
El objetivo final del protocolo de comunicación, es direccionar los mensajes provenientes desde la aplicación que se ejecuta en el computador, al ''usermodule'' correspondiente ejecutado en la placa USB4all.
Estos mensajes son solicitudes de ciertos servicios que los módulos exponen, por ejemplo en el caso de un dispositivo sonoro (buzzer) utilizado para una alarma, va a ser de interés poder emitir sonido (Prender el Buzzer) detener la emisón de sonido (Apagar el Buzzer), hacer sonidos cortos pasando por parámetro la cantidad de milisegundos que se desea esté prendido, etc.
Estos mensajes se tienen que codificar de alguna manera, el protocolo especifica que primero se debe indicar el comando que se desea se ejecute y luego en caso que sea necesario (como en el de los sonidos cortos) enviar los parámetros. En algunos casos va a ser necesario obtener respuestas, las cuales se codifican de forma análoga usando el mismo protocolo, enviando en lugar de un parámetro un valor de retorno.
Este protocolo es llamado ''user protocol'' y esta enfocado al usuario final, pero para que el sistema funcioné correctamente es necesario contar con otros protocolos los cuales transportan el protocolo ''user protocol''. Tal es el caso del handler manager protocol que se encarga de manejar el ruteo de los mensajes al ''user module'' correspondiente. Esto se debe a que en un momento determinado puede haber varios ''user modules'' ejecutando en la placa y el sistema debe permitir notificar al módulo del nuevo mensaje. La tarea fundamental de este protocolo es brindar los mecanismos para comunicar una aplicación con un ''user module''. Otro protocolo involucrado es el ''admin protocol'' el cual se encarga de gestionar el ciclo de vida de los ''user modules'', permitiendo poner a ejecutar un ''user module'', cerrarlo y también algunas funcionalidades como el listar los módulos presentes en la placa, cerrar todos los modulos abiertos o llevar al estado de reset al microcontrolador. Tanto el ''handler protocol'' como el ''admin protocol'' son implementados por las bibliotecas que se utilicen en el computador. Existiendo varias opciones, Java, Python o Lua. Actualmente la opción que se está manteniendo es la de Lua la cual puede estudiarse en profundidad en la sección bobot.

[[Archivo:protocolo.png|700px|Fig. 3.2 Protocolo USB4all]]

Finalmente los paquetes USB4all se trasmiten por el protocolo de comunicación que disponga el ''baseboard'', para el caso típico del ''baseboard usb4all'' se trasmite mediante USB, pero puede ser trasmitido mediante otras tecnologías utilizadas para comunicarse con un computador, como ser serial o bluetooth (entre otros).

== 4. Grabando el Firmware ==

Para grabar el firmware se necesita disponer de un programador hardware, como el picdem o el pickit, este último tiene buen soporte dentro de GNU/Linux.
Microchip distribuye un bootloader para la familia de microcontroladores 18F. Un bootloader es un programa que se utiliza para grabar y/o actualizar el firmware. En nuestro caso, va a permitr grabar el firmware del proyecto USB4all sin la necesidad de disponer de un programador por hardware, para realizar esto es necesario dejar presionado el botón de programación (botón más cercano al led) mientras se resetea la placa con el botón de reset. Esto funciona siempre y cuando el microcontrolador tenga grabado el bootloader.
Una vez que el dispositivo se encuentra en modo programación su identificador de producto cambia de 000c a 000b, esto puede verificarse utilizando el comando ''lsusb'' cuya salida se adjunta para los dos casos a continuación:

Id dispositivo USB4all
Bus 002 Device 002: ID 04d8:000c Microchip Technology, Inc.

id dispositivo Bootloader
Bus 002 Device 003: ID 04d8:000b Microchip Technology, Inc.

Dado que Microchip no distribuye microcontroladores con el bootlader previamente grabado, es necesario utilizar un programador por hardware para grabar el bootloader.
USB4all actualmente utiliza un bootloader modificado que permite actualizar el firmware programáticamente sin necesidad de presionar los botones, útil a la hora de realizar actualizaciones remotas, pero responde a los mismos comandos que el bootloader de Microchip, lo cual permite reutilizar el software ya desarrollado para interactuar con el bootloader.
Los fuentes del bootloader pueden encontrarse en el repositorio en el directorio bootloader del firmware, es un proyecto separado y una vez compilado su grabación se realiza mediante un programador por hardware como picdem o pickit.
Una vez grabado el bootloader ya '''no es necesario utilizar programadores por hardware''' y puede realizarse la grabación del firmware mediante varios programas que implementan el protocolo de grabación de firmware de microchip. Una de esas utilidades es el programa fsusb el cual puede encontrarse en [http://www.internetking.org/fsusb/] y es de código libre. Su uso se realiza de la siguiente forma:

./fsusb --program usb4all2.hex

Donde usb4all2.hex es el binario generado como resultado de compilar el proyecto. Recordar que el hardware debe estar en modo bootloader para poder recibir el firmware.

== 5 Entorno de desarrollo ==
[[Archivo:piklab.png|thumb|Fig. 5.1:Entorno de desarrollor con Piklab en GNU/Linux]][[Archivo:mplab.png|thumb|Fig. 5.2: Entorno de desarrollor con MPLab en GNU/Linux]]
El proyecto USB4all está desarrollado para el compilador C18 de Microchip, hoy día se dispone de un buen soporte del mismo para GNU/Linux puediendose descargar de [http://ww1.microchip.com/downloads/MPLAB/X_Beta/installer.html] también se dispone de un entorno de desarrollo llamado MPLab el cual también se encuentra disponible para GNU/Linux en la misma dirección.
Hace un tiempo atrás no existía compatibilidad para GNU/Linux de estas herramientas clásicas para los ambientes Windows en GNU/Linux. Debiendose recurrir a alternativas para trabajar en un ambiente GNU/Linux, una opción era Piklab. Piklab es un entorno de desarrollo para trabajar con microcontroladores PIC similar a lo que es MPLab. Era muy común utilizar la versión de C18 de windows emulada mediante wine en GNU/Linux debiendose configurar en las opciones de toolchain de PIKLab correspondientes a C18 para que apunten correctamente a los directorios donde se encuentra el compilador C18. En el repositorio puede encontrarse un proyecto piklab configurado de esta manera. Más información sobre la configuración de c18 con piklab en linux (deprecated) ver: [http://cantareus.com/2009/08/18f4550-and-18f2550-with-piklab-and-ubuntu/]
 Luego de compilar, cargar el binario generado (.hex) en la placa mediante el uso del bootloader que se incluye en el firmware. Esto puede realizarse utilizando la herramienta fsusb como se describe en la sección Grabando el Firmware.

== 6. Escribiendo un ''usermodule'' ==
Un ''usermodule'' es el bloque sobre el cual se representa una realidad y se modela utilizando la arquitectura ''USB4all'', en esta sección se presentan sus características, estructura necesaria para especificar los servicios que brinda y de que forma se anexa al ''firmwarebase''

[[Archivo:user_module.png|thumb|Fig. 6.1: Tabla de referencias a ''user modules'']]

'''6.1 Estructura de un ''usermodule:'' ''' 
Un ''usermodule'' debe cumplir con una API determinada, de esta manera es posible agregar las funcionalidades que el módulo expone, dentro del ''basefirmware''.
Las operaciones principales que se deben implementar son las encargadas de atender los eventos de:
* inicialización
* liberación de recursos
* configuración

Estas operaciones se ejecutan en determinados momentos del ciclo de vida de una aplicación USB4all, siendo la operación registrada al evento de inicialización invocada al abrir desde la aplicación el ''usermodule'' y la de liberación de recursos al cerrarlo, esto permite utilizar los recursos del microcontrolador solo cuando es necesario. La operación de configuración puede invocarse en cualquier momento para cambiar en caliente algún aspecto de configuración del hardware.
A comenzar un ''usermodule'' se debe declarar cuales van a ser las funciones que van a atender estos eventos y el nombre del módulo para ser identificado desde el computador al listar los módulos presentes en la placa.

#pragma romdata user
uTab userBuzzerModuleTable = {&UserBuzzerInit,&UserBuzzerRelease,&UserBuzzerConfigure,"buzzer"};
#pragma code

Donde user es el nombre de la sección y uTab es una estructura para almacenar las posiciones de memoria de las operaciones que exporta el módulo y su nombre. En la sección detalles de implementación en el firmware se puede comocer más sobre el significado de la instrucción #pragma romdata user, podemos por el momento asumir que sirve para almacenar la estructura uTab en un lugar conocido de memoria.

Como argumento a la operación init se recibe el número de handler asignado al módulo, este número es utilizado como argumento en otras operaciones como ser ''setHandlerReceiveFunction'' la cual recibe por parámetro el handler y un puntero a la función encargada de manejar la recepción de datos. Otra operación similar es ''getSharedBuffer'' que recibe por parámetro el ''handlerID'' del módulo y retorna un buffer por el cual el módulo puede enviar datos a la aplicación que ejecuta en el computador.
Un buen lugar para obtener éste buffer y registrar la función de recepción de datos es la operación encargada del evento de inicialización. A continuación puede verse como ejemplo la inicialización de un módulo de usuario para controlar un buzzer:

<syntaxhighlight lang="C"> void UserBuzzerInit(byte i) {
usrBuzzerHandler = i;
// add my receive function to the handler module, to be called automatically when the pc sends data to the user module
setHandlerReceiveFunction(usrBuzzerHandler,&UserBuzzerReceived);
// initialize the send buffer, used to send data to the PC
sendBufferUsrBuzzer = getSharedBuffer(usrBuzzerHandler);
}//end UserBuzzerInit </syntaxhighlight>

La función de recepción de datos es la encargada de implementar el protocolo de comunicación entre el ''usermodule'' y la aplicación, típicamente es una estructura tipo ''case'' en el que se espera por los diferentes comandos que pueden enviarse. La forma de codificar el pedido de servicios es mediante mensajes del tipo < COMANDO [argumento1] [argumento2]...[argumentoN] >. La respuesta debe ser del tipo < COMANDO [resultado1] [resultado2]..[resultadoN] >. El buffer para enviar datos al computador es obtenido como argumento de la función y el buffer para enviar datos fue obtenido previamente en la función de inicialización.

<syntaxhighlight lang="C"> void UserBuzzerReceived(byte* recBuffPtr, byte len){
byte index;
byte j;
byte userBuzzerCounter = 0;
byte tiempo;

switch(((BUZZER_DATA_PACKET*)recBuffPtr)->CMD){
case READ_VERSION:
//dataPacket._byte[1] is len
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[2] = BUZZER_MINOR_VERSION;
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[3] = BUZZER_MAJOR_VERSION;
userBuzzerCounter = 0x04;
break;

case PRENDER:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_on();
userBuzzerCounter = 0x02;
break;

case APAGAR:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_off();
userBuzzerCounter = 0x02;
break;

case BUZZER_TRIPLE:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks1 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1]);
cantTicks2 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[2]);
cantTicks3 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[3]);
boubleBeep(cantTicks1, cantTicks2, cantTicks3);
userBuzzerCounter = 0x02;
break;

case BUZZER_CORTO:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks3 = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
timeOutTicksBuzz = 1; // lo seteo timmer para que venza inmediantamente
buzzerState = DELAY;
registerT0event(0, &buzzEvent);
userBuzzerCounter = 0x02;
break;

case RESET:
Reset();
break;

default:
break;
}//end switch(s)
if(userBuzzerCounter != 0){
j = 255;
while(mUSBGenTxIsBusy() && j-->0); // pruebo un máximo de 255 veces
if(!mUSBGenTxIsBusy())
USBGenWrite2(usrBuzzerHandler, userBuzzerCounter);
}//end if
}//end UserBuzzerReceived</syntaxhighlight>

En este ejemplo se puede apreciar como se reciben los pedidos de comandos desde la aplicación que ejecuta en el computador y como se obtienen los parámetros necesarios para implementar los comandos y se devuelven los datos (en caso de ser requeridos) a la aplicación.

'''6.2 Entrada/Salida en user modules:''' 
Una de las tareas más importantes de los ''usermodules'' es la de realizar entrada/salida con diferentes periféricos electrónicos. Para realizar ésta tarea existen dos paradigmas:
 
* Polling
* Interrupciones
 
Dentro de la arquitectura USB4all existen formas de que los módulos implementen entrada/salida utilizando estos paradigmas, para el caso de pooling existe un servicio que permite registrar una función para ser ejecutada cuando el procesador este disponible.

<syntaxhighlight lang="C">
addPollingFunction(&UserBuzzerProcessIO);
</syntaxhighlight>

Existe soporte para interrupciones mediante el módulo ''DynamicISR'' el cual permite que otros módulos se registren sus rutinas de atención para ser invocadas cuando ocurren interrupciones.

<syntaxhighlight lang="C">
addISRFunction(&timmerISRFunction);
</syntaxhighlight>

Una forma que mantiene alta la cohesión del sistema es registrar módulos que se encarguen de esperar un evento en particular y brinde una interfaz para que los ''usermodules'' se registren para ser notificados de eventos generados por el componente de hardware que esta siendo modelado. Dentro de éste módulo además se pueden brindar operaciónes con mayor nivel de abstracción relacionadas con el componente a modelar. Hoy día se dispone del módulo T0service que se encarga de brindar servicio de timmers a los ''usermodules''. Al igual que el resto de los componentes funciona registrando funciones que son invocadas por el ''basefirmware''

También existen funciones para desregistrar los ''usermodules'' de las notificaciones, es conveniente realizar la desregistración en la función que implementa el evento de liberación de recursos del módulo.

Por ahora el único componente de hardware del microcontrolador modelado de esta forma es el timmer, pero puede escalarse a otros que requieran ser compartidos por más de un módulo.
Hay que recordar que la concurrencia implementada es puramente colaborativa entre ''usermodules'' por lo cual se debe tener especial cuidado al programar las funciones que atienden estos eventos ya que si se queda "colgada" va a degradar la disponibilidad de todo el sistema.

Para agregar el ''usermodule'' a la placa de entrada/salida ''usb4all baseboard'' se debe agregar al proyecto el módulo (utilizando el IDE preferido) y realizar la compilación del proyecto

== 7. Servicios de Timers - T0Service ==

T0service es un módulo encargado de brindar primitivas a los ''user modules'' para ser notificados de eventos del timmer.
La API expuesta es la siguiente:

<syntaxhighlight lang="C">
/*
Registers a new event callback, to be called t time units in the future.
This function must not be called from a callback handler.
*/
BOOL registerT0event(unsigned int t, void (*callback)(void));

/*
Registers a new event callback, to be called t time units in the future.
This function only can be called from a callback handler.
*/
BOOL registerT0eventInEvent(unsigned int t, void (*callback)(void));

/*
Unregister a event callback. No pending event(s) will invoke it.
*/
BOOL unregisterT0event(void (*callback)(void));

/*
Initialize the service
*/
void initT0Service(void);
</syntaxhighlight>

== 8. Detalles de implementación en el firmware ==

El firmware está organizado en diferentes áreas que se mapean en secciones definidas dentro de la memoria ROM correspondiente a la memoria de programa del microcontrolador, para implementar esto se necesita especificar en un archivo llamado linker script dónde están alojadas físicamente (en memoria) estas secciones.
La forma de realizar este mapeo es editando el archivo lrk asociado al proyecto.
Existe la directiva CODEPAGE que es utilizada para trabajar con las secciones de programa, permite inicializar datos, constantes, y realizar referencias a las mismas. Tiene el siguiente formato

CODEPAGE NAME=memName START=addr END=addr [PROTECTED] [FILL=fillvalue]

donde:
memName es un string ASCII utilizado para identificar una CODEPAGE.

También existe la directiva DATABANK que permite realizar un manejo similar pero sobre la memoria de datos.

La directiva #pragma
El estándar ANSI C provee a cada implementación de un método para definir constructores únicos, según sea requerido por la arquitectura del procesador a utilizar. Esto es hecho utilizando la directiva #pragma. La directiva #pragma más común en el compilador utilizado (MPLAB C18) identifica la sección de memoria para ser utilizada en el PIC18XXXX. Por ejemplo #pragma code le indica al compilador MPLAB 18 que compile el código C en la sección de programa de la memoria de programa. La sección de código está definida en el linker script asociado para cada dispositivo PIC18XXXX, especificando en que áreas de la memoria de programa pueden ser ejecutadas instrucciones.
Esta directiva puede ser insertada directamente o puede ser seguida de la dirección en el área de código del procesador destino, permitiendo tener un control total del a memoria de código.
En el contexto del USB4all esto es muy utilizado, debido a que se separan varias áreas de memoria, las más importantes son la del bootloader, y la correspondiente a los módulos de usuario, tanto para la parte de programa (module_sec) como para la información del módulo que se almacena para gestionarlo (user_sec).
Otra directiva #pragma común que se utiliza es #pragma udata, la cual se utiliza cuando se aloja memoria para variables, las variables no inicianlizadas definidas después de esta declaración van a utilizar los registros de proposito general para almacenamiento. La arquitectura del PIC18XXXX, se basa en una arquitectura harvard la que a diferencia de la von neumann almacena las variables y las instrucciones en diferentes espacios de memoria. Por tanto las áreas de memoria deben ser explicitamente identificadas.

Por más información, consultar con el manual del compilador C18 (http://www.kevin.org/frc/C18_3.0_getting_started.pdf) en la sección #pragma DIRECTIVE o SECTIONS.

De la forma que se definieron las secciones en el archivo lkr del proyecto (18f4550.lkr) se debe colocar un #pragma code module al comenzar la declaración de los procedimientos del módulo, de esa forma se almacenan en memoria de programa (code section) dentro de la sección module. Si consultamos el linker script podemos ver que está definida la sección module como un alias del área en ROM llamada module_sec

SECTION NAME=module ROM=module_sec

a su vez module_sec es definida como:

CODEPAGE NAME=module_sec START=0x40AB END=0xFFFF PROTECTED

Lo mismo se debe hacer cuando se definen las funciones que utiliza el módulo para atender eventos y su nombre (estructura uTab):

#pragma romdata user
uTab userBuzzerModuleTable = {&UserBuzzerInit,&UserBuzzerRelease,&UserBuzzerConfigure,"buzzer"};
Como vimos en el ejemplo presentado en la sección escribiendo un ''user module''.
Hay que tener cuidado de no olvidarse de los #pragmas correspondientes ya que de de lo contrario puede no dar el espacio para compilar el proyecto o no funcionar el mecanismo de callbacks.
Los archivos lkr también especifican otros conceptos, como ser tamaño de memoria de datos y registros que utiliza, como también tamaño del stack

== 9. Bobot ==
[[Archivo:bobot.png|thumb|Fig. 9.1 bobot logo]][[Archivo:componentes.png|thumb|Fig. 9.2 Arquitectura del bobot]][[Archivo:web_bobot.png|thumb|Fig. 9.3 Interacción con dispositivo USB4all de forma web]]
bobot-server (version 2) es un servicio que permite acceder a aplicaciones y usuarios interactuar con dispositivos USB4all.
Consiste en un agente altamente portable y liviano, que exporta la funcionalidad de los dispositivos USB4all presentes de una forma fácil de usar. Ofrece dos métodos de acceso,
uno optimizado para aplicaciones, basado en un socket y un protocolo fácilmente parseable, y otro optimizado para ser usado por humanos, mediante un sitio web
hosteado en el propio agente, el cual atiende en el puerto 2010. 
Bobot introduce el concepto de driver, en el cual se codifica el protocolo que utilizan los ''usermodules'', de esta forma se exponen al usuario del sistema bobot los servicios que implementan los ''usermodules'' ocultando los detalles relacionados con el protocolo de intercambio de mensajes.
Para desarrollar compatibilidad con un nuevo dispositivo electronico en la plataforma USB4all utilizando bobot para su control, primero se debe desarrollar el ''usermodule'' necesario como fue descripto en la sección: Escribiendo un ''usermodule'' luego se debe escribir el driver correspondiente a ese ''usermodule''.

El driver se escribe en Lua, debe seguir un formato preestablecido y es implementado mediante el recurso de tablas que brinda Lua. Una característica de Lua es que las funciones son miembros de primer orden, esto permite (entre otras cosas) que una función pueda ser un tipo de datos válido, pasar funciones como argumento de funciones o como retorno de las mismas y almacenarla en una tabla.
Esta capacidad permite que dentro de la tabla que representa un driver se puedan almacenar funciones asociadas para cada servicio expuesto por un módulo. Estas funciones son invocadas al solicitarse servicios desde la aplicación que utiliza la biblioteca.

Asociado a cada función se almacenan metadatos que describen los parámetros que la función recibe, su tipo, valor de retorno y valores aceptados.
Mucha de ésta información es utilizada por el bobot para generar el sitio web mencionado anteriormente, como se muestra en la figura 9.3. Este sitio describe al módulo de usuario y se puede usar como documentación y mecanismo de prueba del mismo.
A continuación se muestra un ejemplo de driver para el módulo de usuario presentado en la sección: Escribiendo un ''usermodule''. En este driver podemos ver que se exportan los siguientes servicios:
* read_version
* prender
* apagar
* buzzer_corto
* buzzer_triple

El siguiente código corresponde con la implementación de estos servicios en un driver bobot: 

<syntaxhighlight lang="lua">
local device = _G
local RD_VERSION = string.char(0x00)
local PRENDER = string.char(0x01)
local APAGAR = string.char(0x02)
local BUZZER_CORTO = string.char(0x03)
local BUZZER_TRIPLE = string.char(0x04)

api={}
api.read_version = {}
api.read_version.parameters = {} --no parameters
api.read_version.returns = {[1]={rname="version", rtype="number"}} --one return
api.read_version.call = function ()
local get_read_version = RD_VERSION
device:send(get_read_version)
local version_response = device:read(2)
local raw_val = string.byte(version_response, 2)
--print("rawval, deg_temp: ", raw_val, deg_temp)
return raw_val
end

api.prender = {}
api.prender.parameters = {} --no parameters
api.prender.returns = {} --no return
api.prender.call = function ()
local write_res, err = device:send(PRENDER)
if write_res then return true else return false end
end

api.apagar = {}
api.apagar.parameters = {} --no parameters
api.apagar.returns = {} --no return
api.apagar.call = function ()
local write_res, err = device:send(APAGAR)
if write_res then return true else return false end
end

api.buzzer_corto = {}
api.buzzer_corto.parameters = {[1]={rname="num", rtype="number"}}
api.buzzer_corto.returns = {} --no return
api.buzzer_corto.call = function (num)
local write_res, err = device:send(BUZZER_CORTO .. string.char(num))
if write_res then return true else return false end
end

api.buzzer_triple = {}
api.buzzer_triple.parameters = {[1]={rname="tiempo1", rtype="number"}, [2]={rname="tiempo2", rtype="number"}, [3]={rname="tiempo3", rtype="number"}}
api.buzzer_triple.returns = {} --no return
api.buzzer_triple.call = function (tiempo1, tiempo2, tiempo3)
local write_res, err = device:send(BUZZER_TRIPLE .. string.char(tiempo1) .. string.char(tiempo2) .. string.char(tiempo3))
if write_res then return true else return false end
end
</syntaxhighlight>

En el ejemplo puede notarse al comparar con el ''usermodule'' presentado de ejemplo, como se realiza el pasaje de parámetros entre el driver y el ''usermodule'', esto corresponde con el protocolo definido por el usuario para codificar los comandos del ''usermodule'' y el orden de los parámetros, este protocolo es llamado en la arquitectura USB4all como ''user protocol'' y responde al formato de < COMANDO [argumento1] [argumento2]...[argumentoN] > para el pedido y mensajes del tipo < COMANDO [resultado1] [resultado2]..[resultadoN] > para la respuesta.

Entre las características del bobot se encuentra la capacidad de abstraer al usuario del tipo de hardware de placa de E/S está conectada pudiendo ser placas que utilizan comunicación serial rs232c o USB u otra tecnología como también la cantidad de las mismas. En la figura 8.2 puede verse un caso posible, donde se encuentran diferentes ''usermodules'' cargados en una ''baseboard'' y ciertos drivers cargados en el bobot que van a permitir consumir los servicios expuestos por los ''usermodules''.

Como se mencionó al comienzo de la sección, bobot expone un protocolo que puede utilizarse mediante conexiones TCP/IP, este protocolo se describe de esta forma:

LIST
DESCRIBE moduleName
CALL moduleName operation param1, param2, ...,paramN
OPEN moduleName
CLOSEALL

Donde el comando:
* LIST despliega la lista de módulos disponibles en la placa por su nombre.
* DESCRIBE muestra la información de que servicios expone el módulo de nombre moduleName e información sobre los parámetros.
* CALL es utilizado para invocar los servicios expuestos por un módulo.
* OPEN se utiliza para abirir un módulo, a partir de ese momento el baseboard le asigna tiempo de CPU y recursos al ''usermodule'', actualmente esta deprecado su uso ya que bobot se encarga de abrirlos de forma automática ante la primer invocación.
* CLOSEALL cierra todos los módulos abiertos en la placa, llevandola a un estado conocido.

Puede descargarse bobot desde el git del proyecto butiá en sourceforge.

== ANEXO 1 ==

En el enlace [http://sourceforge.net/p/usb4all/code/ci/6ecc2581f50519fe427f7a3947136c2a03108841/tree/firmware/u4a2/user/usr_buzzer.c] y [http://sourceforge.net/p/usb4all/code/ci/6ecc2581f50519fe427f7a3947136c2a03108841/tree/firmware/u4a2/user/usr_buzzer.h] puede descargarse el código completo del ejemplo presentado como caso de estudio. El mismo puede usarse como esqueleto para desarrollar otros ''user modules''

----

El proyecto USB4all se encuentra disponible bajo licencia GNU/GPL v2 en el [http://sourceforge.net/projects/usb4all/ repositorio sorceforge] 
Este proyecto surge originalmente como un trabajo de [http://www.fing.edu.uy/inco/grupos/mina/pGrado/pgusb tesis de grado] en Ingeniería en Computación de Aguirre, Fernandez y Grossy.

Usb4all

2011-10-31T12:53:44Z

Edgardo: /* 3. Protocolo de Comunicación */

== 1. Motivación ==

La motivación de este proyecto se centra en lograr de una manera sencilla, la comunicación entre un sistema computador y un conjunto de dispositivos electrónicos no necesariamente pensados para interactuar con una computadora.
Durante muchos años la única forma de interactuar con dispositivos externos desde a un computador personal (Personal Computer) (PC) fueron los puertos seriales y paralelos, esto llevo a que se utilizaran ampliamente en multiplicidad de dispositivos. Sus principales carácteristicas son su simplicidad de manejo vía software y facilidad de inclusión en distintos dispositivos. En la última década han aparecido nuevos medios o canales de comunicación, tales como Bluetooth, Fidelidad Inalámbrica (Wireless Fidelity) (WiFi), FireWire, Bus Universal en Serie (Universal Serial Bus) (USB), etc. Estos permitieron mejorar las velocidades de comunicación y calidad de datos y lentamente tornaron a los puertos paralelos y seriales en obsoletos, hasta llegar al día de hoy en que se obtienen sólo de manera opcional en los nuevos PC.
Dentro de todas estas nuevas tecnologías que aparecieron la que tuvo mayor aceptación y difusión entre los usuarios fue el USB, debido a su facilidad y versatilidad de escenarios de uso. Esta simplicidad desde el punto de vista del usuario de los dispositivos USB tiene como contrapartida una mayor complejidad para los desarrolladores de software y hardware, lo cual es un gran problema al momento de interactuar con dispositivos electrónicos.
Frente a estas adversidades que presenta el entorno actual aparece la necesidad de buscar una forma de reducir el grado de complejidad y conocimientos necesarios para poder desarrollar
software que utilice la tecnología USB. Al mismo tiempo, se requiere una plataforma base que incorpore componentes de hardware reutilizables y que en conjunto formen una solución genérica
para la comunicación con dispositivos electrónicos diversos.
En el contexto de lo antedicho aparecen un conjunto de desafíos como son el desarrollo de controladores (drivers) y construcción de piezas de hardware que brinde una solución genérica
reutilizable, desplazando el manejo de los casos particulares a componentes específicos. Esto proporciona el beneficio de evitar que cada vez que se necesite conectar un nuevo dispositivo,
se comience desde cero. A su vez permite recuperar y potenciar la característica de facilidad de manejo que poseían los puertos seriales y paralelos, explotando todas las capacidades brindadas
por USB.

== 2. Arquitectura (Firmware/Hardware)==

La arquitectura esta compuesta por diferentes componentes, los cuales van a permitir el funcionamiento del sistema desde lo relativo al hardware como las abstracciones necesarias para manejarlo mediante software. 
Los componentes principales son:

'''2.1 USB4all ''Baseboard'''''

[[Archivo:usb4all2.png|thumb|Fig.2.1.1: USB4all Baseboard 2.0]]
Es una placa de entrada/salida(E/S) configurable que se conecta por USB con un sistema computador. El proyecto USB4all es mucho más que una placa de E/S, en sí es una forma de modelar sistemas embebidos, siendo la placa de E/S un componente que fue necesario construir para desarrollar la solución completa. Para la construcción de esta placa se utilizó un microcontrolador PIC18F4550 de Microchip. Entre las características más destacadas en lo que concierne al proyecto se encuentra el soporte completo del estándar USB, pudiéndose utilizar varias de sus características, como ser diferentes tipos de transferencias y varios canales de comunicación (endpoints).

'''2.2 USB4all ''base firmware'''''

Es el firmware más estático, brinda servicios a los usermodules para que puedan utilizar los recursos presentes en la baseboard (timmers, puerto USB, conversores A/D, etc) además de brindar las primitivas para el intercambio de mensajes entre el computador y el usermodule y realiza la gestión de los ''usermodules''. Establece las bases para que los usermodules sean independientes del protocolo de comunicación computador/placa y de los detalles de hardware del microcontrolador utilizado. A su vez oferce un entorno de ejecución concurrente que permite instanciar de forma dinámica varios ''usermodules''.

'''2.3 USB4all ''usermodule'''''
Son los componentes intercambiables del sistema que permiten encapsular la lógica de un dispositivo especifico y su protocolo de comunicación con las aplicaciones de usuario. Permite al usuario dar rápidamente soporte a un nuevo dispositivo de forma genérica, expandiendo de ésta manera las funcionalidades del USB4all ''basefirmware''. Los ''user modules'' son los bloques principales sobre los que se construye la arquitectura USB4all. Exponen una API uniforme que es utilizada a modo de callbacks por el ''base firmware'' y también exponen los servicios que brindan los dispositivos. Es recomendable modelar cada uno de los dispositivos electrónicos conectados a la ''baseboard'' como un ''usermodule'' donde los servicios a exponer se mapean con las características del mismo, como ejemplo en el caso de un motor, sería esperable que expusiera servicios para moverse, cambiar la velocidad y el sentido.

Del lado del sistema computador se dispone de diferentes formas de interacción: Todas ellas implementan el protocolo USB4all, su objetivo es abstraer al usuario del mismo brindando una forma sencilla de utilizar el sistema, existiendo soporte para diferentes lenguajes de programación. El objetivo principal de las bibliotecas utilizadas en el computador son las de permitir utilizar los servicios de los ''usermodules''. Esta forma de trabajo permite desarrollar la lógica de interacción entre los diferentes dispositivos electrónicos dentro del sistema computador, con lenguajes de mayor abstracción, mejores herramientas de desarrollo, permitiendo generar un código con un nivel de mantenibilidad y abstracción mayor al que se lograría si todo estuviera embebido en el microcontrolador.

Uno de los componentes más usados actualmente es el bobot que persigue un enfoque genérico al igual que el proyecto USB4all y permite acompañar la extensibilidad de la placa USB4all mediante el uso de ciertos componentes propios de la arquitectura llamados drivers.

== 3. Protocolo de Comunicación ==

El protocolo está formado por un stack de protocolos que permiten abstraer al usuario de los detalles subyacentes de la arquitectura.
El objetivo final del protocolo de comunicación, es direccionar los mensajes provenientes desde la aplicación que se ejecuta en el computador, al ''usermodule'' correspondiente ejecutado en la placa USB4all.
Estos mensajes son solicitudes de ciertos servicios que los módulos exponen, por ejemplo en el caso de un dispositivo sonoro (buzzer) utilizado para una alarma, va a ser de interés poder emitir sonido (Prender el Buzzer) detener la emisón de sonido (Apagar el Buzzer), hacer sonidos cortos pasando por parámetro la cantidad de milisegundos que se desea esté prendido, etc.
Estos mensajes se tienen que codificar de alguna manera, el protocolo especifica que primero se debe indicar el comando que se desea se ejecute y luego en caso que sea necesario (como en el de los sonidos cortos) enviar los parámetros. En algunos casos va a ser necesario obtener respuestas, las cuales se codifican de forma análoga usando el mismo protocolo, enviando en lugar de un parámetro un valor de retorno.
Este protocolo es llamado ''user protocol'' y esta enfocado al usuario final, pero para que el sistema funcioné correctamente es necesario contar con otros protocolos los cuales transportan el protocolo ''user protocol''. Tal es el caso del handler manager protocol que se encarga de manejar el ruteo de los mensajes al ''user module'' correspondiente. Esto se debe a que en un momento determinado puede haber varios ''user modules'' ejecutando en la placa y el sistema debe permitir notificar al módulo del nuevo mensaje. La tarea fundamental de este protocolo es brindar los mecanismos para comunicar una aplicación con un ''user module''. Otro protocolo involucrado es el ''admin protocol'' el cual se encarga de gestionar el ciclo de vida de los ''user modules'', permitiendo poner a ejecutar un ''user module'', cerrarlo y también algunas funcionalidades como el listar los módulos presentes en la placa, cerrar todos los modulos abiertos o llevar al estado de reset al microcontrolador. Tanto el ''handler protocol'' como el ''admin protocol'' son implementados por las bibliotecas que se utilicen en el computador. Existiendo varias opciones, Java, Python o Lua. Actualmente la opción que se está manteniendo es la de Lua la cual puede estudiarse en profundidad en la sección bobot.

[[Archivo:protocolo.png|700px|Fig. 3.2 Protocolo USB4all]]

Finalmente los paquetes USB4all se trasmiten por el protocolo de comunicación que disponga el ''baseboard'', para el caso típico del ''baseboard usb4all'' se trasmite mediante USB, pero puede ser trasmitido mediante otras tecnologías utilizadas para comunicarse con un computador, como ser serial o bluetooth (entre otros).

== 4. Grabando el Firmware ==

Para grabar el firmware se necesita disponer de un programador, como el picdem o el pickit, este último tiene buen soporte dentro de GNU/Linux.
Microchip disrtibuye un bootloader para la familia de microcontroladores 18F. Un bootloader es unprograma que se utiliza para grabar otro. En nuestro caso, va a permitr grabar el firmware del proyecto USB4all sin la necesidad de disponer de un programador por hardware, para realizar esto es necesario dejar prescionado el botón de programación (botón más cercano al led) mientras se resetea la placa con el botón de reset. Esto funciona siempre y cuando el microcontrolador tenga grabado el bootloader.
Una vez que el dispositivo se encuentra en modo programación su identificador de producto cambia de 000c a 000b, esto puede verificarse utilizando el comando ''lsusb'' cuya salida se adjunta para los dos casos a continuación:

Id dispositivo USB4all
Bus 002 Device 002: ID 04d8:000c Microchip Technology, Inc.

id dispositivo Bootloader
Bus 002 Device 003: ID 04d8:000b Microchip Technology, Inc.

Dado que Microchip no distribuye microcontroladores con el bootlader previamente grabado, es necesario utilizar un programador por hardware para grabar el bootloader.
USB4all acutalmente utiliza un bootloader modificado que permite actualizar el firmware programáticamente sin necesidad de prescionar los botones, útil a la hora de realizar actualizaciones remotas, pero responde a los mismos comandos que el bootloader de Microchip, lo cual permite reutilizar el software ya desarrollado para interactuar con el bootloader.
Los fuentes del bootloader pueden encontrarse en el repositorio en el directorio bootloader del firmware, es un proyecto separado y una vez compilado su grabación se realiza mediante un programador por hardware como picdem o pickit.
Una vez grabado el bootloader ya '''no es necesario utilizar programadores por hardware''' y puede realizarse la grabación del firmware mediante varios programas que implementan el protocolo de grabación de firmware de microchip. Una de esas utilidades es el programa fsusb el cual puede encontrarse en [http://www.internetking.org/fsusb/] y es de código libre. Su uso se realiza de la siguiente forma:

./fsusb --program usb4all2.hex

Donde usb4all2.hex es el binario generado como resultado de compilar el proyecto. Recordar que el hardware debe de estar en modo bootloader para poder recibir el firmware.

== 5 Entorno de desarrollo ==
[[Archivo:piklab.png|thumb|Fig. 5.1:Entorno de desarrollor con Piklab en GNU/Linux]][[Archivo:mplab.png|thumb|Fig. 5.2: Entorno de desarrollor con MPLab en GNU/Linux]]
El proyecto USB4all está desarrollado para el compilador C18 de Microchip, hoy día se dispone de un buen soporte del mismo para GNU/Linux puediendose descargar de [http://ww1.microchip.com/downloads/MPLAB/X_Beta/installer.html] también se dispone de un entorno de desarrollo llamado MPLab el cual también se encuentra disponible para GNU/Linux en la misma dirección.
Hace un tiempo atrás no existía compatibilidad para GNU/Linux de estas herramientas clásicas para los ambientes Windows en GNU/Linux. Debiendose recurrir a alternativas para trabajar en un ambiente GNU/Linux, una opción era Piklab. Piklab es un entorno de desarrollo para trabajar con microcontroladores PIC similar a lo que es MPLab. Era muy común utilizar la versión de C18 de windows emulada mediante wine en GNU/Linux debiendose configurar en las opciones de toolchain de PIKLab correspondientes a C18 para que apunten correctamente a los directorios donde se encuentra el compilador C18. En el repositorio puede encontrarse un proyecto piklab configurado de esta manera. Más información sobre la configuración de c18 con piklab en linux (deprecated) ver: [http://cantareus.com/2009/08/18f4550-and-18f2550-with-piklab-and-ubuntu/]
 Luego de compilar, cargar el binario generado (.hex) en la placa mediante el uso del bootloader que se incluye en el firmware. Esto puede realizarse utilizando la herramienta fsusb como se describe en la sección Grabando el Firmware.

== 6. Escribiendo un ''usermodule'' ==
Un ''usermodule'' es el bloque sobre el cual se representa una realidad y se modela utilizando la arquitectura ''USB4all'', en esta sección se presentan sus características, estructura necesaria para especificar los servicios que brinda y de que forma se anexa al ''firmwarebase''

[[Archivo:user_module.png|thumb|Fig. 6.1: Tabla de referencias a ''user modules'']]

'''6.1 Estructura de un ''usermodule:'' ''' 
Un ''usermodule'' debe cumplir con una API determinada, de esta manera es posible agregar las funcionalidades que el módulo expone, dentro del ''basefirmware''.
Las operaciones principales que se deben implementar son las encargadas de atender los eventos de:
* inicialización
* liberación de recursos
* configuración

Estas operaciones se ejecutan en determinados momentos del ciclo de vida de una aplicación USB4all, siendo la operación registrada al evento de inicialización invocada al abrir desde la aplicación el ''usermodule'' y la de liberación de recursos al cerrarlo, esto permite utilizar los recursos del microcontrolador solo cuando es necesario. La operación de configuración puede invocarse en cualquier momento para cambiar en caliente algún aspecto de configuración del hardware.
A comenzar un ''usermodule'' se debe declarar cuales van a ser las funciones que van a atender estos eventos y el nombre del módulo para ser identificado desde el computador al listar los módulos presentes en la placa.

#pragma romdata user
uTab userBuzzerModuleTable = {&UserBuzzerInit,&UserBuzzerRelease,&UserBuzzerConfigure,"buzzer"};
#pragma code

Donde user es el nombre de la sección y uTab es una estructura para almacenar las posiciones de memoria de las operaciones que exporta el módulo y su nombre. En la sección detalles de implementación en el firmware se puede comocer más sobre el significado de la instrucción #pragma romdata user, podemos por el momento asumir que sirve para almacenar la estructura uTab en un lugar conocido de memoria.

Como argumento a la operación init se recibe el número de handler asignado al módulo, este número es utilizado como argumento en otras operaciones como ser ''setHandlerReceiveFunction'' la cual recibe por parámetro el handler y un puntero a la función encargada de manejar la recepción de datos. Otra operación similar es ''getSharedBuffer'' que recibe por parámetro el ''handlerID'' del módulo y retorna un buffer por el cual el módulo puede enviar datos a la aplicación que ejecuta en el computador.
Un buen lugar para obtener éste buffer y registrar la función de recepción de datos es la operación encargada del evento de inicialización. A continuación puede verse como ejemplo la inicialización de un módulo de usuario para controlar un buzzer:

<syntaxhighlight lang="C"> void UserBuzzerInit(byte i) {
usrBuzzerHandler = i;
// add my receive function to the handler module, to be called automatically when the pc sends data to the user module
setHandlerReceiveFunction(usrBuzzerHandler,&UserBuzzerReceived);
// initialize the send buffer, used to send data to the PC
sendBufferUsrBuzzer = getSharedBuffer(usrBuzzerHandler);
}//end UserBuzzerInit </syntaxhighlight>

La función de recepción de datos es la encargada de implementar el protocolo de comunicación entre el ''usermodule'' y la aplicación, típicamente es una estructura tipo ''case'' en el que se espera por los diferentes comandos que pueden enviarse. La forma de codificar el pedido de servicios es mediante mensajes del tipo < COMANDO [argumento1] [argumento2]...[argumentoN] >. La respuesta debe ser del tipo < COMANDO [resultado1] [resultado2]..[resultadoN] >. El buffer para enviar datos al computador es obtenido como argumento de la función y el buffer para enviar datos fue obtenido previamente en la función de inicialización.

<syntaxhighlight lang="C"> void UserBuzzerReceived(byte* recBuffPtr, byte len){
byte index;
byte j;
byte userBuzzerCounter = 0;
byte tiempo;

switch(((BUZZER_DATA_PACKET*)recBuffPtr)->CMD){
case READ_VERSION:
//dataPacket._byte[1] is len
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[2] = BUZZER_MINOR_VERSION;
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[3] = BUZZER_MAJOR_VERSION;
userBuzzerCounter = 0x04;
break;

case PRENDER:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_on();
userBuzzerCounter = 0x02;
break;

case APAGAR:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_off();
userBuzzerCounter = 0x02;
break;

case BUZZER_TRIPLE:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks1 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1]);
cantTicks2 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[2]);
cantTicks3 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[3]);
boubleBeep(cantTicks1, cantTicks2, cantTicks3);
userBuzzerCounter = 0x02;
break;

case BUZZER_CORTO:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks3 = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
timeOutTicksBuzz = 1; // lo seteo timmer para que venza inmediantamente
buzzerState = DELAY;
registerT0event(0, &buzzEvent);
userBuzzerCounter = 0x02;
break;

case RESET:
Reset();
break;

default:
break;
}//end switch(s)
if(userBuzzerCounter != 0){
j = 255;
while(mUSBGenTxIsBusy() && j-->0); // pruebo un máximo de 255 veces
if(!mUSBGenTxIsBusy())
USBGenWrite2(usrBuzzerHandler, userBuzzerCounter);
}//end if
}//end UserBuzzerReceived</syntaxhighlight>

En este ejemplo se puede apreciar como se reciben los pedidos de comandos desde la aplicación que ejecuta en el computador y como se obtienen los parámetros necesarios para implementar los comandos y se devuelven los datos (en caso de ser requeridos) a la aplicación.

'''6.2 Entrada/Salida en user modules:''' 
Una de las tareas más importantes de los ''usermodules'' es la de realizar entrada/salida con diferentes periféricos electrónicos. Para realizar ésta tarea existen dos paradigmas:
 
* Polling
* Interrupciones
 
Dentro de la arquitectura USB4all existen formas de que los módulos implementen entrada/salida utilizando estos paradigmas, para el caso de pooling existe un servicio que permite registrar una función para ser ejecutada cuando el procesador este disponible.

<syntaxhighlight lang="C">
addPollingFunction(&UserBuzzerProcessIO);
</syntaxhighlight>

Existe soporte para interrupciones mediante el módulo ''DynamicISR'' el cual permite que otros módulos se registren sus rutinas de atención para ser invocadas cuando ocurren interrupciones.

<syntaxhighlight lang="C">
addISRFunction(&timmerISRFunction);
</syntaxhighlight>

Una forma que mantiene alta la cohesión del sistema es registrar módulos que se encarguen de esperar un evento en particular y brinde una interfaz para que los ''usermodules'' se registren para ser notificados de eventos generados por el componente de hardware que esta siendo modelado. Dentro de éste módulo además se pueden brindar operaciónes con mayor nivel de abstracción relacionadas con el componente a modelar. Hoy día se dispone del módulo T0service que se encarga de brindar servicio de timmers a los ''usermodules''. Al igual que el resto de los componentes funciona registrando funciones que son invocadas por el ''basefirmware''

También existen funciones para desregistrar los ''usermodules'' de las notificaciones, es conveniente realizar la desregistración en la función que implementa el evento de liberación de recursos del módulo.

Por ahora el único componente de hardware del microcontrolador modelado de esta forma es el timmer, pero puede escalarse a otros que requieran ser compartidos por más de un módulo.
Hay que recordar que la concurrencia implementada es puramente colaborativa entre ''usermodules'' por lo cual se debe tener especial cuidado al programar las funciones que atienden estos eventos ya que si se queda "colgada" va a degradar la disponibilidad de todo el sistema.

Para agregar el ''usermodule'' a la placa de entrada/salida ''usb4all baseboard'' se debe agregar al proyecto el módulo (utilizando el IDE preferido) y realizar la compilación del proyecto

== 7. Servicios de Timers - T0Service ==

T0service es un módulo encargado de brindar primitivas a los ''user modules'' para ser notificados de eventos del timmer.
La API expuesta es la siguiente:

<syntaxhighlight lang="C">
/*
Registers a new event callback, to be called t time units in the future.
This function must not be called from a callback handler.
*/
BOOL registerT0event(unsigned int t, void (*callback)(void));

/*
Registers a new event callback, to be called t time units in the future.
This function only can be called from a callback handler.
*/
BOOL registerT0eventInEvent(unsigned int t, void (*callback)(void));

/*
Unregister a event callback. No pending event(s) will invoke it.
*/
BOOL unregisterT0event(void (*callback)(void));

/*
Initialize the service
*/
void initT0Service(void);
</syntaxhighlight>

== 8. Detalles de implementación en el firmware ==

El firmware está organizado en diferentes áreas que se mapean en secciones definidas dentro de la memoria ROM correspondiente a la memoria de programa del microcontrolador, para implementar esto se necesita especificar en un archivo llamado linker script dónde están alojadas físicamente (en memoria) estas secciones.
La forma de realizar este mapeo es editando el archivo lrk asociado al proyecto.
Existe la directiva CODEPAGE que es utilizada para trabajar con las secciones de programa, permite inicializar datos, constantes, y realizar referencias a las mismas. Tiene el siguiente formato

CODEPAGE NAME=memName START=addr END=addr [PROTECTED] [FILL=fillvalue]

donde:
memName es un string ASCII utilizado para identificar una CODEPAGE.

También existe la directiva DATABANK que permite realizar un manejo similar pero sobre la memoria de datos.

La directiva #pragma
El estándar ANSI C provee a cada implementación de un método para definir constructores únicos, según sea requerido por la arquitectura del procesador a utilizar. Esto es hecho utilizando la directiva #pragma. La directiva #pragma más común en el compilador utilizado (MPLAB C18) identifica la sección de memoria para ser utilizada en el PIC18XXXX. Por ejemplo #pragma code le indica al compilador MPLAB 18 que compile el código C en la sección de programa de la memoria de programa. La sección de código está definida en el linker script asociado para cada dispositivo PIC18XXXX, especificando en que áreas de la memoria de programa pueden ser ejecutadas instrucciones.
Esta directiva puede ser insertada directamente o puede ser seguida de la dirección en el área de código del procesador destino, permitiendo tener un control total del a memoria de código.
En el contexto del USB4all esto es muy utilizado, debido a que se separan varias áreas de memoria, las más importantes son la del bootloader, y la correspondiente a los módulos de usuario, tanto para la parte de programa (module_sec) como para la información del módulo que se almacena para gestionarlo (user_sec).
Otra directiva #pragma común que se utiliza es #pragma udata, la cual se utiliza cuando se aloja memoria para variables, las variables no inicianlizadas definidas después de esta declaración van a utilizar los registros de proposito general para almacenamiento. La arquitectura del PIC18XXXX, se basa en una arquitectura harvard la que a diferencia de la von neumann almacena las variables y las instrucciones en diferentes espacios de memoria. Por tanto las áreas de memoria deben ser explicitamente identificadas.

Por más información, consultar con el manual del compilador C18 (http://www.kevin.org/frc/C18_3.0_getting_started.pdf) en la sección #pragma DIRECTIVE o SECTIONS.

De la forma que se definieron las secciones en el archivo lkr del proyecto (18f4550.lkr) se debe colocar un #pragma code module al comenzar la declaración de los procedimientos del módulo, de esa forma se almacenan en memoria de programa (code section) dentro de la sección module. Si consultamos el linker script podemos ver que está definida la sección module como un alias del área en ROM llamada module_sec

SECTION NAME=module ROM=module_sec

a su vez module_sec es definida como:

CODEPAGE NAME=module_sec START=0x40AB END=0xFFFF PROTECTED

Lo mismo se debe hacer cuando se definen las funciones que utiliza el módulo para atender eventos y su nombre (estructura uTab):

#pragma romdata user
uTab userBuzzerModuleTable = {&UserBuzzerInit,&UserBuzzerRelease,&UserBuzzerConfigure,"buzzer"};
Como vimos en el ejemplo presentado en la sección escribiendo un ''user module''.
Hay que tener cuidado de no olvidarse de los #pragmas correspondientes ya que de de lo contrario puede no dar el espacio para compilar el proyecto o no funcionar el mecanismo de callbacks.
Los archivos lkr también especifican otros conceptos, como ser tamaño de memoria de datos y registros que utiliza, como también tamaño del stack

== 9. Bobot ==
[[Archivo:bobot.png|thumb|Fig. 9.1 bobot logo]][[Archivo:componentes.png|thumb|Fig. 9.2 Arquitectura del bobot]][[Archivo:web_bobot.png|thumb|Fig. 9.3 Interacción con dispositivo USB4all de forma web]]
bobot-server (version 2) es un servicio que permite acceder a aplicaciones y usuarios interactuar con dispositivos USB4all.
Consiste en un agente altamente portable y liviano, que exporta la funcionalidad de los dispositivos USB4all presentes de una forma fácil de usar. Ofrece dos métodos de acceso,
uno optimizado para aplicaciones, basado en un socket y un protocolo fácilmente parseable, y otro optimizado para ser usado por humanos, mediante un sitio web
hosteado en el propio agente, el cual atiende en el puerto 2010. 
Bobot introduce el concepto de driver, en el cual se codifica el protocolo que utilizan los ''usermodules'', de esta forma se exponen al usuario del sistema bobot los servicios que implementan los ''usermodules'' ocultando los detalles relacionados con el protocolo de intercambio de mensajes.
Para desarrollar compatibilidad con un nuevo dispositivo electronico en la plataforma USB4all utilizando bobot para su control, primero se debe desarrollar el ''usermodule'' necesario como fue descripto en la sección: Escribiendo un ''usermodule'' luego se debe escribir el driver correspondiente a ese ''usermodule''.

El driver se escribe en Lua, debe seguir un formato preestablecido y es implementado mediante el recurso de tablas que brinda Lua. Una característica de Lua es que las funciones son miembros de primer orden, esto permite (entre otras cosas) que una función pueda ser un tipo de datos válido, pasar funciones como argumento de funciones o como retorno de las mismas y almacenarla en una tabla.
Esta capacidad permite que dentro de la tabla que representa un driver se puedan almacenar funciones asociadas para cada servicio expuesto por un módulo. Estas funciones son invocadas al solicitarse servicios desde la aplicación que utiliza la biblioteca.

Asociado a cada función se almacenan metadatos que describen los parámetros que la función recibe, su tipo, valor de retorno y valores aceptados.
Mucha de ésta información es utilizada por el bobot para generar el sitio web mencionado anteriormente, como se muestra en la figura 9.3. Este sitio describe al módulo de usuario y se puede usar como documentación y mecanismo de prueba del mismo.
A continuación se muestra un ejemplo de driver para el módulo de usuario presentado en la sección: Escribiendo un ''usermodule''. En este driver podemos ver que se exportan los siguientes servicios:
* read_version
* prender
* apagar
* buzzer_corto
* buzzer_triple

El siguiente código corresponde con la implementación de estos servicios en un driver bobot: 

<syntaxhighlight lang="lua">
local device = _G
local RD_VERSION = string.char(0x00)
local PRENDER = string.char(0x01)
local APAGAR = string.char(0x02)
local BUZZER_CORTO = string.char(0x03)
local BUZZER_TRIPLE = string.char(0x04)

api={}
api.read_version = {}
api.read_version.parameters = {} --no parameters
api.read_version.returns = {[1]={rname="version", rtype="number"}} --one return
api.read_version.call = function ()
local get_read_version = RD_VERSION
device:send(get_read_version)
local version_response = device:read(2)
local raw_val = string.byte(version_response, 2)
--print("rawval, deg_temp: ", raw_val, deg_temp)
return raw_val
end

api.prender = {}
api.prender.parameters = {} --no parameters
api.prender.returns = {} --no return
api.prender.call = function ()
local write_res, err = device:send(PRENDER)
if write_res then return true else return false end
end

api.apagar = {}
api.apagar.parameters = {} --no parameters
api.apagar.returns = {} --no return
api.apagar.call = function ()
local write_res, err = device:send(APAGAR)
if write_res then return true else return false end
end

api.buzzer_corto = {}
api.buzzer_corto.parameters = {[1]={rname="num", rtype="number"}}
api.buzzer_corto.returns = {} --no return
api.buzzer_corto.call = function (num)
local write_res, err = device:send(BUZZER_CORTO .. string.char(num))
if write_res then return true else return false end
end

api.buzzer_triple = {}
api.buzzer_triple.parameters = {[1]={rname="tiempo1", rtype="number"}, [2]={rname="tiempo2", rtype="number"}, [3]={rname="tiempo3", rtype="number"}}
api.buzzer_triple.returns = {} --no return
api.buzzer_triple.call = function (tiempo1, tiempo2, tiempo3)
local write_res, err = device:send(BUZZER_TRIPLE .. string.char(tiempo1) .. string.char(tiempo2) .. string.char(tiempo3))
if write_res then return true else return false end
end
</syntaxhighlight>

En el ejemplo puede notarse al comparar con el ''usermodule'' presentado de ejemplo, como se realiza el pasaje de parámetros entre el driver y el ''usermodule'', esto corresponde con el protocolo definido por el usuario para codificar los comandos del ''usermodule'' y el orden de los parámetros, este protocolo es llamado en la arquitectura USB4all como ''user protocol'' y responde al formato de < COMANDO [argumento1] [argumento2]...[argumentoN] > para el pedido y mensajes del tipo < COMANDO [resultado1] [resultado2]..[resultadoN] > para la respuesta.

Entre las características del bobot se encuentra la capacidad de abstraer al usuario del tipo de hardware de placa de E/S está conectada pudiendo ser placas que utilizan comunicación serial rs232c o USB u otra tecnología como también la cantidad de las mismas. En la figura 8.2 puede verse un caso posible, donde se encuentran diferentes ''usermodules'' cargados en una ''baseboard'' y ciertos drivers cargados en el bobot que van a permitir consumir los servicios expuestos por los ''usermodules''.

Como se mencionó al comienzo de la sección, bobot expone un protocolo que puede utilizarse mediante conexiones TCP/IP, este protocolo se describe de esta forma:

LIST
DESCRIBE moduleName
CALL moduleName operation param1, param2, ...,paramN
OPEN moduleName
CLOSEALL

Donde el comando:
* LIST despliega la lista de módulos disponibles en la placa por su nombre.
* DESCRIBE muestra la información de que servicios expone el módulo de nombre moduleName e información sobre los parámetros.
* CALL es utilizado para invocar los servicios expuestos por un módulo.
* OPEN se utiliza para abirir un módulo, a partir de ese momento el baseboard le asigna tiempo de CPU y recursos al ''usermodule'', actualmente esta deprecado su uso ya que bobot se encarga de abrirlos de forma automática ante la primer invocación.
* CLOSEALL cierra todos los módulos abiertos en la placa, llevandola a un estado conocido.

Puede descargarse bobot desde el git del proyecto butiá en sourceforge.

== ANEXO 1 ==

En el enlace [http://sourceforge.net/p/usb4all/code/ci/6ecc2581f50519fe427f7a3947136c2a03108841/tree/firmware/u4a2/user/usr_buzzer.c] y [http://sourceforge.net/p/usb4all/code/ci/6ecc2581f50519fe427f7a3947136c2a03108841/tree/firmware/u4a2/user/usr_buzzer.h] puede descargarse el código completo del ejemplo presentado como caso de estudio. El mismo puede usarse como esqueleto para desarrollar otros ''user modules''

----

El proyecto USB4all se encuentra disponible bajo licencia GNU/GPL v2 en el [http://sourceforge.net/projects/usb4all/ repositorio sorceforge] 
Este proyecto surge originalmente como un trabajo de [http://www.fing.edu.uy/inco/grupos/mina/pGrado/pgusb tesis de grado] en Ingeniería en Computación de Aguirre, Fernandez y Grossy.

Usb4all

2011-10-31T12:33:32Z

Edgardo: /* 3. Protocolo de Comunicación */

== 1. Motivación ==

La motivación de este proyecto se centra en lograr de una manera sencilla, la comunicación entre un sistema computador y un conjunto de dispositivos electrónicos no necesariamente pensados para interactuar con una computadora.
Durante muchos años la única forma de interactuar con dispositivos externos desde a un computador personal (Personal Computer) (PC) fueron los puertos seriales y paralelos, esto llevo a que se utilizaran ampliamente en multiplicidad de dispositivos. Sus principales carácteristicas son su simplicidad de manejo vía software y facilidad de inclusión en distintos dispositivos. En la última década han aparecido nuevos medios o canales de comunicación, tales como Bluetooth, Fidelidad Inalámbrica (Wireless Fidelity) (WiFi), FireWire, Bus Universal en Serie (Universal Serial Bus) (USB), etc. Estos permitieron mejorar las velocidades de comunicación y calidad de datos y lentamente tornaron a los puertos paralelos y seriales en obsoletos, hasta llegar al día de hoy en que se obtienen sólo de manera opcional en los nuevos PC.
Dentro de todas estas nuevas tecnologías que aparecieron la que tuvo mayor aceptación y difusión entre los usuarios fue el USB, debido a su facilidad y versatilidad de escenarios de uso. Esta simplicidad desde el punto de vista del usuario de los dispositivos USB tiene como contrapartida una mayor complejidad para los desarrolladores de software y hardware, lo cual es un gran problema al momento de interactuar con dispositivos electrónicos.
Frente a estas adversidades que presenta el entorno actual aparece la necesidad de buscar una forma de reducir el grado de complejidad y conocimientos necesarios para poder desarrollar
software que utilice la tecnología USB. Al mismo tiempo, se requiere una plataforma base que incorpore componentes de hardware reutilizables y que en conjunto formen una solución genérica
para la comunicación con dispositivos electrónicos diversos.
En el contexto de lo antedicho aparecen un conjunto de desafíos como son el desarrollo de controladores (drivers) y construcción de piezas de hardware que brinde una solución genérica
reutilizable, desplazando el manejo de los casos particulares a componentes específicos. Esto proporciona el beneficio de evitar que cada vez que se necesite conectar un nuevo dispositivo,
se comience desde cero. A su vez permite recuperar y potenciar la característica de facilidad de manejo que poseían los puertos seriales y paralelos, explotando todas las capacidades brindadas
por USB.

== 2. Arquitectura (Firmware/Hardware)==

La arquitectura esta compuesta por diferentes componentes, los cuales van a permitir el funcionamiento del sistema desde lo relativo al hardware como las abstracciones necesarias para manejarlo mediante software. 
Los componentes principales son:

'''2.1 USB4all ''Baseboard'''''

[[Archivo:usb4all2.png|thumb|Fig.2.1.1: USB4all Baseboard 2.0]]
Es una placa de entrada/salida(E/S) configurable que se conecta por USB con un sistema computador. El proyecto USB4all es mucho más que una placa de E/S, en sí es una forma de modelar sistemas embebidos, siendo la placa de E/S un componente que fue necesario construir para desarrollar la solución completa. Para la construcción de esta placa se utilizó un microcontrolador PIC18F4550 de Microchip. Entre las características más destacadas en lo que concierne al proyecto se encuentra el soporte completo del estándar USB, pudiéndose utilizar varias de sus características, como ser diferentes tipos de transferencias y varios canales de comunicación (endpoints).

'''2.2 USB4all ''base firmware'''''

Es el firmware más estático, brinda servicios a los usermodules para que puedan utilizar los recursos presentes en la baseboard (timmers, puerto USB, conversores A/D, etc) además de brindar las primitivas para el intercambio de mensajes entre el computador y el usermodule y realiza la gestión de los ''usermodules''. Establece las bases para que los usermodules sean independientes del protocolo de comunicación computador/placa y de los detalles de hardware del microcontrolador utilizado. A su vez oferce un entorno de ejecución concurrente que permite instanciar de forma dinámica varios ''usermodules''.

'''2.3 USB4all ''usermodule'''''
Son los componentes intercambiables del sistema que permiten encapsular la lógica de un dispositivo especifico y su protocolo de comunicación con las aplicaciones de usuario. Permite al usuario dar rápidamente soporte a un nuevo dispositivo de forma genérica, expandiendo de ésta manera las funcionalidades del USB4all ''basefirmware''. Los ''user modules'' son los bloques principales sobre los que se construye la arquitectura USB4all. Exponen una API uniforme que es utilizada a modo de callbacks por el ''base firmware'' y también exponen los servicios que brindan los dispositivos. Es recomendable modelar cada uno de los dispositivos electrónicos conectados a la ''baseboard'' como un ''usermodule'' donde los servicios a exponer se mapean con las características del mismo, como ejemplo en el caso de un motor, sería esperable que expusiera servicios para moverse, cambiar la velocidad y el sentido.

Del lado del sistema computador se dispone de diferentes formas de interacción: Todas ellas implementan el protocolo USB4all, su objetivo es abstraer al usuario del mismo brindando una forma sencilla de utilizar el sistema, existiendo soporte para diferentes lenguajes de programación. El objetivo principal de las bibliotecas utilizadas en el computador son las de permitir utilizar los servicios de los ''usermodules''. Esta forma de trabajo permite desarrollar la lógica de interacción entre los diferentes dispositivos electrónicos dentro del sistema computador, con lenguajes de mayor abstracción, mejores herramientas de desarrollo, permitiendo generar un código con un nivel de mantenibilidad y abstracción mayor al que se lograría si todo estuviera embebido en el microcontrolador.

Uno de los componentes más usados actualmente es el bobot que persigue un enfoque genérico al igual que el proyecto USB4all y permite acompañar la extensibilidad de la placa USB4all mediante el uso de ciertos componentes propios de la arquitectura llamados drivers.

== 3. Protocolo de Comunicación ==

El protocolo está formado por un stack de protocolos que permiten abstraer al usuario de los detalles subyacentes de la arquitectura.
El objetivo final del protocolo de comunicación, es direccionar los mensajes provenientes desde la aplicación que se ejecuta en el computador, al ''usermodule'' correspondiente ejecutado en la placa USB4all.
Estos mensajes son solicitudes de ciertos servicios que los módulos exponen, por ejemplo en el caso de un dispositivo sonoro (buzzer) utilizado para una alarma, va a ser de interés poder emitir sonido (Prender el Buzzer) detener la emisón de sonido (Apagar el Buzzer), hacer sonidos cortos pasando por parámetro la cantidad de milisegundos que se desea esté prendido, etc.
Estos mensajes se tienen que codificar de alguna manera, el protocolo especifica que primero se debe indicar el comando que se desea se ejecute y luego en caso que sea necesario (como en el de los sonidos cortos) enviar los parámetros. En algunos casos va a ser necesario obtener respuestas, las cuales se codifican de forma análoga usando el mismo protocolo, enviando en lugar de un parámetro un valor de retorno.
Este protocolo es el que se llama ''user protocol'' y esta enfocado al usuario final, pero para que el sistema funcioné correctamente es necesario contar con otros protocolos los cuales transportan el protocolo ''user protocol''. Tal es el caso del handler manager protocol que se encarga de manejar el ruteo de los mensajes al ''user module'' correspondiente. Esto se debe a que en un momento determinado puede haber varios ''user modules'' ejecutando en la placa y el sistema debe permitir notificar al módulo del nuevo mensaje. La tarea fundamental de este protocolo es brindar los mecanismos para comunicar una aplicación con un ''user module''. Otro protocolo involucrado es el ''admin protocol'' el cual se encarga de gestionar el ciclo de vida de los ''user modules'', permitiendo poner a ejecutar un ''user module'', cerrarlo y también algunas funcionalidades como el listar los módulos presentes en la placa, cerrar todos los modulos abiertos o llevar al estado de reset al microcontrolador. Tanto el ''handler protocol'' como el ''admin protocol'' son implementados por las bibliotecas que se utilicen en el computador. Existiendo varias opciones, Java, Python o Lua. Actualmente la opción que se está manteniendo es la de Lua la cual puede estudiarse en profundidad en la sección bobot.

[[Archivo:protocolo.png|700px|Fig. 3.2 Protocolo USB4all]]

Finalmente los paquetes USB4all se trasmiten por el protocolo de comunicación que disponga el ''baseboard'', para el caso típico del ''baseboard usb4all'' se trasmite mediante USB, pero puede ser trasmitido mediante otras tecnologías utilizadas para comunicarse con un computador, como ser serial o bluetooth (entre otros).

== 4. Grabando el Firmware ==

Para grabar el firmware se necesita disponer de un programador, como el picdem o el pickit, este último tiene buen soporte dentro de GNU/Linux.
Microchip disrtibuye un bootloader para la familia de microcontroladores 18F. Un bootloader es unprograma que se utiliza para grabar otro. En nuestro caso, va a permitr grabar el firmware del proyecto USB4all sin la necesidad de disponer de un programador por hardware, para realizar esto es necesario dejar prescionado el botón de programación (botón más cercano al led) mientras se resetea la placa con el botón de reset. Esto funciona siempre y cuando el microcontrolador tenga grabado el bootloader.
Una vez que el dispositivo se encuentra en modo programación su identificador de producto cambia de 000c a 000b, esto puede verificarse utilizando el comando ''lsusb'' cuya salida se adjunta para los dos casos a continuación:

Id dispositivo USB4all
Bus 002 Device 002: ID 04d8:000c Microchip Technology, Inc.

id dispositivo Bootloader
Bus 002 Device 003: ID 04d8:000b Microchip Technology, Inc.

Dado que Microchip no distribuye microcontroladores con el bootlader previamente grabado, es necesario utilizar un programador por hardware para grabar el bootloader.
USB4all acutalmente utiliza un bootloader modificado que permite actualizar el firmware programáticamente sin necesidad de prescionar los botones, útil a la hora de realizar actualizaciones remotas, pero responde a los mismos comandos que el bootloader de Microchip, lo cual permite reutilizar el software ya desarrollado para interactuar con el bootloader.
Los fuentes del bootloader pueden encontrarse en el repositorio en el directorio bootloader del firmware, es un proyecto separado y una vez compilado su grabación se realiza mediante un programador por hardware como picdem o pickit.
Una vez grabado el bootloader ya '''no es necesario utilizar programadores por hardware''' y puede realizarse la grabación del firmware mediante varios programas que implementan el protocolo de grabación de firmware de microchip. Una de esas utilidades es el programa fsusb el cual puede encontrarse en [http://www.internetking.org/fsusb/] y es de código libre. Su uso se realiza de la siguiente forma:

./fsusb --program usb4all2.hex

Donde usb4all2.hex es el binario generado como resultado de compilar el proyecto. Recordar que el hardware debe de estar en modo bootloader para poder recibir el firmware.

== 5 Entorno de desarrollo ==
[[Archivo:piklab.png|thumb|Fig. 5.1:Entorno de desarrollor con Piklab en GNU/Linux]][[Archivo:mplab.png|thumb|Fig. 5.2: Entorno de desarrollor con MPLab en GNU/Linux]]
El proyecto USB4all está desarrollado para el compilador C18 de Microchip, hoy día se dispone de un buen soporte del mismo para GNU/Linux puediendose descargar de [http://ww1.microchip.com/downloads/MPLAB/X_Beta/installer.html] también se dispone de un entorno de desarrollo llamado MPLab el cual también se encuentra disponible para GNU/Linux en la misma dirección.
Hace un tiempo atrás no existía compatibilidad para GNU/Linux de estas herramientas clásicas para los ambientes Windows en GNU/Linux. Debiendose recurrir a alternativas para trabajar en un ambiente GNU/Linux, una opción era Piklab. Piklab es un entorno de desarrollo para trabajar con microcontroladores PIC similar a lo que es MPLab. Era muy común utilizar la versión de C18 de windows emulada mediante wine en GNU/Linux debiendose configurar en las opciones de toolchain de PIKLab correspondientes a C18 para que apunten correctamente a los directorios donde se encuentra el compilador C18. En el repositorio puede encontrarse un proyecto piklab configurado de esta manera. Más información sobre la configuración de c18 con piklab en linux (deprecated) ver: [http://cantareus.com/2009/08/18f4550-and-18f2550-with-piklab-and-ubuntu/]
 Luego de compilar, cargar el binario generado (.hex) en la placa mediante el uso del bootloader que se incluye en el firmware. Esto puede realizarse utilizando la herramienta fsusb como se describe en la sección Grabando el Firmware.

== 6. Escribiendo un ''usermodule'' ==
Un ''usermodule'' es el bloque sobre el cual se representa una realidad y se modela utilizando la arquitectura ''USB4all'', en esta sección se presentan sus características, estructura necesaria para especificar los servicios que brinda y de que forma se anexa al ''firmwarebase''

[[Archivo:user_module.png|thumb|Fig. 6.1: Tabla de referencias a ''user modules'']]

'''6.1 Estructura de un ''usermodule:'' ''' 
Un ''usermodule'' debe cumplir con una API determinada, de esta manera es posible agregar las funcionalidades que el módulo expone, dentro del ''basefirmware''.
Las operaciones principales que se deben implementar son las encargadas de atender los eventos de:
* inicialización
* liberación de recursos
* configuración

Estas operaciones se ejecutan en determinados momentos del ciclo de vida de una aplicación USB4all, siendo la operación registrada al evento de inicialización invocada al abrir desde la aplicación el ''usermodule'' y la de liberación de recursos al cerrarlo, esto permite utilizar los recursos del microcontrolador solo cuando es necesario. La operación de configuración puede invocarse en cualquier momento para cambiar en caliente algún aspecto de configuración del hardware.
A comenzar un ''usermodule'' se debe declarar cuales van a ser las funciones que van a atender estos eventos y el nombre del módulo para ser identificado desde el computador al listar los módulos presentes en la placa.

#pragma romdata user
uTab userBuzzerModuleTable = {&UserBuzzerInit,&UserBuzzerRelease,&UserBuzzerConfigure,"buzzer"};
#pragma code

Donde user es el nombre de la sección y uTab es una estructura para almacenar las posiciones de memoria de las operaciones que exporta el módulo y su nombre. En la sección detalles de implementación en el firmware se puede comocer más sobre el significado de la instrucción #pragma romdata user, podemos por el momento asumir que sirve para almacenar la estructura uTab en un lugar conocido de memoria.

Como argumento a la operación init se recibe el número de handler asignado al módulo, este número es utilizado como argumento en otras operaciones como ser ''setHandlerReceiveFunction'' la cual recibe por parámetro el handler y un puntero a la función encargada de manejar la recepción de datos. Otra operación similar es ''getSharedBuffer'' que recibe por parámetro el ''handlerID'' del módulo y retorna un buffer por el cual el módulo puede enviar datos a la aplicación que ejecuta en el computador.
Un buen lugar para obtener éste buffer y registrar la función de recepción de datos es la operación encargada del evento de inicialización. A continuación puede verse como ejemplo la inicialización de un módulo de usuario para controlar un buzzer:

<syntaxhighlight lang="C"> void UserBuzzerInit(byte i) {
usrBuzzerHandler = i;
// add my receive function to the handler module, to be called automatically when the pc sends data to the user module
setHandlerReceiveFunction(usrBuzzerHandler,&UserBuzzerReceived);
// initialize the send buffer, used to send data to the PC
sendBufferUsrBuzzer = getSharedBuffer(usrBuzzerHandler);
}//end UserBuzzerInit </syntaxhighlight>

La función de recepción de datos es la encargada de implementar el protocolo de comunicación entre el ''usermodule'' y la aplicación, típicamente es una estructura tipo ''case'' en el que se espera por los diferentes comandos que pueden enviarse. La forma de codificar el pedido de servicios es mediante mensajes del tipo < COMANDO [argumento1] [argumento2]...[argumentoN] >. La respuesta debe ser del tipo < COMANDO [resultado1] [resultado2]..[resultadoN] >. El buffer para enviar datos al computador es obtenido como argumento de la función y el buffer para enviar datos fue obtenido previamente en la función de inicialización.

<syntaxhighlight lang="C"> void UserBuzzerReceived(byte* recBuffPtr, byte len){
byte index;
byte j;
byte userBuzzerCounter = 0;
byte tiempo;

switch(((BUZZER_DATA_PACKET*)recBuffPtr)->CMD){
case READ_VERSION:
//dataPacket._byte[1] is len
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[2] = BUZZER_MINOR_VERSION;
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[3] = BUZZER_MAJOR_VERSION;
userBuzzerCounter = 0x04;
break;

case PRENDER:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_on();
userBuzzerCounter = 0x02;
break;

case APAGAR:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_off();
userBuzzerCounter = 0x02;
break;

case BUZZER_TRIPLE:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks1 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1]);
cantTicks2 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[2]);
cantTicks3 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[3]);
boubleBeep(cantTicks1, cantTicks2, cantTicks3);
userBuzzerCounter = 0x02;
break;

case BUZZER_CORTO:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks3 = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
timeOutTicksBuzz = 1; // lo seteo timmer para que venza inmediantamente
buzzerState = DELAY;
registerT0event(0, &buzzEvent);
userBuzzerCounter = 0x02;
break;

case RESET:
Reset();
break;

default:
break;
}//end switch(s)
if(userBuzzerCounter != 0){
j = 255;
while(mUSBGenTxIsBusy() && j-->0); // pruebo un máximo de 255 veces
if(!mUSBGenTxIsBusy())
USBGenWrite2(usrBuzzerHandler, userBuzzerCounter);
}//end if
}//end UserBuzzerReceived</syntaxhighlight>

En este ejemplo se puede apreciar como se reciben los pedidos de comandos desde la aplicación que ejecuta en el computador y como se obtienen los parámetros necesarios para implementar los comandos y se devuelven los datos (en caso de ser requeridos) a la aplicación.

'''6.2 Entrada/Salida en user modules:''' 
Una de las tareas más importantes de los ''usermodules'' es la de realizar entrada/salida con diferentes periféricos electrónicos. Para realizar ésta tarea existen dos paradigmas:
 
* Polling
* Interrupciones
 
Dentro de la arquitectura USB4all existen formas de que los módulos implementen entrada/salida utilizando estos paradigmas, para el caso de pooling existe un servicio que permite registrar una función para ser ejecutada cuando el procesador este disponible.

<syntaxhighlight lang="C">
addPollingFunction(&UserBuzzerProcessIO);
</syntaxhighlight>

Existe soporte para interrupciones mediante el módulo ''DynamicISR'' el cual permite que otros módulos se registren sus rutinas de atención para ser invocadas cuando ocurren interrupciones.

<syntaxhighlight lang="C">
addISRFunction(&timmerISRFunction);
</syntaxhighlight>

Una forma que mantiene alta la cohesión del sistema es registrar módulos que se encarguen de esperar un evento en particular y brinde una interfaz para que los ''usermodules'' se registren para ser notificados de eventos generados por el componente de hardware que esta siendo modelado. Dentro de éste módulo además se pueden brindar operaciónes con mayor nivel de abstracción relacionadas con el componente a modelar. Hoy día se dispone del módulo T0service que se encarga de brindar servicio de timmers a los ''usermodules''. Al igual que el resto de los componentes funciona registrando funciones que son invocadas por el ''basefirmware''

También existen funciones para desregistrar los ''usermodules'' de las notificaciones, es conveniente realizar la desregistración en la función que implementa el evento de liberación de recursos del módulo.

Por ahora el único componente de hardware del microcontrolador modelado de esta forma es el timmer, pero puede escalarse a otros que requieran ser compartidos por más de un módulo.
Hay que recordar que la concurrencia implementada es puramente colaborativa entre ''usermodules'' por lo cual se debe tener especial cuidado al programar las funciones que atienden estos eventos ya que si se queda "colgada" va a degradar la disponibilidad de todo el sistema.

Para agregar el ''usermodule'' a la placa de entrada/salida ''usb4all baseboard'' se debe agregar al proyecto el módulo (utilizando el IDE preferido) y realizar la compilación del proyecto

== 7. Servicios de Timers - T0Service ==

T0service es un módulo encargado de brindar primitivas a los ''user modules'' para ser notificados de eventos del timmer.
La API expuesta es la siguiente:

<syntaxhighlight lang="C">
/*
Registers a new event callback, to be called t time units in the future.
This function must not be called from a callback handler.
*/
BOOL registerT0event(unsigned int t, void (*callback)(void));

/*
Registers a new event callback, to be called t time units in the future.
This function only can be called from a callback handler.
*/
BOOL registerT0eventInEvent(unsigned int t, void (*callback)(void));

/*
Unregister a event callback. No pending event(s) will invoke it.
*/
BOOL unregisterT0event(void (*callback)(void));

/*
Initialize the service
*/
void initT0Service(void);
</syntaxhighlight>

== 8. Detalles de implementación en el firmware ==

El firmware está organizado en diferentes áreas que se mapean en secciones definidas dentro de la memoria ROM correspondiente a la memoria de programa del microcontrolador, para implementar esto se necesita especificar en un archivo llamado linker script dónde están alojadas físicamente (en memoria) estas secciones.
La forma de realizar este mapeo es editando el archivo lrk asociado al proyecto.
Existe la directiva CODEPAGE que es utilizada para trabajar con las secciones de programa, permite inicializar datos, constantes, y realizar referencias a las mismas. Tiene el siguiente formato

CODEPAGE NAME=memName START=addr END=addr [PROTECTED] [FILL=fillvalue]

donde:
memName es un string ASCII utilizado para identificar una CODEPAGE.

También existe la directiva DATABANK que permite realizar un manejo similar pero sobre la memoria de datos.

La directiva #pragma
El estándar ANSI C provee a cada implementación de un método para definir constructores únicos, según sea requerido por la arquitectura del procesador a utilizar. Esto es hecho utilizando la directiva #pragma. La directiva #pragma más común en el compilador utilizado (MPLAB C18) identifica la sección de memoria para ser utilizada en el PIC18XXXX. Por ejemplo #pragma code le indica al compilador MPLAB 18 que compile el código C en la sección de programa de la memoria de programa. La sección de código está definida en el linker script asociado para cada dispositivo PIC18XXXX, especificando en que áreas de la memoria de programa pueden ser ejecutadas instrucciones.
Esta directiva puede ser insertada directamente o puede ser seguida de la dirección en el área de código del procesador destino, permitiendo tener un control total del a memoria de código.
En el contexto del USB4all esto es muy utilizado, debido a que se separan varias áreas de memoria, las más importantes son la del bootloader, y la correspondiente a los módulos de usuario, tanto para la parte de programa (module_sec) como para la información del módulo que se almacena para gestionarlo (user_sec).
Otra directiva #pragma común que se utiliza es #pragma udata, la cual se utiliza cuando se aloja memoria para variables, las variables no inicianlizadas definidas después de esta declaración van a utilizar los registros de proposito general para almacenamiento. La arquitectura del PIC18XXXX, se basa en una arquitectura harvard la que a diferencia de la von neumann almacena las variables y las instrucciones en diferentes espacios de memoria. Por tanto las áreas de memoria deben ser explicitamente identificadas.

Por más información, consultar con el manual del compilador C18 (http://www.kevin.org/frc/C18_3.0_getting_started.pdf) en la sección #pragma DIRECTIVE o SECTIONS.

De la forma que se definieron las secciones en el archivo lkr del proyecto (18f4550.lkr) se debe colocar un #pragma code module al comenzar la declaración de los procedimientos del módulo, de esa forma se almacenan en memoria de programa (code section) dentro de la sección module. Si consultamos el linker script podemos ver que está definida la sección module como un alias del área en ROM llamada module_sec

SECTION NAME=module ROM=module_sec

a su vez module_sec es definida como:

CODEPAGE NAME=module_sec START=0x40AB END=0xFFFF PROTECTED

Lo mismo se debe hacer cuando se definen las funciones que utiliza el módulo para atender eventos y su nombre (estructura uTab):

#pragma romdata user
uTab userBuzzerModuleTable = {&UserBuzzerInit,&UserBuzzerRelease,&UserBuzzerConfigure,"buzzer"};
Como vimos en el ejemplo presentado en la sección escribiendo un ''user module''.
Hay que tener cuidado de no olvidarse de los #pragmas correspondientes ya que de de lo contrario puede no dar el espacio para compilar el proyecto o no funcionar el mecanismo de callbacks.
Los archivos lkr también especifican otros conceptos, como ser tamaño de memoria de datos y registros que utiliza, como también tamaño del stack

== 9. Bobot ==
[[Archivo:bobot.png|thumb|Fig. 9.1 bobot logo]][[Archivo:componentes.png|thumb|Fig. 9.2 Arquitectura del bobot]][[Archivo:web_bobot.png|thumb|Fig. 9.3 Interacción con dispositivo USB4all de forma web]]
bobot-server (version 2) es un servicio que permite acceder a aplicaciones y usuarios interactuar con dispositivos USB4all.
Consiste en un agente altamente portable y liviano, que exporta la funcionalidad de los dispositivos USB4all presentes de una forma fácil de usar. Ofrece dos métodos de acceso,
uno optimizado para aplicaciones, basado en un socket y un protocolo fácilmente parseable, y otro optimizado para ser usado por humanos, mediante un sitio web
hosteado en el propio agente, el cual atiende en el puerto 2010. 
Bobot introduce el concepto de driver, en el cual se codifica el protocolo que utilizan los ''usermodules'', de esta forma se exponen al usuario del sistema bobot los servicios que implementan los ''usermodules'' ocultando los detalles relacionados con el protocolo de intercambio de mensajes.
Para desarrollar compatibilidad con un nuevo dispositivo electronico en la plataforma USB4all utilizando bobot para su control, primero se debe desarrollar el ''usermodule'' necesario como fue descripto en la sección: Escribiendo un ''usermodule'' luego se debe escribir el driver correspondiente a ese ''usermodule''.

El driver se escribe en Lua, debe seguir un formato preestablecido y es implementado mediante el recurso de tablas que brinda Lua. Una característica de Lua es que las funciones son miembros de primer orden, esto permite (entre otras cosas) que una función pueda ser un tipo de datos válido, pasar funciones como argumento de funciones o como retorno de las mismas y almacenarla en una tabla.
Esta capacidad permite que dentro de la tabla que representa un driver se puedan almacenar funciones asociadas para cada servicio expuesto por un módulo. Estas funciones son invocadas al solicitarse servicios desde la aplicación que utiliza la biblioteca.

Asociado a cada función se almacenan metadatos que describen los parámetros que la función recibe, su tipo, valor de retorno y valores aceptados.
Mucha de ésta información es utilizada por el bobot para generar el sitio web mencionado anteriormente, como se muestra en la figura 9.3. Este sitio describe al módulo de usuario y se puede usar como documentación y mecanismo de prueba del mismo.
A continuación se muestra un ejemplo de driver para el módulo de usuario presentado en la sección: Escribiendo un ''usermodule''. En este driver podemos ver que se exportan los siguientes servicios:
* read_version
* prender
* apagar
* buzzer_corto
* buzzer_triple

El siguiente código corresponde con la implementación de estos servicios en un driver bobot: 

<syntaxhighlight lang="lua">
local device = _G
local RD_VERSION = string.char(0x00)
local PRENDER = string.char(0x01)
local APAGAR = string.char(0x02)
local BUZZER_CORTO = string.char(0x03)
local BUZZER_TRIPLE = string.char(0x04)

api={}
api.read_version = {}
api.read_version.parameters = {} --no parameters
api.read_version.returns = {[1]={rname="version", rtype="number"}} --one return
api.read_version.call = function ()
local get_read_version = RD_VERSION
device:send(get_read_version)
local version_response = device:read(2)
local raw_val = string.byte(version_response, 2)
--print("rawval, deg_temp: ", raw_val, deg_temp)
return raw_val
end

api.prender = {}
api.prender.parameters = {} --no parameters
api.prender.returns = {} --no return
api.prender.call = function ()
local write_res, err = device:send(PRENDER)
if write_res then return true else return false end
end

api.apagar = {}
api.apagar.parameters = {} --no parameters
api.apagar.returns = {} --no return
api.apagar.call = function ()
local write_res, err = device:send(APAGAR)
if write_res then return true else return false end
end

api.buzzer_corto = {}
api.buzzer_corto.parameters = {[1]={rname="num", rtype="number"}}
api.buzzer_corto.returns = {} --no return
api.buzzer_corto.call = function (num)
local write_res, err = device:send(BUZZER_CORTO .. string.char(num))
if write_res then return true else return false end
end

api.buzzer_triple = {}
api.buzzer_triple.parameters = {[1]={rname="tiempo1", rtype="number"}, [2]={rname="tiempo2", rtype="number"}, [3]={rname="tiempo3", rtype="number"}}
api.buzzer_triple.returns = {} --no return
api.buzzer_triple.call = function (tiempo1, tiempo2, tiempo3)
local write_res, err = device:send(BUZZER_TRIPLE .. string.char(tiempo1) .. string.char(tiempo2) .. string.char(tiempo3))
if write_res then return true else return false end
end
</syntaxhighlight>

En el ejemplo puede notarse al comparar con el ''usermodule'' presentado de ejemplo, como se realiza el pasaje de parámetros entre el driver y el ''usermodule'', esto corresponde con el protocolo definido por el usuario para codificar los comandos del ''usermodule'' y el orden de los parámetros, este protocolo es llamado en la arquitectura USB4all como ''user protocol'' y responde al formato de < COMANDO [argumento1] [argumento2]...[argumentoN] > para el pedido y mensajes del tipo < COMANDO [resultado1] [resultado2]..[resultadoN] > para la respuesta.

Entre las características del bobot se encuentra la capacidad de abstraer al usuario del tipo de hardware de placa de E/S está conectada pudiendo ser placas que utilizan comunicación serial rs232c o USB u otra tecnología como también la cantidad de las mismas. En la figura 8.2 puede verse un caso posible, donde se encuentran diferentes ''usermodules'' cargados en una ''baseboard'' y ciertos drivers cargados en el bobot que van a permitir consumir los servicios expuestos por los ''usermodules''.

Como se mencionó al comienzo de la sección, bobot expone un protocolo que puede utilizarse mediante conexiones TCP/IP, este protocolo se describe de esta forma:

LIST
DESCRIBE moduleName
CALL moduleName operation param1, param2, ...,paramN
OPEN moduleName
CLOSEALL

Donde el comando:
* LIST despliega la lista de módulos disponibles en la placa por su nombre.
* DESCRIBE muestra la información de que servicios expone el módulo de nombre moduleName e información sobre los parámetros.
* CALL es utilizado para invocar los servicios expuestos por un módulo.
* OPEN se utiliza para abirir un módulo, a partir de ese momento el baseboard le asigna tiempo de CPU y recursos al ''usermodule'', actualmente esta deprecado su uso ya que bobot se encarga de abrirlos de forma automática ante la primer invocación.
* CLOSEALL cierra todos los módulos abiertos en la placa, llevandola a un estado conocido.

Puede descargarse bobot desde el git del proyecto butiá en sourceforge.

== ANEXO 1 ==

En el enlace [http://sourceforge.net/p/usb4all/code/ci/6ecc2581f50519fe427f7a3947136c2a03108841/tree/firmware/u4a2/user/usr_buzzer.c] y [http://sourceforge.net/p/usb4all/code/ci/6ecc2581f50519fe427f7a3947136c2a03108841/tree/firmware/u4a2/user/usr_buzzer.h] puede descargarse el código completo del ejemplo presentado como caso de estudio. El mismo puede usarse como esqueleto para desarrollar otros ''user modules''

----

El proyecto USB4all se encuentra disponible bajo licencia GNU/GPL v2 en el [http://sourceforge.net/projects/usb4all/ repositorio sorceforge] 
Este proyecto surge originalmente como un trabajo de [http://www.fing.edu.uy/inco/grupos/mina/pGrado/pgusb tesis de grado] en Ingeniería en Computación de Aguirre, Fernandez y Grossy.

Usb4all

2011-10-05T19:08:16Z

Edgardo: /* Bobot */

== Motivación ==

La motivación de este proyecto se centra en lograr de una manera sencilla, la comunicación entre un sistema computador y un conjunto de dispositivos electrónicos no necesariamente pensados para interactuar con una computadora.
Durante muchos años la única forma de interactuar con dispositivos externos desde a un computador personal (Personal Computer) (PC) fueron los puertos seriales y paralelos, esto llevo a que se utilizaran ampliamente en multiplicidad de dispositivos. Sus principales carácteristicas son su simplicidad de manejo vía software y facilidad de inclusión en distintos dispositivos. En la última década han aparecido nuevos medios o canales de comunicación, tales como Bluetooth, Fidelidad Inalámbrica (Wireless Fidelity) (WiFi), FireWire, Bus Universal en Serie (Universal Serial Bus) (USB), etc. Estos permitieron mejorar las velocidades de comunicación y calidad de datos y lentamente tornaron a los puertos paralelos y seriales en obsoletos, hasta llegar al día de hoy en que se obtienen sólo de manera opcional en los nuevos PC.
Dentro de todas estas nuevas tecnologías que aparecieron la que tuvo mayor aceptación y difusión entre los usuarios fue el USB, debido a su facilidad y versatilidad de escenarios de uso. Esta simplicidad desde el punto de vista del usuario de los dispositivos USB tiene como contrapartida una mayor complejidad para los desarrolladores de software y hardware, lo cual es un gran problema al momento de interactuar con dispositivos electrónicos.
Frente a estas adversidades que presenta el entorno actual aparece la necesidad de buscar una forma de reducir el grado de complejidad y conocimientos necesarios para poder desarrollar
software que utilice la tecnología USB. Al mismo tiempo, se requiere una plataforma base que incorpore componentes de hardware reutilizables y que en conjunto formen una solución genérica
para la comunicación con dispositivos electrónicos diversos.
En el contexto de lo antedicho aparecen un conjunto de desafíos como son el desarrollo de controladores (drivers) y construcción de piezas de hardware que brinde una solución genérica
reutilizable, desplazando el manejo de los casos particulares a componentes específicos. Esto proporciona el beneficio de evitar que cada vez que se necesite conectar un nuevo dispositivo,
se comience desde cero. A su vez permite recuperar y potenciar la característica de facilidad de manejo que poseían los puertos seriales y paralelos, explotando todas las capacidades brindadas
por USB.

== Arquitectura ==

La arquitectura esta compuesta por diferentes componentes, los cuales van a permitir el funcionamiento del sistema desde lo concerniente al hardware como las abstracciones necesarias para manejarlo mediante software. Los componentes principales son:

'''USB4all ''Baseboard'''''

[[Archivo:usb4all2.png|thumb|USB4all Baseboard]]
Es una placa de entrada/salida configurable que se conecta por USB con un sistema computador. El proyecto USB4all es mucho más que una placa de E/S, en sí es una forma de modelar sistemas embebidos, siendo la placa de E/S un componente que fue necesario construir para desarrollar la solución completa. Para la construcción de ésta placa se utilizó un microcontrolador PIC18F4550 de Microchip. Entre las características más destacadas en lo que concierne al proyecto se encuentra el soporte completo del estándar USB, pudiéndose utilizar varias de sus características, como ser diferentes tipos de transferencias y varios canales de comunicación (endpoints).

'''USB4all ''base firmware'''''

Es el firmware más estático, brinda servicios a los usermodules para que puedan utilizar los recursos presentes en la baseboard (timmers, puerto USB, conversores A/D, etc) además de brindar las primitivas para el intercambio de mensajes entre el computador y el usermodule y realiza la gestión de los ''usermodules''. Establece las bases para que los usermodules sean independientes del protocolo de comunicación computador/placa y de los detalles de hardware del microcontrolador utilizado. A su vez oferce un entorno de ejecución concurrente que permite instanciar de forma dinámica varios ''usermodules''.

'''USB4all ''usermodule'''''
Son los componentes intercambiables del sistema que permiten encapsular la lógica de un dispositivo especifico y su protocolo de comunicación con las aplicaciones de usuario. Permite al usuario dar rápidamente soporte a un nuevo dispositivo de forma genérica, expandiendo de ésta manera las funcionalidades del USB4all ''basefirmware''. Los ''user modules'' son los bloques principales sobre los que se construye la arquitectura USB4all. Exponen una API uniforme que es utilizada a modo de callbacks por el ''base firmware'' y también exponen los servicios que brindan los dispositivos. Es recomendable modelar cada uno de los dispositivos electrónicos conectados a la ''baseboard'' como un ''usermodule'' donde los servicios a exponer se mapean con las características del mismo, como ejemplo en el caso de un motor, sería esperable que expusiera servicios para moverse, cambiar la velocidad y el sentido.

Del lado del sistema computador se dispone de diferentes formas de interacción: Todas ellas implementan el protocolo USB4all, su objetivo es abstraer al usuario del mismo brindando una forma sencilla de utilizar el sistema, existiendo soporte para diferentes lenguajes de programación. El objetivo principal de las bibliotecas utilizadas en el computador son las de permitir utilizar los servicios de los ''usermodules''. Esta forma de trabajo permite desarrollar la lógica de interacción entre los diferentes dispositivos electrónicos dentro del sistema computador, con lenguajes de mayor abstracción, mejores herramientas de desarrollo, permitiendo generar un código con un nivel de mantenibilidad y abstracción mayor al que se lograría si todo estuviera embebido en el microcontrolador.

Uno de los componentes más usados actualmente es el bobot que persigue un enfoque genérico al igual que el proyecto USB4all y permite acompañar la extensibilidad de la placa USB4all mediante el uso de ciertos componentes propios de la arquitectura llamados drivers.

== Protocolo de Comunicación ==

==Grabando el Firmware ==

Para grabar el firmware se necesita disponer de un programador, como el picdem o el pickit, este último tiene buen soporte dentro de GNU/Linux
Microchip disrtibuye un bootloader para ésta familia de microcontroladores, el cual permite grabar el firmware sin la necesidad de disponer de un programador, para realizar esto es necesario dejar prescionado el botón de programación (botón más cercano al led) mientras se resetea la placa con el botón de reset.
Una vez que el dispositivo se encuentra en modo programación su identificador de producto cambia de 000c a 000b, esto puede verificarse utilizando el comando ''lsusb'' cuya salida se adjunta para los dos casos a continuación:

Id dispositivo USB4all
Bus 002 Device 002: ID 04d8:000c Microchip Technology, Inc.

id dispositivo Bootloader
Bus 002 Device 003: ID 04d8:000b Microchip Technology, Inc.

La versión 2.0 de la placa USB4all utiliza un bootloader modificado que permite actualizar el firmware programáticamente sin necesidad de prescionar los botones.
La misma puede encontrarse en el repositorio en el directorio bootloader del firmware, es un proyecto separado y una ves compilado su grabación se realiza mediante un programador por hardware como picdem o pickit.
Una vez grabado el bootloader ya no es necesario utilizar programadores por hardware y puede realizarse la grabación del firmware mediante varios programas que implementan el protocolo de grabación de firmware de microchip. Una de esas utilidades es el programa fsusb el cual puede encontrarse en [http://www.internetking.org/fsusb/] y es de código libre. Su uso se realiza de la siguiente forma:

./fsusb --program usb4all2.hex

Donde usb4all2.hex es el binario generado como resultado de compilar el proyecto. Recordar que el hardware debe de estar en modo bootloader para poder recibir el firmware.

== Entorno de desarrollo ==
[[Archivo:piklab.png|thumb|Entorno de desarrollor con piklab]]
Una de las opciones posibles para trabajar en un ambiente GNU/Linux es instalar el Piklab, Piklab es un entorno de desarrollo para trabajar con microcontroladores PIC, el proyecto USB4all utiliza el compilador C18 de Microchip el cual solo está disponible para Windows, para hacerlo funcionar se utiliza wine y se debe configurar el toolchain C18 en piklab para que apunte correctamente a los directorios donde se encuentra el compilador C18.
Una limitante que posee este compilador es que no permite rutas de archivos que sean muy largas, lo cual es fácilmente alcanzado utilizando wine, por lo tanto se recomienda que el proyecto este lo más cercano a la raíz posible.
Más información sobre la configuración de c18 con piklab en linux ver: [http://cantareus.com/2009/08/18f4550-and-18f2550-with-piklab-and-ubuntu/]
Otra opción es utilizar MPlab que actualmente trae soporte para GNU/Linux [http://microchip.wikidot.com/mplab:_start]
En el repositorio USB4all puede descargarse un proyecto ya armado para trabajar con piklab, compilando contra c18 mediante wine. Luego de compilar, cargar el binario en la placa mediante el uso del bootloader que se incluye en el firmware, utilizando la utilidad fsusb como fue descripto en la sección Grabando el Firmware.

== Escribiendo un ''usermodule'' ==
[[Archivo:user_module.png|thumb|tabla de referencias a ''user modules'']]

Un ''usermodule'' debe cumplir con una API determinada, de esta manera es posible agregar las funcionalidades que el módulo expone, dentro del ''basefirmware''.
Las operaciones principales que se deben implementar son las encargadas de atender los eventos de:
* inicialización
* liberación de recursos
* configuración

Estas operaciones se ejecutan en determinados momentos del ciclo de vida de una aplicación USB4all, siendo la operación registrada al evento de inicialización invocada al abrir desde la aplicación el ''usermodule'' y la de liberación de recursos al cerrarlo, esto permite utilizar los recursos del microcontrolador solo cuando es necesario. La operación de configuración puede invocarse en cualquier momento para cambiar en caliente algún aspecto de configuración del hardware.
A comenzar un ''usermodule'' se debe declarar cuales van a ser las funciones que van a atender estos eventos y el nombre del módulo para ser identificado desde el computador al listar los módulos presentes en la placa.

#pragma romdata user
uTab userBuzzerModuleTable = {&UserBuzzerInit,&UserBuzzerRelease,&UserBuzzerConfigure,"buzzer"};
#pragma code

Donde user es el nombre de la sección y uTab es una estructura para almacenar las posiciones de memoria de las operaciones que exporta el módulo y su nombre.

Como argumento a la operación init se recibe el número de handler asignado al módulo, este número es utilizado como argumento en otras operaciones como ser ''setHandlerReceiveFunction'' la cual recibe por parámetro el handler y un puntero a la función encargada de manejar la recepción de datos. Otra operación similar es ''getSharedBuffer'' que recibe por parámetro el ''handlerID'' del módulo y retorna un buffer por el cual el módulo puede enviar datos a la aplicación que ejecuta en el computador.
Un buen lugar para obtener éste buffer y registrar la función de recepción de datos es la operación encargada del evento de inicialización
<syntaxhighlight lang="C"> void UserBuzzerInit(byte i) {
usrBuzzerHandler = i;
// add my receive function to the handler module, to be called automatically when the pc sends data to the user module
setHandlerReceiveFunction(usrBuzzerHandler,&UserBuzzerReceived);
// initialize the send buffer, used to send data to the PC
sendBufferUsrBuzzer = getSharedBuffer(usrBuzzerHandler);
}//end UserBuzzerInit </syntaxhighlight>

La función de recepción de datos es la encargada de implementar el protocolo de comunicación entre el ''usermodule'' y la aplicación, típicamente es un case en el que se espera por los diferentes comandos que pueden enviarse. La forma de codificar el pedido de servicios es mediante mensajes del tipo <comando><argumento1>...<argumentoN>. La respuesta debe ser del tipo <comando><resultado1>...<resultadoN>. El buffer para enviar datos al computador es obtenido como argumento de la función y el buffer para enviar datos fue obtenido previamente en la función de inicialización.

<syntaxhighlight lang="C"> void UserBuzzerReceived(byte* recBuffPtr, byte len){
byte index;
byte j;
byte userBuzzerCounter = 0;
byte tiempo;

switch(((BUZZER_DATA_PACKET*)recBuffPtr)->CMD){
case READ_VERSION:
//dataPacket._byte[1] is len
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[2] = BUZZER_MINOR_VERSION;
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[3] = BUZZER_MAJOR_VERSION;
userBuzzerCounter = 0x04;
break;

case PRENDER:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_on();
userBuzzerCounter = 0x02;
break;

case APAGAR:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_off();
userBuzzerCounter = 0x02;
break;

case BUZZER_TRIPLE:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks1 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1]);
cantTicks2 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[2]);
cantTicks3 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[3]);
boubleBeep(cantTicks1, cantTicks2, cantTicks3);
userBuzzerCounter = 0x02;
break;

case BUZZER_CORTO:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks3 = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
timeOutTicksBuzz = 1; // lo seteo timmer para que venza inmediantamente
buzzerState = DELAY;
registerT0event(0, &buzzEvent);
userBuzzerCounter = 0x02;
break;

case RESET:
Reset();
break;

default:
break;
}//end switch(s)
if(userBuzzerCounter != 0){
j = 255;
while(mUSBGenTxIsBusy() && j-->0); // pruebo un máximo de 255 veces
if(!mUSBGenTxIsBusy())
USBGenWrite2(usrBuzzerHandler, userBuzzerCounter);
}//end if
}//end UserBuzzerReceived</syntaxhighlight>

En este ejemplo se puede apreciar como se reciben los pedidos de comandos desde la aplicación que ejecuta en el computador y como se obtienen los parámetros necesarios para implementar los comandos y se devuelven los datos (en caso de ser requeridos) a la aplicación.

'''Entrada/Salida en user modules:'''
Una de las tareas más importantes de los ''usermodules'' es la de realizar entrada/salida con diferentes periféricos electrónicos. Para realizar ésta tarea existen dos paradigmas:
 
* Polling
* Interrupciones
 
Dentro de la arquitectura USB4all existen formas de que los módulos implementen entrada/salida utilizando estos paradigmas, para el caso de pooling existe un servicio que permite registrar una función para ser ejecutada cuando el procesador este disponible.

<syntaxhighlight lang="C">
addPollingFunction(&UserBuzzerProcessIO);
</syntaxhighlight>

Existe soporte para interrupciones mediante el módulo ''DynamicISR'' el cual permite que otros módulos se registren para ser notificados cuando ocurren interrupciones.

<syntaxhighlight lang="C">
addISRFunction(&timmerISRFunction);
</syntaxhighlight>

Una forma que mantiene alta la cohesión del sistema es registrar módulos que se encarguen de esperar un evento en particular y brinde una interfaz para que los ''usermodules'' se registren para ser notificados de eventos generados por el componente de hardware que esta siendo modelado. Hoy día se dispone del módulo T0service que se encarga de brindar servicio de timmers a los ''usermodules''. Al igual que el resto de los componentes funciona registrando funciones que son invocadas por el ''basefirmware''

También existen funciones para desregistrar los ''usermodules'' de las notificaciones, es conveniente realizar la desregistración en la función que implementa el evento de liberación de recursos del módulo.

Por ahora el único componente de hardware del microcontrolador modelado de esta forma es el timmer, pero puede escalarse a otros que requieran ser compartidos por más de un módulo.
Hay que recordar que la concurrencia implementada es puramente colaborativa entre ''usermodules'' por lo cual se debe tener especial cuidado al programar las funciones que atienden estos eventos ya que si se queda "colgada" va a degradar la disponibilidad de todo el sistema.

Para agregar el usermodule a la placa de entrada salida usb4all ''baseboard'' se debe agregar al proyecto en piklab el módulo y realizar la compilación del proyecto

== Detalles de implementación en el firmware ==

El firmware está organizado en diferentes área que se mapean en secciones definidas dentro de la memoria ROM correspondiente a la memoria de programa del microcontrolador, para implementar esto se necesita especificar en un archivo llamado linker script dónde están alojadas físicamente(en memoria) estas secciones.
La forma de realizar este mapeo es editando el archivo lrk asociado al proyecto.
Existe la directiva CODEPAGE que es utilizada para trabajar con las secciones de programa, permite inicializar datos, constantes, y referencias externas. Tiene el siguiente formato

CODEPAGE NAME=memName START=addr END=addr [PROTECTED] [FILL=fillvalue]

donde:
memName es un string ASCII utilizado para identificar una CODEPAGE.

== Bobot ==
[[Archivo:bobot.png|thumb|bobot logo]][[Archivo:web_bobot.png|thumb|Interacción con dispositivo USB4all de forma web]]
bobot-server (version 2) es un servicio que permite acceder a aplicaciones y usuarios interactuar con dispositivos USB4all.
Consiste en un agente altamente portable y liviano, que exporta la funcionalidad de los dispositivos USB4all presentes de una forma fácil de usar. Ofrece dos métodos de acceso,
uno optimizado para aplicaciones, basado en un socket y un protocolo fácilmente parseable, y otro optimizado para ser usado por humanos, mediante un sitio web
hosteado en el propio agente, el cual atiende en el puerto 2010.
Bobot introduce el concepto de driver, en el cual se codifica el protocolo que utilizan los ''usermodules'' de esta forma se exponen al usuario del sistema bobot los servicios que implementan los ''usermodules'' ocultando los detalles relacionados con el protocolo de intercambio de mensajes.
Para desarrollar compatibilidad con un nuevo dispositivo electronico en la plataforma USB4all utilizando bobot para su control, se debe primero desarrollar el ''usermodule'' necesario como fue descripto en la sección: Escribiendo un ''usermodule'' luego se debe escribir el driver correspondiente a ese ''usermodule''.
El driver está escrito en Lua y esta implementado como una tabla aprovechando la característica de de este lenguaje en el que las funciones son miembros de primer orden, esto permite que una función pueda ser un tipo de datos válido, pasar funciones como argumento de funciones o como retorno de las mismas almacenarla en una tabla, entre otras cosas. Por este motivo dentro de la tabla se pueden almacenar funciones donde en la misma se especifican las operaciones que el driver expone, y los tipos de parámetros que recibe. Mucha de ésta información es utilizada por el bobot para generar el sitio web mencionado anteriormente, la cual describe un módulo de usuario otra como el método de la función es utilizada para resolver de forma genérica las invocaciones a los servicios expuestos por el driver.

A continuación se muestra un ejemplo de driver para el módulo de usuario presentado en la sección: Escribiendo un ''usermodule''
<syntaxhighlight lang="lua">
local device = _G
local RD_VERSION = string.char(0x00)
local PRENDER = string.char(0x01)
local APAGAR = string.char(0x02)
local BUZZER_CORTO = string.char(0x03)
local BUZZER_TRIPLE = string.char(0x04)

api={}
api.read_version = {}
api.read_version.parameters = {} --no parameters
api.read_version.returns = {[1]={rname="version", rtype="number"}} --one return
api.read_version.call = function ()
local get_read_version = RD_VERSION
device:send(get_read_version)
local version_response = device:read(2)
local raw_val = string.byte(version_response, 2)
--print("rawval, deg_temp: ", raw_val, deg_temp)
return raw_val
end

api.prender = {}
api.prender.parameters = {} --no parameters
api.prender.returns = {} --no return
api.prender.call = function ()
local write_res, err = device:send(PRENDER)
if write_res then return true else return false end
end

api.apagar = {}
api.apagar.parameters = {} --no parameters
api.apagar.returns = {} --no return
api.apagar.call = function ()
local write_res, err = device:send(APAGAR)
if write_res then return true else return false end
end

api.buzzer_corto = {}
api.buzzer_corto.parameters = {[1]={rname="num", rtype="number"}}
api.buzzer_corto.returns = {} --no return
api.buzzer_corto.call = function (num)
local write_res, err = device:send(BUZZER_CORTO .. string.char(num))
if write_res then return true else return false end
end

api.buzzer_triple = {}
api.buzzer_triple.parameters = {[1]={rname="tiempo1", rtype="number"}, [2]={rname="tiempo2", rtype="number"}, [3]={rname="tiempo3", rtype="number"}}
api.buzzer_triple.returns = {} --no return
api.buzzer_triple.call = function (tiempo1, tiempo2, tiempo3)
local write_res, err = device:send(BUZZER_TRIPLE .. string.char(tiempo1) .. string.char(tiempo2) .. string.char(tiempo3))
if write_res then return true else return false end
end
</syntaxhighlight>

En el ejemplo puede notarse al comparar con el ''usermodule'' presentado de ejemplo, como se realiza el pasaje de parámetros entre el driver y el ''usermodule'', esto corresponde con el protocolo definido por el usuario para codificar los comandos del ''usermodule'' y el orden de los parámetros, este protocolo es llamado en la arquitectura USB4all como ''user protocol''.

Puede descargarse bobot-server desde el git del proyecto butiá en sourceforge.

----

El proyecto USB4all se encuentra disponible bajo licencia GNU/GPL v2 en el [http://sourceforge.net/projects/usb4all/ repositorio sorceforge] 
Este proyecto surge originalmente como un trabajo de [http://www.fing.edu.uy/inco/grupos/mina/pGrado/pgusb tesis de grado] en Ingeniería en Computación de Aguirre, Fernandez y Grossy.

Usb4all

2011-10-05T18:13:12Z

Edgardo: /* Detalles de implementación en el firmware */

== Motivación ==

La motivación de este proyecto se centra en lograr de una manera sencilla, la comunicación entre un sistema computador y un conjunto de dispositivos electrónicos no necesariamente pensados para interactuar con una computadora.
Durante muchos años la única forma de interactuar con dispositivos externos desde a un computador personal (Personal Computer) (PC) fueron los puertos seriales y paralelos, esto llevo a que se utilizaran ampliamente en multiplicidad de dispositivos. Sus principales carácteristicas son su simplicidad de manejo vía software y facilidad de inclusión en distintos dispositivos. En la última década han aparecido nuevos medios o canales de comunicación, tales como Bluetooth, Fidelidad Inalámbrica (Wireless Fidelity) (WiFi), FireWire, Bus Universal en Serie (Universal Serial Bus) (USB), etc. Estos permitieron mejorar las velocidades de comunicación y calidad de datos y lentamente tornaron a los puertos paralelos y seriales en obsoletos, hasta llegar al día de hoy en que se obtienen sólo de manera opcional en los nuevos PC.
Dentro de todas estas nuevas tecnologías que aparecieron la que tuvo mayor aceptación y difusión entre los usuarios fue el USB, debido a su facilidad y versatilidad de escenarios de uso. Esta simplicidad desde el punto de vista del usuario de los dispositivos USB tiene como contrapartida una mayor complejidad para los desarrolladores de software y hardware, lo cual es un gran problema al momento de interactuar con dispositivos electrónicos.
Frente a estas adversidades que presenta el entorno actual aparece la necesidad de buscar una forma de reducir el grado de complejidad y conocimientos necesarios para poder desarrollar
software que utilice la tecnología USB. Al mismo tiempo, se requiere una plataforma base que incorpore componentes de hardware reutilizables y que en conjunto formen una solución genérica
para la comunicación con dispositivos electrónicos diversos.
En el contexto de lo antedicho aparecen un conjunto de desafíos como son el desarrollo de controladores (drivers) y construcción de piezas de hardware que brinde una solución genérica
reutilizable, desplazando el manejo de los casos particulares a componentes específicos. Esto proporciona el beneficio de evitar que cada vez que se necesite conectar un nuevo dispositivo,
se comience desde cero. A su vez permite recuperar y potenciar la característica de facilidad de manejo que poseían los puertos seriales y paralelos, explotando todas las capacidades brindadas
por USB.

== Arquitectura ==

La arquitectura esta compuesta por diferentes componentes, los cuales van a permitir el funcionamiento del sistema desde lo concerniente al hardware como las abstracciones necesarias para manejarlo mediante software. Los componentes principales son:

'''USB4all ''Baseboard'''''

[[Archivo:usb4all2.png|thumb|USB4all Baseboard]]
Es una placa de entrada/salida configurable que se conecta por USB con un sistema computador. El proyecto USB4all es mucho más que una placa de E/S, en sí es una forma de modelar sistemas embebidos, siendo la placa de E/S un componente que fue necesario construir para desarrollar la solución completa. Para la construcción de ésta placa se utilizó un microcontrolador PIC18F4550 de Microchip. Entre las características más destacadas en lo que concierne al proyecto se encuentra el soporte completo del estándar USB, pudiéndose utilizar varias de sus características, como ser diferentes tipos de transferencias y varios canales de comunicación (endpoints).

'''USB4all ''base firmware'''''

Es el firmware más estático, brinda servicios a los usermodules para que puedan utilizar los recursos presentes en la baseboard (timmers, puerto USB, conversores A/D, etc) además de brindar las primitivas para el intercambio de mensajes entre el computador y el usermodule y realiza la gestión de los ''usermodules''. Establece las bases para que los usermodules sean independientes del protocolo de comunicación computador/placa y de los detalles de hardware del microcontrolador utilizado. A su vez oferce un entorno de ejecución concurrente que permite instanciar de forma dinámica varios ''usermodules''.

'''USB4all ''usermodule'''''
Son los componentes intercambiables del sistema que permiten encapsular la lógica de un dispositivo especifico y su protocolo de comunicación con las aplicaciones de usuario. Permite al usuario dar rápidamente soporte a un nuevo dispositivo de forma genérica, expandiendo de ésta manera las funcionalidades del USB4all ''basefirmware''. Los ''user modules'' son los bloques principales sobre los que se construye la arquitectura USB4all. Exponen una API uniforme que es utilizada a modo de callbacks por el ''base firmware'' y también exponen los servicios que brindan los dispositivos. Es recomendable modelar cada uno de los dispositivos electrónicos conectados a la ''baseboard'' como un ''usermodule'' donde los servicios a exponer se mapean con las características del mismo, como ejemplo en el caso de un motor, sería esperable que expusiera servicios para moverse, cambiar la velocidad y el sentido.

Del lado del sistema computador se dispone de diferentes formas de interacción: Todas ellas implementan el protocolo USB4all, su objetivo es abstraer al usuario del mismo brindando una forma sencilla de utilizar el sistema, existiendo soporte para diferentes lenguajes de programación. El objetivo principal de las bibliotecas utilizadas en el computador son las de permitir utilizar los servicios de los ''usermodules''. Esta forma de trabajo permite desarrollar la lógica de interacción entre los diferentes dispositivos electrónicos dentro del sistema computador, con lenguajes de mayor abstracción, mejores herramientas de desarrollo, permitiendo generar un código con un nivel de mantenibilidad y abstracción mayor al que se lograría si todo estuviera embebido en el microcontrolador.

Uno de los componentes más usados actualmente es el bobot que persigue un enfoque genérico al igual que el proyecto USB4all y permite acompañar la extensibilidad de la placa USB4all mediante el uso de ciertos componentes propios de la arquitectura llamados drivers.

== Protocolo de Comunicación ==

==Grabando el Firmware ==

Para grabar el firmware se necesita disponer de un programador, como el picdem o el pickit, este último tiene buen soporte dentro de GNU/Linux
Microchip disrtibuye un bootloader para ésta familia de microcontroladores, el cual permite grabar el firmware sin la necesidad de disponer de un programador, para realizar esto es necesario dejar prescionado el botón de programación (botón más cercano al led) mientras se resetea la placa con el botón de reset.
Una vez que el dispositivo se encuentra en modo programación su identificador de producto cambia de 000c a 000b, esto puede verificarse utilizando el comando ''lsusb'' cuya salida se adjunta para los dos casos a continuación:

Id dispositivo USB4all
Bus 002 Device 002: ID 04d8:000c Microchip Technology, Inc.

id dispositivo Bootloader
Bus 002 Device 003: ID 04d8:000b Microchip Technology, Inc.

La versión 2.0 de la placa USB4all utiliza un bootloader modificado que permite actualizar el firmware programáticamente sin necesidad de prescionar los botones.
La misma puede encontrarse en el repositorio en el directorio bootloader del firmware, es un proyecto separado y una ves compilado su grabación se realiza mediante un programador por hardware como picdem o pickit.
Una vez grabado el bootloader ya no es necesario utilizar programadores por hardware y puede realizarse la grabación del firmware mediante varios programas que implementan el protocolo de grabación de firmware de microchip. Una de esas utilidades es el programa fsusb el cual puede encontrarse en [http://www.internetking.org/fsusb/] y es de código libre. Su uso se realiza de la siguiente forma:

./fsusb --program usb4all2.hex

Donde usb4all2.hex es el binario generado como resultado de compilar el proyecto. Recordar que el hardware debe de estar en modo bootloader para poder recibir el firmware.

== Entorno de desarrollo ==
[[Archivo:piklab.png|thumb|Entorno de desarrollor con piklab]]
Una de las opciones posibles para trabajar en un ambiente GNU/Linux es instalar el Piklab, Piklab es un entorno de desarrollo para trabajar con microcontroladores PIC, el proyecto USB4all utiliza el compilador C18 de Microchip el cual solo está disponible para Windows, para hacerlo funcionar se utiliza wine y se debe configurar el toolchain C18 en piklab para que apunte correctamente a los directorios donde se encuentra el compilador C18.
Una limitante que posee este compilador es que no permite rutas de archivos que sean muy largas, lo cual es fácilmente alcanzado utilizando wine, por lo tanto se recomienda que el proyecto este lo más cercano a la raíz posible.
Más información sobre la configuración de c18 con piklab en linux ver: [http://cantareus.com/2009/08/18f4550-and-18f2550-with-piklab-and-ubuntu/]
Otra opción es utilizar MPlab que actualmente trae soporte para GNU/Linux [http://microchip.wikidot.com/mplab:_start]
En el repositorio USB4all puede descargarse un proyecto ya armado para trabajar con piklab, compilando contra c18 mediante wine. Luego de compilar, cargar el binario en la placa mediante el uso del bootloader que se incluye en el firmware, utilizando la utilidad fsusb como fue descripto en la sección Grabando el Firmware.

== Escribiendo un ''usermodule'' ==
[[Archivo:user_module.png|thumb|tabla de referencias a ''user modules'']]

Un ''usermodule'' debe cumplir con una API determinada, de esta manera es posible agregar las funcionalidades que el módulo expone, dentro del ''basefirmware''.
Las operaciones principales que se deben implementar son las encargadas de atender los eventos de:
* inicialización
* liberación de recursos
* configuración

Estas operaciones se ejecutan en determinados momentos del ciclo de vida de una aplicación USB4all, siendo la operación registrada al evento de inicialización invocada al abrir desde la aplicación el ''usermodule'' y la de liberación de recursos al cerrarlo, esto permite utilizar los recursos del microcontrolador solo cuando es necesario. La operación de configuración puede invocarse en cualquier momento para cambiar en caliente algún aspecto de configuración del hardware.
A comenzar un ''usermodule'' se debe declarar cuales van a ser las funciones que van a atender estos eventos y el nombre del módulo para ser identificado desde el computador al listar los módulos presentes en la placa.

#pragma romdata user
uTab userBuzzerModuleTable = {&UserBuzzerInit,&UserBuzzerRelease,&UserBuzzerConfigure,"buzzer"};
#pragma code

Donde user es el nombre de la sección y uTab es una estructura para almacenar las posiciones de memoria de las operaciones que exporta el módulo y su nombre.

Como argumento a la operación init se recibe el número de handler asignado al módulo, este número es utilizado como argumento en otras operaciones como ser ''setHandlerReceiveFunction'' la cual recibe por parámetro el handler y un puntero a la función encargada de manejar la recepción de datos. Otra operación similar es ''getSharedBuffer'' que recibe por parámetro el ''handlerID'' del módulo y retorna un buffer por el cual el módulo puede enviar datos a la aplicación que ejecuta en el computador.
Un buen lugar para obtener éste buffer y registrar la función de recepción de datos es la operación encargada del evento de inicialización
<syntaxhighlight lang="C"> void UserBuzzerInit(byte i) {
usrBuzzerHandler = i;
// add my receive function to the handler module, to be called automatically when the pc sends data to the user module
setHandlerReceiveFunction(usrBuzzerHandler,&UserBuzzerReceived);
// initialize the send buffer, used to send data to the PC
sendBufferUsrBuzzer = getSharedBuffer(usrBuzzerHandler);
}//end UserBuzzerInit </syntaxhighlight>

La función de recepción de datos es la encargada de implementar el protocolo de comunicación entre el ''usermodule'' y la aplicación, típicamente es un case en el que se espera por los diferentes comandos que pueden enviarse. La forma de codificar el pedido de servicios es mediante mensajes del tipo <comando><argumento1>...<argumentoN>. La respuesta debe ser del tipo <comando><resultado1>...<resultadoN>. El buffer para enviar datos al computador es obtenido como argumento de la función y el buffer para enviar datos fue obtenido previamente en la función de inicialización.

<syntaxhighlight lang="C"> void UserBuzzerReceived(byte* recBuffPtr, byte len){
byte index;
byte j;
byte userBuzzerCounter = 0;
byte tiempo;

switch(((BUZZER_DATA_PACKET*)recBuffPtr)->CMD){
case READ_VERSION:
//dataPacket._byte[1] is len
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[2] = BUZZER_MINOR_VERSION;
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[3] = BUZZER_MAJOR_VERSION;
userBuzzerCounter = 0x04;
break;

case PRENDER:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_on();
userBuzzerCounter = 0x02;
break;

case APAGAR:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_off();
userBuzzerCounter = 0x02;
break;

case BUZZER_TRIPLE:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks1 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1]);
cantTicks2 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[2]);
cantTicks3 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[3]);
boubleBeep(cantTicks1, cantTicks2, cantTicks3);
userBuzzerCounter = 0x02;
break;

case BUZZER_CORTO:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks3 = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
timeOutTicksBuzz = 1; // lo seteo timmer para que venza inmediantamente
buzzerState = DELAY;
registerT0event(0, &buzzEvent);
userBuzzerCounter = 0x02;
break;

case RESET:
Reset();
break;

default:
break;
}//end switch(s)
if(userBuzzerCounter != 0){
j = 255;
while(mUSBGenTxIsBusy() && j-->0); // pruebo un máximo de 255 veces
if(!mUSBGenTxIsBusy())
USBGenWrite2(usrBuzzerHandler, userBuzzerCounter);
}//end if
}//end UserBuzzerReceived</syntaxhighlight>

En este ejemplo se puede apreciar como se reciben los pedidos de comandos desde la aplicación que ejecuta en el computador y como se obtienen los parámetros necesarios para implementar los comandos y se devuelven los datos (en caso de ser requeridos) a la aplicación.

'''Entrada/Salida en user modules:'''
Una de las tareas más importantes de los ''usermodules'' es la de realizar entrada/salida con diferentes periféricos electrónicos. Para realizar ésta tarea existen dos paradigmas:
 
* Polling
* Interrupciones
 
Dentro de la arquitectura USB4all existen formas de que los módulos implementen entrada/salida utilizando estos paradigmas, para el caso de pooling existe un servicio que permite registrar una función para ser ejecutada cuando el procesador este disponible.

<syntaxhighlight lang="C">
addPollingFunction(&UserBuzzerProcessIO);
</syntaxhighlight>

Existe soporte para interrupciones mediante el módulo ''DynamicISR'' el cual permite que otros módulos se registren para ser notificados cuando ocurren interrupciones.

<syntaxhighlight lang="C">
addISRFunction(&timmerISRFunction);
</syntaxhighlight>

Una forma que mantiene alta la cohesión del sistema es registrar módulos que se encarguen de esperar un evento en particular y brinde una interfaz para que los ''usermodules'' se registren para ser notificados de eventos generados por el componente de hardware que esta siendo modelado. Hoy día se dispone del módulo T0service que se encarga de brindar servicio de timmers a los ''usermodules''. Al igual que el resto de los componentes funciona registrando funciones que son invocadas por el ''basefirmware''

También existen funciones para desregistrar los ''usermodules'' de las notificaciones, es conveniente realizar la desregistración en la función que implementa el evento de liberación de recursos del módulo.

Por ahora el único componente de hardware del microcontrolador modelado de esta forma es el timmer, pero puede escalarse a otros que requieran ser compartidos por más de un módulo.
Hay que recordar que la concurrencia implementada es puramente colaborativa entre ''usermodules'' por lo cual se debe tener especial cuidado al programar las funciones que atienden estos eventos ya que si se queda "colgada" va a degradar la disponibilidad de todo el sistema.

Para agregar el usermodule a la placa de entrada salida usb4all ''baseboard'' se debe agregar al proyecto en piklab el módulo y realizar la compilación del proyecto

== Detalles de implementación en el firmware ==

El firmware está organizado en diferentes área que se mapean en secciones definidas dentro de la memoria ROM correspondiente a la memoria de programa del microcontrolador, para implementar esto se necesita especificar en un archivo llamado linker script dónde están alojadas físicamente(en memoria) estas secciones.
La forma de realizar este mapeo es editando el archivo lrk asociado al proyecto.
Existe la directiva CODEPAGE que es utilizada para trabajar con las secciones de programa, permite inicializar datos, constantes, y referencias externas. Tiene el siguiente formato

CODEPAGE NAME=memName START=addr END=addr [PROTECTED] [FILL=fillvalue]

donde:
memName es un string ASCII utilizado para identificar una CODEPAGE.

== Bobot ==
[[Archivo:bobot.png|thumb|bobot logo]][[Archivo:web_bobot.png|thumb|Interacción con dispositivo USB4all de forma web]]
bobot-server (version 2) es un servicio que permite acceder a aplicaciones y usuarios interactuar con dispositivos USB4all.
Consiste en un agente altamente portable y liviano, que exporta la funcionalidad de los dispositivos USB4all presentes de una forma fácil de usar. Ofrece dos métodos de acceso,
uno optimizado para aplicaciones, basado en un socket y un protocolo fácilmente parseable, y otro optimizado para ser usado por humanos, mediante un sitio web
hosteado en el propio agente, el cual atiende en el puerto 2010.
Bobot introduce el concepto de driver, en el cual se codifica el protocolo que utilizan los ''usermodules'' de esta forma se exponen al usuario del sistema bobot los servicios que implementan los ''usermodules'' ocultando los detalles relacionados con el protocolo de intercambio de mensajes.
Para desarrollar compatibilidad con un nuevo dispositivo electronico en la plataforma USB4all utilizando bobot para su control, se debe primero desarrollar el ''usermodule'' necesario como fue descripto en la sección: Escribiendo un ''usermodule'' luego se debe escribir el driver correspondiente a ese ''usermodule''.
El driver está escrito en Lua y esta implementado como una tabla aprovechando la característica de de este lenguaje en el que las funciones son miembros de primer orden, esto permite que una función pueda ser un tipo de datos válido, pasar funciones como arguemnto de funciones o como retorno de las mismas almcenarla en una tabla, entre otras cosas. Por este motivo dentro de la tabla se pueden almacenar funciones donde en la misma se especifican las operaciones que el driver expone, los tipos de parametros que recibe y de que tipo son los mismos. Mucha de ésta información es utilizada por el bobot para generar el sitio web mencionado anteriormente, la cual describe un módulo de usuario otra como el método de la función es utilizada para resolver de forma genérica las invocaciones a los servicios expuestos por el driver.

A continuación se muestra un ejemplo de driver para el módulo de usuario presentado en la sección: Escribiendo un ''usermodule''
<syntaxhighlight lang="lua">
local device = _G
local RD_VERSION = string.char(0x00)
local PRENDER = string.char(0x01)
local APAGAR = string.char(0x02)
local BUZZER_CORTO = string.char(0x03)
local BUZZER_TRIPLE = string.char(0x04)

api={}
api.read_version = {}
api.read_version.parameters = {} --no parameters
api.read_version.returns = {[1]={rname="version", rtype="number"}} --one return
api.read_version.call = function ()
local get_read_version = RD_VERSION
device:send(get_read_version)
local version_response = device:read(2)
local raw_val = string.byte(version_response, 2)
--print("rawval, deg_temp: ", raw_val, deg_temp)
return raw_val
end

api.prender = {}
api.prender.parameters = {} --no parameters
api.prender.returns = {} --no return
api.prender.call = function ()
local write_res, err = device:send(PRENDER)
if write_res then return true else return false end
end

api.apagar = {}
api.apagar.parameters = {} --no parameters
api.apagar.returns = {} --no return
api.apagar.call = function ()
local write_res, err = device:send(APAGAR)
if write_res then return true else return false end
end

api.buzzer_corto = {}
api.buzzer_corto.parameters = {[1]={rname="num", rtype="number"}}
api.buzzer_corto.returns = {} --no return
api.buzzer_corto.call = function (num)
local write_res, err = device:send(BUZZER_CORTO .. string.char(num))
if write_res then return true else return false end
end

api.buzzer_triple = {}
api.buzzer_triple.parameters = {[1]={rname="tiempo1", rtype="number"}, [2]={rname="tiempo2", rtype="number"}, [3]={rname="tiempo3", rtype="number"}}
api.buzzer_triple.returns = {} --no return
api.buzzer_triple.call = function (tiempo1, tiempo2, tiempo3)
local write_res, err = device:send(BUZZER_TRIPLE .. string.char(tiempo1) .. string.char(tiempo2) .. string.char(tiempo3))
if write_res then return true else return false end
end
</syntaxhighlight>

En el ejemplo puede notarse al comparar con el ''usermodule'' presentado de ejemplo, como se realiza el pasaje de parámetros entre el driver y el ''usermodule'', esto corresponde con el protocolo definido por el usuario para codificar los comandos del ''usermodule'' y el orden de los parámetros, este protocolo es llamado en la arquitectura USB4all como ''user protocol''.

Puede descargarse bobot-server desde el git del proyecto butiá en sourceforge.

----

El proyecto USB4all se encuentra disponible bajo licencia GNU/GPL v2 en el [http://sourceforge.net/projects/usb4all/ repositorio sorceforge] 
Este proyecto surge originalmente como un trabajo de [http://www.fing.edu.uy/inco/grupos/mina/pGrado/pgusb tesis de grado] en Ingeniería en Computación de Aguirre, Fernandez y Grossy.

Usb4all

2011-10-05T15:05:48Z

Edgardo: /* Escribiendo un usermodule */

== Motivación ==

La motivación de este proyecto se centra en lograr de una manera sencilla, la comunicación entre un sistema computador y un conjunto de dispositivos electrónicos no necesariamente pensados para interactuar con una computadora.
Durante muchos años la única forma de interactuar con dispositivos externos desde a un computador personal (Personal Computer) (PC) fueron los puertos seriales y paralelos, esto llevo a que se utilizaran ampliamente en multiplicidad de dispositivos. Sus principales carácteristicas son su simplicidad de manejo vía software y facilidad de inclusión en distintos dispositivos. En la última década han aparecido nuevos medios o canales de comunicación, tales como Bluetooth, Fidelidad Inalámbrica (Wireless Fidelity) (WiFi), FireWire, Bus Universal en Serie (Universal Serial Bus) (USB), etc. Estos permitieron mejorar las velocidades de comunicación y calidad de datos y lentamente tornaron a los puertos paralelos y seriales en obsoletos, hasta llegar al día de hoy en que se obtienen sólo de manera opcional en los nuevos PC.
Dentro de todas estas nuevas tecnologías que aparecieron la que tuvo mayor aceptación y difusión entre los usuarios fue el USB, debido a su facilidad y versatilidad de escenarios de uso. Esta simplicidad desde el punto de vista del usuario de los dispositivos USB tiene como contrapartida una mayor complejidad para los desarrolladores de software y hardware, lo cual es un gran problema al momento de interactuar con dispositivos electrónicos.
Frente a estas adversidades que presenta el entorno actual aparece la necesidad de buscar una forma de reducir el grado de complejidad y conocimientos necesarios para poder desarrollar
software que utilice la tecnología USB. Al mismo tiempo, se requiere una plataforma base que incorpore componentes de hardware reutilizables y que en conjunto formen una solución genérica
para la comunicación con dispositivos electrónicos diversos.
En el contexto de lo antedicho aparecen un conjunto de desafíos como son el desarrollo de controladores (drivers) y construcción de piezas de hardware que brinde una solución genérica
reutilizable, desplazando el manejo de los casos particulares a componentes específicos. Esto proporciona el beneficio de evitar que cada vez que se necesite conectar un nuevo dispositivo,
se comience desde cero. A su vez permite recuperar y potenciar la característica de facilidad de manejo que poseían los puertos seriales y paralelos, explotando todas las capacidades brindadas
por USB.

== Arquitectura ==

La arquitectura esta compuesta por diferentes componentes, los cuales van a permitir el funcionamiento del sistema desde lo concerniente al hardware como las abstracciones necesarias para manejarlo mediante software. Los componentes principales son:

'''USB4all ''Baseboard'''''

[[Archivo:usb4all2.png|thumb|USB4all Baseboard]]
Es una placa de entrada/salida configurable que se conecta por USB con un sistema computador. El proyecto USB4all es mucho más que una placa de E/S, en sí es una forma de modelar sistemas embebidos, siendo la placa de E/S un componente que fue necesario construir para desarrollar la solución completa. Para la construcción de ésta placa se utilizó un microcontrolador PIC18F4550 de Microchip. Entre las características más destacadas en lo que concierne al proyecto se encuentra el soporte completo del estándar USB, pudiéndose utilizar varias de sus características, como ser diferentes tipos de transferencias y varios canales de comunicación (endpoints).

'''USB4all ''base firmware'''''

Es el firmware más estático, brinda servicios a los usermodules para que puedan utilizar los recursos presentes en la baseboard (timmers, puerto USB, conversores A/D, etc) además de brindar las primitivas para el intercambio de mensajes entre el computador y el usermodule y realiza la gestión de los ''usermodules''. Establece las bases para que los usermodules sean independientes del protocolo de comunicación computador/placa y de los detalles de hardware del microcontrolador utilizado. A su vez oferce un entorno de ejecución concurrente que permite instanciar de forma dinámica varios ''usermodules''.

'''USB4all ''usermodule'''''
Son los componentes intercambiables del sistema que permiten encapsular la lógica de un dispositivo especifico y su protocolo de comunicación con las aplicaciones de usuario. Permite al usuario dar rápidamente soporte a un nuevo dispositivo de forma genérica, expandiendo de ésta manera las funcionalidades del USB4all ''basefirmware''. Los ''user modules'' son los bloques principales sobre los que se construye la arquitectura USB4all. Exponen una API uniforme que es utilizada a modo de callbacks por el ''base firmware'' y también exponen los servicios que brindan los dispositivos. Es recomendable modelar cada uno de los dispositivos electrónicos conectados a la ''baseboard'' como un ''usermodule'' donde los servicios a exponer se mapean con las características del mismo, como ejemplo en el caso de un motor, sería esperable que expusiera servicios para moverse, cambiar la velocidad y el sentido.

Del lado del sistema computador se dispone de diferentes formas de interacción: Todas ellas implementan el protocolo USB4all, su objetivo es abstraer al usuario del mismo brindando una forma sencilla de utilizar el sistema, existiendo soporte para diferentes lenguajes de programación. El objetivo principal de las bibliotecas utilizadas en el computador son las de permitir utilizar los servicios de los ''usermodules''. Esta forma de trabajo permite desarrollar la lógica de interacción entre los diferentes dispositivos electrónicos dentro del sistema computador, con lenguajes de mayor abstracción, mejores herramientas de desarrollo, permitiendo generar un código con un nivel de mantenibilidad y abstracción mayor al que se lograría si todo estuviera embebido en el microcontrolador.

Uno de los componentes más usados actualmente es el bobot que persigue un enfoque genérico al igual que el proyecto USB4all y permite acompañar la extensibilidad de la placa USB4all mediante el uso de ciertos componentes propios de la arquitectura llamados drivers.

== Protocolo de Comunicación ==

==Grabando el Firmware ==

Para grabar el firmware se necesita disponer de un programador, como el picdem o el pickit, este último tiene buen soporte dentro de GNU/Linux
Microchip disrtibuye un bootloader para ésta familia de microcontroladores, el cual permite grabar el firmware sin la necesidad de disponer de un programador, para realizar esto es necesario dejar prescionado el botón de programación (botón más cercano al led) mientras se resetea la placa con el botón de reset.
Una vez que el dispositivo se encuentra en modo programación su identificador de producto cambia de 000c a 000b, esto puede verificarse utilizando el comando ''lsusb'' cuya salida se adjunta para los dos casos a continuación:

Id dispositivo USB4all
Bus 002 Device 002: ID 04d8:000c Microchip Technology, Inc.

id dispositivo Bootloader
Bus 002 Device 003: ID 04d8:000b Microchip Technology, Inc.

La versión 2.0 de la placa USB4all utiliza un bootloader modificado que permite actualizar el firmware programáticamente sin necesidad de prescionar los botones.
La misma puede encontrarse en el repositorio en el directorio bootloader del firmware, es un proyecto separado y una ves compilado su grabación se realiza mediante un programador por hardware como picdem o pickit.
Una vez grabado el bootloader ya no es necesario utilizar programadores por hardware y puede realizarse la grabación del firmware mediante varios programas que implementan el protocolo de grabación de firmware de microchip. Una de esas utilidades es el programa fsusb el cual puede encontrarse en [http://www.internetking.org/fsusb/] y es de código libre. Su uso se realiza de la siguiente forma:

./fsusb --program usb4all2.hex

Donde usb4all2.hex es el binario generado como resultado de compilar el proyecto. Recordar que el hardware debe de estar en modo bootloader para poder recibir el firmware.

== Entorno de desarrollo ==
[[Archivo:piklab.png|thumb|Entorno de desarrollor con piklab]]
Una de las opciones posibles para trabajar en un ambiente GNU/Linux es instalar el Piklab, Piklab es un entorno de desarrollo para trabajar con microcontroladores PIC, el proyecto USB4all utiliza el compilador C18 de Microchip el cual solo está disponible para Windows, para hacerlo funcionar se utiliza wine y se debe configurar el toolchain C18 en piklab para que apunte correctamente a los directorios donde se encuentra el compilador C18.
Una limitante que posee este compilador es que no permite rutas de archivos que sean muy largas, lo cual es fácilmente alcanzado utilizando wine, por lo tanto se recomienda que el proyecto este lo más cercano a la raíz posible.
Más información sobre la configuración de c18 con piklab en linux ver: [http://cantareus.com/2009/08/18f4550-and-18f2550-with-piklab-and-ubuntu/]
Otra opción es utilizar MPlab que actualmente trae soporte para GNU/Linux [http://microchip.wikidot.com/mplab:_start]
En el repositorio USB4all puede descargarse un proyecto ya armado para trabajar con piklab, compilando contra c18 mediante wine. Luego de compilar, cargar el binario en la placa mediante el uso del bootloader que se incluye en el firmware, utilizando la utilidad fsusb como fue descripto en la sección Grabando el Firmware.

== Escribiendo un ''usermodule'' ==
[[Archivo:user_module.png|thumb|tabla de referencias a ''user modules'']]

Un ''usermodule'' debe cumplir con una API determinada, de esta manera es posible agregar las funcionalidades que el módulo expone, dentro del ''basefirmware''.
Las operaciones principales que se deben implementar son las encargadas de atender los eventos de:
* inicialización
* liberación de recursos
* configuración

Estas operaciones se ejecutan en determinados momentos del ciclo de vida de una aplicación USB4all, siendo la operación registrada al evento de inicialización invocada al abrir desde la aplicación el ''usermodule'' y la de liberación de recursos al cerrarlo, esto permite utilizar los recursos del microcontrolador solo cuando es necesario. La operación de configuración puede invocarse en cualquier momento para cambiar en caliente algún aspecto de configuración del hardware.
A comenzar un ''usermodule'' se debe declarar cuales van a ser las funciones que van a atender estos eventos y el nombre del módulo para ser identificado desde el computador al listar los módulos presentes en la placa.

#pragma romdata user
uTab userBuzzerModuleTable = {&UserBuzzerInit,&UserBuzzerRelease,&UserBuzzerConfigure,"buzzer"};
#pragma code

Donde user es el nombre de la sección y uTab es una estructura para almacenar las posiciones de memoria de las operaciones que exporta el módulo y su nombre.

Como argumento a la operación init se recibe el número de handler asignado al módulo, este número es utilizado como argumento en otras operaciones como ser ''setHandlerReceiveFunction'' la cual recibe por parámetro el handler y un puntero a la función encargada de manejar la recepción de datos. Otra operación similar es ''getSharedBuffer'' que recibe por parámetro el ''handlerID'' del módulo y retorna un buffer por el cual el módulo puede enviar datos a la aplicación que ejecuta en el computador.
Un buen lugar para obtener éste buffer y registrar la función de recepción de datos es la operación encargada del evento de inicialización
<syntaxhighlight lang="C"> void UserBuzzerInit(byte i) {
usrBuzzerHandler = i;
// add my receive function to the handler module, to be called automatically when the pc sends data to the user module
setHandlerReceiveFunction(usrBuzzerHandler,&UserBuzzerReceived);
// initialize the send buffer, used to send data to the PC
sendBufferUsrBuzzer = getSharedBuffer(usrBuzzerHandler);
}//end UserBuzzerInit </syntaxhighlight>

La función de recepción de datos es la encargada de implementar el protocolo de comunicación entre el ''usermodule'' y la aplicación, típicamente es un case en el que se espera por los diferentes comandos que pueden enviarse. La forma de codificar el pedido de servicios es mediante mensajes del tipo <comando><argumento1>...<argumentoN>. La respuesta debe ser del tipo <comando><resultado1>...<resultadoN>. El buffer para enviar datos al computador es obtenido como argumento de la función y el buffer para enviar datos fue obtenido previamente en la función de inicialización.

<syntaxhighlight lang="C"> void UserBuzzerReceived(byte* recBuffPtr, byte len){
byte index;
byte j;
byte userBuzzerCounter = 0;
byte tiempo;

switch(((BUZZER_DATA_PACKET*)recBuffPtr)->CMD){
case READ_VERSION:
//dataPacket._byte[1] is len
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[2] = BUZZER_MINOR_VERSION;
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[3] = BUZZER_MAJOR_VERSION;
userBuzzerCounter = 0x04;
break;

case PRENDER:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_on();
userBuzzerCounter = 0x02;
break;

case APAGAR:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_off();
userBuzzerCounter = 0x02;
break;

case BUZZER_TRIPLE:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks1 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1]);
cantTicks2 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[2]);
cantTicks3 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[3]);
boubleBeep(cantTicks1, cantTicks2, cantTicks3);
userBuzzerCounter = 0x02;
break;

case BUZZER_CORTO:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks3 = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
timeOutTicksBuzz = 1; // lo seteo timmer para que venza inmediantamente
buzzerState = DELAY;
registerT0event(0, &buzzEvent);
userBuzzerCounter = 0x02;
break;

case RESET:
Reset();
break;

default:
break;
}//end switch(s)
if(userBuzzerCounter != 0){
j = 255;
while(mUSBGenTxIsBusy() && j-->0); // pruebo un máximo de 255 veces
if(!mUSBGenTxIsBusy())
USBGenWrite2(usrBuzzerHandler, userBuzzerCounter);
}//end if
}//end UserBuzzerReceived</syntaxhighlight>

En este ejemplo se puede apreciar como se reciben los pedidos de comandos desde la aplicación que ejecuta en el computador y como se obtienen los parámetros necesarios para implementar los comandos y se devuelven los datos (en caso de ser requeridos) a la aplicación.

'''Entrada/Salida en user modules:'''
Una de las tareas más importantes de los ''usermodules'' es la de realizar entrada/salida con diferentes periféricos electrónicos. Para realizar ésta tarea existen dos paradigmas:
 
* Polling
* Interrupciones
 
Dentro de la arquitectura USB4all existen formas de que los módulos implementen entrada/salida utilizando estos paradigmas, para el caso de pooling existe un servicio que permite registrar una función para ser ejecutada cuando el procesador este disponible.

<syntaxhighlight lang="C">
addPollingFunction(&UserBuzzerProcessIO);
</syntaxhighlight>

Existe soporte para interrupciones mediante el módulo ''DynamicISR'' el cual permite que otros módulos se registren para ser notificados cuando ocurren interrupciones.

<syntaxhighlight lang="C">
addISRFunction(&timmerISRFunction);
</syntaxhighlight>

Una forma que mantiene alta la cohesión del sistema es registrar módulos que se encarguen de esperar un evento en particular y brinde una interfaz para que los ''usermodules'' se registren para ser notificados de eventos generados por el componente de hardware que esta siendo modelado. Hoy día se dispone del módulo T0service que se encarga de brindar servicio de timmers a los ''usermodules''. Al igual que el resto de los componentes funciona registrando funciones que son invocadas por el ''basefirmware''

También existen funciones para desregistrar los ''usermodules'' de las notificaciones, es conveniente realizar la desregistración en la función que implementa el evento de liberación de recursos del módulo.

Por ahora el único componente de hardware del microcontrolador modelado de esta forma es el timmer, pero puede escalarse a otros que requieran ser compartidos por más de un módulo.
Hay que recordar que la concurrencia implementada es puramente colaborativa entre ''usermodules'' por lo cual se debe tener especial cuidado al programar las funciones que atienden estos eventos ya que si se queda "colgada" va a degradar la disponibilidad de todo el sistema.

Para agregar el usermodule a la placa de entrada salida usb4all ''baseboard'' se debe agregar al proyecto en piklab el módulo y realizar la compilación del proyecto

== Detalles de implementación en el firmware ==

El firmware está organizado en diferentes área que se mapean en secciones definidos dentro de la memoria ROM correspondiente a la memoria del programa del microcontrolador, para implementar esto se necesita especificar en un archivo llamado linker script donde físicamente estan alojadas estas secciones.
La forma de realizar este mapeo es editando en el archivo lrk asociado al proyecto.
Existe la directiva CODEPAGE que es utilizada para trabajar con las secciones de programa, permite inicializar datos, constantes, y referencias externas. Tiene el siguiente formato

CODEPAGE NAME=memName START=addr END=addr [PROTECTED] [FILL=fillvalue]

donde:
memName es un string ASCII utilizado para identificar una CODEPAGE.

== Bobot ==
[[Archivo:bobot.png|thumb|bobot logo]][[Archivo:web_bobot.png|thumb|Interacción con dispositivo USB4all de forma web]]
bobot-server (version 2) es un servicio que permite acceder a aplicaciones y usuarios interactuar con dispositivos USB4all.
Consiste en un agente altamente portable y liviano, que exporta la funcionalidad de los dispositivos USB4all presentes de una forma fácil de usar. Ofrece dos métodos de acceso,
uno optimizado para aplicaciones, basado en un socket y un protocolo fácilmente parseable, y otro optimizado para ser usado por humanos, mediante un sitio web
hosteado en el propio agente, el cual atiende en el puerto 2010.
Bobot introduce el concepto de driver, en el cual se codifica el protocolo que utilizan los ''usermodules'' de esta forma se exponen al usuario del sistema bobot los servicios que implementan los ''usermodules'' ocultando los detalles relacionados con el protocolo de intercambio de mensajes.
Para desarrollar compatibilidad con un nuevo dispositivo electronico en la plataforma USB4all utilizando bobot para su control, se debe primero desarrollar el ''usermodule'' necesario como fue descripto en la sección: Escribiendo un ''usermodule'' luego se debe escribir el driver correspondiente a ese ''usermodule''.
El driver está escrito en Lua y esta implementado como una tabla aprovechando la característica de de este lenguaje en el que las funciones son miembros de primer orden, esto permite que una función pueda ser un tipo de datos válido, pasar funciones como arguemnto de funciones o como retorno de las mismas almcenarla en una tabla, entre otras cosas. Por este motivo dentro de la tabla se pueden almacenar funciones donde en la misma se especifican las operaciones que el driver expone, los tipos de parametros que recibe y de que tipo son los mismos. Mucha de ésta información es utilizada por el bobot para generar el sitio web mencionado anteriormente, la cual describe un módulo de usuario otra como el método de la función es utilizada para resolver de forma genérica las invocaciones a los servicios expuestos por el driver.

A continuación se muestra un ejemplo de driver para el módulo de usuario presentado en la sección: Escribiendo un ''usermodule''
<syntaxhighlight lang="lua">
local device = _G
local RD_VERSION = string.char(0x00)
local PRENDER = string.char(0x01)
local APAGAR = string.char(0x02)
local BUZZER_CORTO = string.char(0x03)
local BUZZER_TRIPLE = string.char(0x04)

api={}
api.read_version = {}
api.read_version.parameters = {} --no parameters
api.read_version.returns = {[1]={rname="version", rtype="number"}} --one return
api.read_version.call = function ()
local get_read_version = RD_VERSION
device:send(get_read_version)
local version_response = device:read(2)
local raw_val = string.byte(version_response, 2)
--print("rawval, deg_temp: ", raw_val, deg_temp)
return raw_val
end

api.prender = {}
api.prender.parameters = {} --no parameters
api.prender.returns = {} --no return
api.prender.call = function ()
local write_res, err = device:send(PRENDER)
if write_res then return true else return false end
end

api.apagar = {}
api.apagar.parameters = {} --no parameters
api.apagar.returns = {} --no return
api.apagar.call = function ()
local write_res, err = device:send(APAGAR)
if write_res then return true else return false end
end

api.buzzer_corto = {}
api.buzzer_corto.parameters = {[1]={rname="num", rtype="number"}}
api.buzzer_corto.returns = {} --no return
api.buzzer_corto.call = function (num)
local write_res, err = device:send(BUZZER_CORTO .. string.char(num))
if write_res then return true else return false end
end

api.buzzer_triple = {}
api.buzzer_triple.parameters = {[1]={rname="tiempo1", rtype="number"}, [2]={rname="tiempo2", rtype="number"}, [3]={rname="tiempo3", rtype="number"}}
api.buzzer_triple.returns = {} --no return
api.buzzer_triple.call = function (tiempo1, tiempo2, tiempo3)
local write_res, err = device:send(BUZZER_TRIPLE .. string.char(tiempo1) .. string.char(tiempo2) .. string.char(tiempo3))
if write_res then return true else return false end
end
</syntaxhighlight>

En el ejemplo puede notarse al comparar con el ''usermodule'' presentado de ejemplo, como se realiza el pasaje de parámetros entre el driver y el ''usermodule'', esto corresponde con el protocolo definido por el usuario para codificar los comandos del ''usermodule'' y el orden de los parámetros, este protocolo es llamado en la arquitectura USB4all como ''user protocol''.

Puede descargarse bobot-server desde el git del proyecto butiá en sourceforge.

----

El proyecto USB4all se encuentra disponible bajo licencia GNU/GPL v2 en el [http://sourceforge.net/projects/usb4all/ repositorio sorceforge] 
Este proyecto surge originalmente como un trabajo de [http://www.fing.edu.uy/inco/grupos/mina/pGrado/pgusb tesis de grado] en Ingeniería en Computación de Aguirre, Fernandez y Grossy.

Usb4all

2011-10-05T15:02:10Z

Edgardo: /* Entorno de desarrollo */

== Motivación ==

La motivación de este proyecto se centra en lograr de una manera sencilla, la comunicación entre un sistema computador y un conjunto de dispositivos electrónicos no necesariamente pensados para interactuar con una computadora.
Durante muchos años la única forma de interactuar con dispositivos externos desde a un computador personal (Personal Computer) (PC) fueron los puertos seriales y paralelos, esto llevo a que se utilizaran ampliamente en multiplicidad de dispositivos. Sus principales carácteristicas son su simplicidad de manejo vía software y facilidad de inclusión en distintos dispositivos. En la última década han aparecido nuevos medios o canales de comunicación, tales como Bluetooth, Fidelidad Inalámbrica (Wireless Fidelity) (WiFi), FireWire, Bus Universal en Serie (Universal Serial Bus) (USB), etc. Estos permitieron mejorar las velocidades de comunicación y calidad de datos y lentamente tornaron a los puertos paralelos y seriales en obsoletos, hasta llegar al día de hoy en que se obtienen sólo de manera opcional en los nuevos PC.
Dentro de todas estas nuevas tecnologías que aparecieron la que tuvo mayor aceptación y difusión entre los usuarios fue el USB, debido a su facilidad y versatilidad de escenarios de uso. Esta simplicidad desde el punto de vista del usuario de los dispositivos USB tiene como contrapartida una mayor complejidad para los desarrolladores de software y hardware, lo cual es un gran problema al momento de interactuar con dispositivos electrónicos.
Frente a estas adversidades que presenta el entorno actual aparece la necesidad de buscar una forma de reducir el grado de complejidad y conocimientos necesarios para poder desarrollar
software que utilice la tecnología USB. Al mismo tiempo, se requiere una plataforma base que incorpore componentes de hardware reutilizables y que en conjunto formen una solución genérica
para la comunicación con dispositivos electrónicos diversos.
En el contexto de lo antedicho aparecen un conjunto de desafíos como son el desarrollo de controladores (drivers) y construcción de piezas de hardware que brinde una solución genérica
reutilizable, desplazando el manejo de los casos particulares a componentes específicos. Esto proporciona el beneficio de evitar que cada vez que se necesite conectar un nuevo dispositivo,
se comience desde cero. A su vez permite recuperar y potenciar la característica de facilidad de manejo que poseían los puertos seriales y paralelos, explotando todas las capacidades brindadas
por USB.

== Arquitectura ==

La arquitectura esta compuesta por diferentes componentes, los cuales van a permitir el funcionamiento del sistema desde lo concerniente al hardware como las abstracciones necesarias para manejarlo mediante software. Los componentes principales son:

'''USB4all ''Baseboard'''''

[[Archivo:usb4all2.png|thumb|USB4all Baseboard]]
Es una placa de entrada/salida configurable que se conecta por USB con un sistema computador. El proyecto USB4all es mucho más que una placa de E/S, en sí es una forma de modelar sistemas embebidos, siendo la placa de E/S un componente que fue necesario construir para desarrollar la solución completa. Para la construcción de ésta placa se utilizó un microcontrolador PIC18F4550 de Microchip. Entre las características más destacadas en lo que concierne al proyecto se encuentra el soporte completo del estándar USB, pudiéndose utilizar varias de sus características, como ser diferentes tipos de transferencias y varios canales de comunicación (endpoints).

'''USB4all ''base firmware'''''

Es el firmware más estático, brinda servicios a los usermodules para que puedan utilizar los recursos presentes en la baseboard (timmers, puerto USB, conversores A/D, etc) además de brindar las primitivas para el intercambio de mensajes entre el computador y el usermodule y realiza la gestión de los ''usermodules''. Establece las bases para que los usermodules sean independientes del protocolo de comunicación computador/placa y de los detalles de hardware del microcontrolador utilizado. A su vez oferce un entorno de ejecución concurrente que permite instanciar de forma dinámica varios ''usermodules''.

'''USB4all ''usermodule'''''
Son los componentes intercambiables del sistema que permiten encapsular la lógica de un dispositivo especifico y su protocolo de comunicación con las aplicaciones de usuario. Permite al usuario dar rápidamente soporte a un nuevo dispositivo de forma genérica, expandiendo de ésta manera las funcionalidades del USB4all ''basefirmware''. Los ''user modules'' son los bloques principales sobre los que se construye la arquitectura USB4all. Exponen una API uniforme que es utilizada a modo de callbacks por el ''base firmware'' y también exponen los servicios que brindan los dispositivos. Es recomendable modelar cada uno de los dispositivos electrónicos conectados a la ''baseboard'' como un ''usermodule'' donde los servicios a exponer se mapean con las características del mismo, como ejemplo en el caso de un motor, sería esperable que expusiera servicios para moverse, cambiar la velocidad y el sentido.

Del lado del sistema computador se dispone de diferentes formas de interacción: Todas ellas implementan el protocolo USB4all, su objetivo es abstraer al usuario del mismo brindando una forma sencilla de utilizar el sistema, existiendo soporte para diferentes lenguajes de programación. El objetivo principal de las bibliotecas utilizadas en el computador son las de permitir utilizar los servicios de los ''usermodules''. Esta forma de trabajo permite desarrollar la lógica de interacción entre los diferentes dispositivos electrónicos dentro del sistema computador, con lenguajes de mayor abstracción, mejores herramientas de desarrollo, permitiendo generar un código con un nivel de mantenibilidad y abstracción mayor al que se lograría si todo estuviera embebido en el microcontrolador.

Uno de los componentes más usados actualmente es el bobot que persigue un enfoque genérico al igual que el proyecto USB4all y permite acompañar la extensibilidad de la placa USB4all mediante el uso de ciertos componentes propios de la arquitectura llamados drivers.

== Protocolo de Comunicación ==

==Grabando el Firmware ==

Para grabar el firmware se necesita disponer de un programador, como el picdem o el pickit, este último tiene buen soporte dentro de GNU/Linux
Microchip disrtibuye un bootloader para ésta familia de microcontroladores, el cual permite grabar el firmware sin la necesidad de disponer de un programador, para realizar esto es necesario dejar prescionado el botón de programación (botón más cercano al led) mientras se resetea la placa con el botón de reset.
Una vez que el dispositivo se encuentra en modo programación su identificador de producto cambia de 000c a 000b, esto puede verificarse utilizando el comando ''lsusb'' cuya salida se adjunta para los dos casos a continuación:

Id dispositivo USB4all
Bus 002 Device 002: ID 04d8:000c Microchip Technology, Inc.

id dispositivo Bootloader
Bus 002 Device 003: ID 04d8:000b Microchip Technology, Inc.

La versión 2.0 de la placa USB4all utiliza un bootloader modificado que permite actualizar el firmware programáticamente sin necesidad de prescionar los botones.
La misma puede encontrarse en el repositorio en el directorio bootloader del firmware, es un proyecto separado y una ves compilado su grabación se realiza mediante un programador por hardware como picdem o pickit.
Una vez grabado el bootloader ya no es necesario utilizar programadores por hardware y puede realizarse la grabación del firmware mediante varios programas que implementan el protocolo de grabación de firmware de microchip. Una de esas utilidades es el programa fsusb el cual puede encontrarse en [http://www.internetking.org/fsusb/] y es de código libre. Su uso se realiza de la siguiente forma:

./fsusb --program usb4all2.hex

Donde usb4all2.hex es el binario generado como resultado de compilar el proyecto. Recordar que el hardware debe de estar en modo bootloader para poder recibir el firmware.

== Entorno de desarrollo ==
[[Archivo:piklab.png|thumb|Entorno de desarrollor con piklab]]
Una de las opciones posibles para trabajar en un ambiente GNU/Linux es instalar el Piklab, Piklab es un entorno de desarrollo para trabajar con microcontroladores PIC, el proyecto USB4all utiliza el compilador C18 de Microchip el cual solo está disponible para Windows, para hacerlo funcionar se utiliza wine y se debe configurar el toolchain C18 en piklab para que apunte correctamente a los directorios donde se encuentra el compilador C18.
Una limitante que posee este compilador es que no permite rutas de archivos que sean muy largas, lo cual es fácilmente alcanzado utilizando wine, por lo tanto se recomienda que el proyecto este lo más cercano a la raíz posible.
Más información sobre la configuración de c18 con piklab en linux ver: [http://cantareus.com/2009/08/18f4550-and-18f2550-with-piklab-and-ubuntu/]
Otra opción es utilizar MPlab que actualmente trae soporte para GNU/Linux [http://microchip.wikidot.com/mplab:_start]
En el repositorio USB4all puede descargarse un proyecto ya armado para trabajar con piklab, compilando contra c18 mediante wine. Luego de compilar, cargar el binario en la placa mediante el uso del bootloader que se incluye en el firmware, utilizando la utilidad fsusb como fue descripto en la sección Grabando el Firmware.

== Escribiendo un ''usermodule'' ==
[[Archivo:user_module.png|thumb|tabla de referencias a ''user modules'']]

Un ''usermodule'' debe cumplir con una API determinada, de esta manera es posible agregar las funcionalidades que él módulo expone, dentro del ''basefirmware''.
Las operaciones principales que se deben implementar son las encargadas de atender los eventos de:
* inicialización
* liberación de recursos
* configuración

Estas operaciones se ejecutan en determinados momentos del ciclo de vida de una aplicación USB4all, siendo la operación registrada al evento de inicialización invocada al abrir desde la aplicación el ''usermodule'' y la de liberación de recursos al cerrarlo, esto permite utilizar los recursos del microcontrolador solo cuando es necesario. La operación de configuración puede invocarse en cualquier momento para cambiar en caliente algún aspecto de configuración del hardware.
A comenzar un ''usermodule'' se debe declarar cuales van a ser las funciones que van a atender estos eventos y el nombre del módulo para ser identificado desde el computador al listar los módulos presentes en la placa.

#pragma romdata user
uTab userBuzzerModuleTable = {&UserBuzzerInit,&UserBuzzerRelease,&UserBuzzerConfigure,"buzzer"};
#pragma code

Donde user es el nombre de la sección y uTab es un estructura para almacenar las posiciones de memoria de las operaciones que exporta el módulo y su nombre.

Como argumento a la operación init se recibe el número de handler asignado al módulo, este número es utilizado como argumento en otras operaciones como ser ''setHandlerReceiveFunction'' la cual recibe por parámetro el handler y un puntero a la función encargada de manejar la recepción de datos. Otra operación similar es ''getSharedBuffer'' que recibe por parámetro el ''handlerID'' del módulo y retorna un buffer por el cual el módulo puede enviar datos a la aplicación que ejecuta en el computador.
Un buen lugar para obtener éste buffer y registrar la función de recepción de datos es la operación encargada del evento de inicialización
<syntaxhighlight lang="C"> void UserBuzzerInit(byte i) {
usrBuzzerHandler = i;
// add my receive function to the handler module, to be called automatically when the pc sends data to the user module
setHandlerReceiveFunction(usrBuzzerHandler,&UserBuzzerReceived);
// initialize the send buffer, used to send data to the PC
sendBufferUsrBuzzer = getSharedBuffer(usrBuzzerHandler);
}//end UserBuzzerInit </syntaxhighlight>

La función de recepción de datos es la encargada de implementar el protocolo de comunicación entre el ''usermodule'' y la aplicación, típicamente es un case en el que se espera por los diferentes comandos que pueden eviarse. La forma de codificar el pedido de servicios es mediante mensajes del tipo <comando><argumento1>...<argumentoN>. La respuesta debe ser del tipo <comando><resultado1>...<resultadoN>. El buffer para enviar datos al computador es obtenido como argumento de la función y el buffer para enviar datos fue obtenido previamente en la función de inicialización.

<syntaxhighlight lang="C"> void UserBuzzerReceived(byte* recBuffPtr, byte len){
byte index;
byte j;
byte userBuzzerCounter = 0;
byte tiempo;

switch(((BUZZER_DATA_PACKET*)recBuffPtr)->CMD){
case READ_VERSION:
//dataPacket._byte[1] is len
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[2] = BUZZER_MINOR_VERSION;
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[3] = BUZZER_MAJOR_VERSION;
userBuzzerCounter = 0x04;
break;

case PRENDER:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_on();
userBuzzerCounter = 0x02;
break;

case APAGAR:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_off();
userBuzzerCounter = 0x02;
break;

case BUZZER_TRIPLE:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks1 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1]);
cantTicks2 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[2]);
cantTicks3 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[3]);
boubleBeep(cantTicks1, cantTicks2, cantTicks3);
userBuzzerCounter = 0x02;
break;

case BUZZER_CORTO:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks3 = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
timeOutTicksBuzz = 1; // lo seteo timmer para que venza inmediantamente
buzzerState = DELAY;
registerT0event(0, &buzzEvent);
userBuzzerCounter = 0x02;
break;

case RESET:
Reset();
break;

default:
break;
}//end switch(s)
if(userBuzzerCounter != 0){
j = 255;
while(mUSBGenTxIsBusy() && j-->0); // pruebo un máximo de 255 veces
if(!mUSBGenTxIsBusy())
USBGenWrite2(usrBuzzerHandler, userBuzzerCounter);
}//end if
}//end UserBuzzerReceived</syntaxhighlight>

En este ejemplo se puede apreciar como se reciben los pedidos de comandos desde la aplicación que ejecuta en el computador y como se obtienen los parámetros necesarios para implementar los comandos y se devueleven los datos (en caso de ser requeridos) a la aplicación.

'''Entrada/Salida en user modules:'''
Una de las tareas más importantes de los ''usermodules'' es la de realizar entrada/salida con diferentes periféricos electrónicos. Para realizar ésta tarea existen dos paradigmas:
 
* Polling
* Interrupciones
 
Dentro de la arquitectura USB4all existen formas de que los módulos implementen entrada/salida utilizando estos paradigmas, para el caso de pooling existe un servicio que permite registrar una función para ser ejecutada cuando el procesador este disponible.

<syntaxhighlight lang="C">
addPollingFunction(&UserBuzzerProcessIO);
</syntaxhighlight>

Existe soporte para interrupciones mediante el módulo ''DynamicISR'' el cual permite que otros módulos se registren para ser notificados cuando ocurren interrupciones.

<syntaxhighlight lang="C">
addISRFunction(&timmerISRFunction);
</syntaxhighlight>

Una forma que mantiene alta la cohesión del sistema es registrar módulos que se encarguen de esperar un evento en particular y brinde una interfaz para que los ''usermodules'' se registren para ser notificados de eventos generados por el componente de hardware que esta siendo modelado. Hoy día se dispone del módulo T0service que se encarga de brindar servicio de timmers a los ''usermodules''. Al igual que el resto de los componentes funciona registrando funciones que son invocadas por el ''basefirmware''

También existen funciones para desregistrar los ''usermodules'' de las notificaciones, es conveniente realizar la desregistración en la función que implementa el evento de liberación de recursos del módulo.

Por ahora el único componente de hardware del microcontrolador modelado de esta forma es el timmer, pero puede escalarse a otros que requieran ser compartidos por más de un módulo.
Hay que recordar que la concurrencia implementada es puramente colaborativa entre ''usermodules'' por lo cual se debe tener especial cuidado al programar las funciones que atienden estos eventos ya que si se queda "colgada" va a degradar la disponibilidad de todo el sistema.

Para agregar el usermodule a la placa de entrada salida usb4all ''baseboard'' se debe agregar al proyecto en piklab el módulo y realizar la compilación del proyecto

== Detalles de implementación en el firmware ==

El firmware está organizado en diferentes área que se mapean en secciones definidos dentro de la memoria ROM correspondiente a la memoria del programa del microcontrolador, para implementar esto se encesita especificar en un archivo llamado linker script donde físicamente estan alojadas estas secciones.

//TODO completar esto

Linker script files are the command files of the linker. They specify:
• Program and data memory regions for the target part
• Stack size and location (for MPLAB C18)
• A mapping of logical sections in source code into program and data regions

The CODEPAGE directive is used for program code, initialized data values, constant data values and external memory. It has the following format:
CODEPAGE NAME=memName START=addr END=addr [PROTECTED] [FILL=fillvalue]

where:
memName is any ASCII string used to identify a CODEPAGE.

== Bobot ==
[[Archivo:bobot.png|thumb|bobot logo]][[Archivo:web_bobot.png|thumb|Interacción con dispositivo USB4all de forma web]]
bobot-server (version 2) es un servicio que permite acceder a aplicaciones y usuarios interactuar con dispositivos USB4all.
Consiste en un agente altamente portable y liviano, que exporta la funcionalidad de los dispositivos USB4all presentes de una forma fácil de usar. Ofrece dos métodos de acceso,
uno optimizado para aplicaciones, basado en un socket y un protocolo fácilmente parseable, y otro optimizado para ser usado por humanos, mediante un sitio web
hosteado en el propio agente, el cual atiende en el puerto 2010.
Bobot introduce el concepto de driver, en el cual se codifica el protocolo que utilizan los ''usermodules'' de esta forma se exponen al usuario del sistema bobot los servicios que implementan los ''usermodules'' ocultando los detalles relacionados con el protocolo de intercambio de mensajes.
Para desarrollar compatibilidad con un nuevo dispositivo electronico en la plataforma USB4all utilizando bobot para su control, se debe primero desarrollar el ''usermodule'' necesario como fue descripto en la sección: Escribiendo un ''usermodule'' luego se debe escribir el driver correspondiente a ese ''usermodule''.
El driver está escrito en Lua y esta implementado como una tabla aprovechando la característica de de este lenguaje en el que las funciones son miembros de primer orden, esto permite que una función pueda ser un tipo de datos válido, pasar funciones como arguemnto de funciones o como retorno de las mismas almcenarla en una tabla, entre otras cosas. Por este motivo dentro de la tabla se pueden almacenar funciones donde en la misma se especifican las operaciones que el driver expone, los tipos de parametros que recibe y de que tipo son los mismos. Mucha de ésta información es utilizada por el bobot para generar el sitio web mencionado anteriormente, la cual describe un módulo de usuario otra como el método de la función es utilizada para resolver de forma genérica las invocaciones a los servicios expuestos por el driver.

A continuación se muestra un ejemplo de driver para el módulo de usuario presentado en la sección: Escribiendo un ''usermodule''
<syntaxhighlight lang="lua">
local device = _G
local RD_VERSION = string.char(0x00)
local PRENDER = string.char(0x01)
local APAGAR = string.char(0x02)
local BUZZER_CORTO = string.char(0x03)
local BUZZER_TRIPLE = string.char(0x04)

api={}
api.read_version = {}
api.read_version.parameters = {} --no parameters
api.read_version.returns = {[1]={rname="version", rtype="number"}} --one return
api.read_version.call = function ()
local get_read_version = RD_VERSION
device:send(get_read_version)
local version_response = device:read(2)
local raw_val = string.byte(version_response, 2)
--print("rawval, deg_temp: ", raw_val, deg_temp)
return raw_val
end

api.prender = {}
api.prender.parameters = {} --no parameters
api.prender.returns = {} --no return
api.prender.call = function ()
local write_res, err = device:send(PRENDER)
if write_res then return true else return false end
end

api.apagar = {}
api.apagar.parameters = {} --no parameters
api.apagar.returns = {} --no return
api.apagar.call = function ()
local write_res, err = device:send(APAGAR)
if write_res then return true else return false end
end

api.buzzer_corto = {}
api.buzzer_corto.parameters = {[1]={rname="num", rtype="number"}}
api.buzzer_corto.returns = {} --no return
api.buzzer_corto.call = function (num)
local write_res, err = device:send(BUZZER_CORTO .. string.char(num))
if write_res then return true else return false end
end

api.buzzer_triple = {}
api.buzzer_triple.parameters = {[1]={rname="tiempo1", rtype="number"}, [2]={rname="tiempo2", rtype="number"}, [3]={rname="tiempo3", rtype="number"}}
api.buzzer_triple.returns = {} --no return
api.buzzer_triple.call = function (tiempo1, tiempo2, tiempo3)
local write_res, err = device:send(BUZZER_TRIPLE .. string.char(tiempo1) .. string.char(tiempo2) .. string.char(tiempo3))
if write_res then return true else return false end
end
</syntaxhighlight>

En el ejemplo puede notarse al comparar con el ''usermodule'' presentado de ejemplo, como se realiza el pasaje de parámetros entre el driver y el ''usermodule'', esto corresponde con el protocolo definido por el usuario para codificar los comandos del ''usermodule'' y el orden de los parámetros, este protocolo es llamado en la arquitectura USB4all como ''user protocol''.

Puede descargarse bobot-server desde el git del proyecto butiá en sourceforge.

----

El proyecto USB4all se encuentra disponible bajo licencia GNU/GPL v2 en el [http://sourceforge.net/projects/usb4all/ repositorio sorceforge] 
Este proyecto surge originalmente como un trabajo de [http://www.fing.edu.uy/inco/grupos/mina/pGrado/pgusb tesis de grado] en Ingeniería en Computación de Aguirre, Fernandez y Grossy.

Usb4all

2011-10-05T14:59:08Z

Edgardo: /* Arquitectura */

== Motivación ==

La motivación de este proyecto se centra en lograr de una manera sencilla, la comunicación entre un sistema computador y un conjunto de dispositivos electrónicos no necesariamente pensados para interactuar con una computadora.
Durante muchos años la única forma de interactuar con dispositivos externos desde a un computador personal (Personal Computer) (PC) fueron los puertos seriales y paralelos, esto llevo a que se utilizaran ampliamente en multiplicidad de dispositivos. Sus principales carácteristicas son su simplicidad de manejo vía software y facilidad de inclusión en distintos dispositivos. En la última década han aparecido nuevos medios o canales de comunicación, tales como Bluetooth, Fidelidad Inalámbrica (Wireless Fidelity) (WiFi), FireWire, Bus Universal en Serie (Universal Serial Bus) (USB), etc. Estos permitieron mejorar las velocidades de comunicación y calidad de datos y lentamente tornaron a los puertos paralelos y seriales en obsoletos, hasta llegar al día de hoy en que se obtienen sólo de manera opcional en los nuevos PC.
Dentro de todas estas nuevas tecnologías que aparecieron la que tuvo mayor aceptación y difusión entre los usuarios fue el USB, debido a su facilidad y versatilidad de escenarios de uso. Esta simplicidad desde el punto de vista del usuario de los dispositivos USB tiene como contrapartida una mayor complejidad para los desarrolladores de software y hardware, lo cual es un gran problema al momento de interactuar con dispositivos electrónicos.
Frente a estas adversidades que presenta el entorno actual aparece la necesidad de buscar una forma de reducir el grado de complejidad y conocimientos necesarios para poder desarrollar
software que utilice la tecnología USB. Al mismo tiempo, se requiere una plataforma base que incorpore componentes de hardware reutilizables y que en conjunto formen una solución genérica
para la comunicación con dispositivos electrónicos diversos.
En el contexto de lo antedicho aparecen un conjunto de desafíos como son el desarrollo de controladores (drivers) y construcción de piezas de hardware que brinde una solución genérica
reutilizable, desplazando el manejo de los casos particulares a componentes específicos. Esto proporciona el beneficio de evitar que cada vez que se necesite conectar un nuevo dispositivo,
se comience desde cero. A su vez permite recuperar y potenciar la característica de facilidad de manejo que poseían los puertos seriales y paralelos, explotando todas las capacidades brindadas
por USB.

== Arquitectura ==

La arquitectura esta compuesta por diferentes componentes, los cuales van a permitir el funcionamiento del sistema desde lo concerniente al hardware como las abstracciones necesarias para manejarlo mediante software. Los componentes principales son:

'''USB4all ''Baseboard'''''

[[Archivo:usb4all2.png|thumb|USB4all Baseboard]]
Es una placa de entrada/salida configurable que se conecta por USB con un sistema computador. El proyecto USB4all es mucho más que una placa de E/S, en sí es una forma de modelar sistemas embebidos, siendo la placa de E/S un componente que fue necesario construir para desarrollar la solución completa. Para la construcción de ésta placa se utilizó un microcontrolador PIC18F4550 de Microchip. Entre las características más destacadas en lo que concierne al proyecto se encuentra el soporte completo del estándar USB, pudiéndose utilizar varias de sus características, como ser diferentes tipos de transferencias y varios canales de comunicación (endpoints).

'''USB4all ''base firmware'''''

Es el firmware más estático, brinda servicios a los usermodules para que puedan utilizar los recursos presentes en la baseboard (timmers, puerto USB, conversores A/D, etc) además de brindar las primitivas para el intercambio de mensajes entre el computador y el usermodule y realiza la gestión de los ''usermodules''. Establece las bases para que los usermodules sean independientes del protocolo de comunicación computador/placa y de los detalles de hardware del microcontrolador utilizado. A su vez oferce un entorno de ejecución concurrente que permite instanciar de forma dinámica varios ''usermodules''.

'''USB4all ''usermodule'''''
Son los componentes intercambiables del sistema que permiten encapsular la lógica de un dispositivo especifico y su protocolo de comunicación con las aplicaciones de usuario. Permite al usuario dar rápidamente soporte a un nuevo dispositivo de forma genérica, expandiendo de ésta manera las funcionalidades del USB4all ''basefirmware''. Los ''user modules'' son los bloques principales sobre los que se construye la arquitectura USB4all. Exponen una API uniforme que es utilizada a modo de callbacks por el ''base firmware'' y también exponen los servicios que brindan los dispositivos. Es recomendable modelar cada uno de los dispositivos electrónicos conectados a la ''baseboard'' como un ''usermodule'' donde los servicios a exponer se mapean con las características del mismo, como ejemplo en el caso de un motor, sería esperable que expusiera servicios para moverse, cambiar la velocidad y el sentido.

Del lado del sistema computador se dispone de diferentes formas de interacción: Todas ellas implementan el protocolo USB4all, su objetivo es abstraer al usuario del mismo brindando una forma sencilla de utilizar el sistema, existiendo soporte para diferentes lenguajes de programación. El objetivo principal de las bibliotecas utilizadas en el computador son las de permitir utilizar los servicios de los ''usermodules''. Esta forma de trabajo permite desarrollar la lógica de interacción entre los diferentes dispositivos electrónicos dentro del sistema computador, con lenguajes de mayor abstracción, mejores herramientas de desarrollo, permitiendo generar un código con un nivel de mantenibilidad y abstracción mayor al que se lograría si todo estuviera embebido en el microcontrolador.

Uno de los componentes más usados actualmente es el bobot que persigue un enfoque genérico al igual que el proyecto USB4all y permite acompañar la extensibilidad de la placa USB4all mediante el uso de ciertos componentes propios de la arquitectura llamados drivers.

== Protocolo de Comunicación ==

==Grabando el Firmware ==

Para grabar el firmware se necesita disponer de un programador, como el picdem o el pickit, este último tiene buen soporte dentro de GNU/Linux
Microchip disrtibuye un bootloader para ésta familia de microcontroladores, el cual permite grabar el firmware sin la necesidad de disponer de un programador, para realizar esto es necesario dejar prescionado el botón de programación (botón más cercano al led) mientras se resetea la placa con el botón de reset.
Una vez que el dispositivo se encuentra en modo programación su identificador de producto cambia de 000c a 000b, esto puede verificarse utilizando el comando ''lsusb'' cuya salida se adjunta para los dos casos a continuación:

Id dispositivo USB4all
Bus 002 Device 002: ID 04d8:000c Microchip Technology, Inc.

id dispositivo Bootloader
Bus 002 Device 003: ID 04d8:000b Microchip Technology, Inc.

La versión 2.0 de la placa USB4all utiliza un bootloader modificado que permite actualizar el firmware programáticamente sin necesidad de prescionar los botones.
La misma puede encontrarse en el repositorio en el directorio bootloader del firmware, es un proyecto separado y una ves compilado su grabación se realiza mediante un programador por hardware como picdem o pickit.
Una vez grabado el bootloader ya no es necesario utilizar programadores por hardware y puede realizarse la grabación del firmware mediante varios programas que implementan el protocolo de grabación de firmware de microchip. Una de esas utilidades es el programa fsusb el cual puede encontrarse en [http://www.internetking.org/fsusb/] y es de código libre. Su uso se realiza de la siguiente forma:

./fsusb --program usb4all2.hex

Donde usb4all2.hex es el binario generado como resultado de compilar el proyecto. Recordar que el hardware debe de estar en modo bootloader para poder recibir el firmware.

== Entorno de desarrollo ==
[[Archivo:piklab.png|thumb|Entorno de desarrollor con piklab]]
Una de las opciones posibles para trabajar en un ambiente GNU/Linux es instalar el Piklab, Piklab es un entorno de desarrollo para trabajar con microcontroladores PIC, el proyecto USB4all utiliza el compilador C18 de Microchip el cual solo está disponible para Windows, para hacerlo funcionar se utiliza wine y se debe configurar el toolchain C18 en piklab para que apunte correctamente a los directorios donde se encuentra el compilador C18.
Una limitante que posee este compilador es que no permite rutas de archivos que sean muy largas, lo cual es fácilmente alcansado utilizando wine, por lo tanto se recomienda que el proyecto este lo más cercano a la raiz posible.
Más información sobre la configuración de c18 con piklab en linux ver: [http://cantareus.com/2009/08/18f4550-and-18f2550-with-piklab-and-ubuntu/]
Otra opción es utilizar MPlab que actualmente trae soporte para GNU/Linux [http://microchip.wikidot.com/mplab:_start]
En el repositorio USB4all puede descargarse un proyecto ya armado para trabajar con piklab, compilando contra c18 mediante wine. Luego de compilar el carga el binario en la placa mediante el uso del bootloader que se incluye en el firmware utilizando la utilidad fsusb como fue descripto en la sección Grabando el Firmware.

== Escribiendo un ''usermodule'' ==
[[Archivo:user_module.png|thumb|tabla de referencias a ''user modules'']]

Un ''usermodule'' debe cumplir con una API determinada, de esta manera es posible agregar las funcionalidades que él módulo expone, dentro del ''basefirmware''.
Las operaciones principales que se deben implementar son las encargadas de atender los eventos de:
* inicialización
* liberación de recursos
* configuración

Estas operaciones se ejecutan en determinados momentos del ciclo de vida de una aplicación USB4all, siendo la operación registrada al evento de inicialización invocada al abrir desde la aplicación el ''usermodule'' y la de liberación de recursos al cerrarlo, esto permite utilizar los recursos del microcontrolador solo cuando es necesario. La operación de configuración puede invocarse en cualquier momento para cambiar en caliente algún aspecto de configuración del hardware.
A comenzar un ''usermodule'' se debe declarar cuales van a ser las funciones que van a atender estos eventos y el nombre del módulo para ser identificado desde el computador al listar los módulos presentes en la placa.

#pragma romdata user
uTab userBuzzerModuleTable = {&UserBuzzerInit,&UserBuzzerRelease,&UserBuzzerConfigure,"buzzer"};
#pragma code

Donde user es el nombre de la sección y uTab es un estructura para almacenar las posiciones de memoria de las operaciones que exporta el módulo y su nombre.

Como argumento a la operación init se recibe el número de handler asignado al módulo, este número es utilizado como argumento en otras operaciones como ser ''setHandlerReceiveFunction'' la cual recibe por parámetro el handler y un puntero a la función encargada de manejar la recepción de datos. Otra operación similar es ''getSharedBuffer'' que recibe por parámetro el ''handlerID'' del módulo y retorna un buffer por el cual el módulo puede enviar datos a la aplicación que ejecuta en el computador.
Un buen lugar para obtener éste buffer y registrar la función de recepción de datos es la operación encargada del evento de inicialización
<syntaxhighlight lang="C"> void UserBuzzerInit(byte i) {
usrBuzzerHandler = i;
// add my receive function to the handler module, to be called automatically when the pc sends data to the user module
setHandlerReceiveFunction(usrBuzzerHandler,&UserBuzzerReceived);
// initialize the send buffer, used to send data to the PC
sendBufferUsrBuzzer = getSharedBuffer(usrBuzzerHandler);
}//end UserBuzzerInit </syntaxhighlight>

La función de recepción de datos es la encargada de implementar el protocolo de comunicación entre el ''usermodule'' y la aplicación, típicamente es un case en el que se espera por los diferentes comandos que pueden eviarse. La forma de codificar el pedido de servicios es mediante mensajes del tipo <comando><argumento1>...<argumentoN>. La respuesta debe ser del tipo <comando><resultado1>...<resultadoN>. El buffer para enviar datos al computador es obtenido como argumento de la función y el buffer para enviar datos fue obtenido previamente en la función de inicialización.

<syntaxhighlight lang="C"> void UserBuzzerReceived(byte* recBuffPtr, byte len){
byte index;
byte j;
byte userBuzzerCounter = 0;
byte tiempo;

switch(((BUZZER_DATA_PACKET*)recBuffPtr)->CMD){
case READ_VERSION:
//dataPacket._byte[1] is len
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[2] = BUZZER_MINOR_VERSION;
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[3] = BUZZER_MAJOR_VERSION;
userBuzzerCounter = 0x04;
break;

case PRENDER:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_on();
userBuzzerCounter = 0x02;
break;

case APAGAR:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
buzzer_off();
userBuzzerCounter = 0x02;
break;

case BUZZER_TRIPLE:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks1 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1]);
cantTicks2 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[2]);
cantTicks3 = (byte)(((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[3]);
boubleBeep(cantTicks1, cantTicks2, cantTicks3);
userBuzzerCounter = 0x02;
break;

case BUZZER_CORTO:
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[0] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[0];
((BUZZER_DATA_PACKET*)sendBufferUsrBuzzer)->_byte[1] = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
cantTicks3 = ((BUZZER_DATA_PACKET*)recBuffPtr)->_byte[1];
timeOutTicksBuzz = 1; // lo seteo timmer para que venza inmediantamente
buzzerState = DELAY;
registerT0event(0, &buzzEvent);
userBuzzerCounter = 0x02;
break;

case RESET:
Reset();
break;

default:
break;
}//end switch(s)
if(userBuzzerCounter != 0){
j = 255;
while(mUSBGenTxIsBusy() && j-->0); // pruebo un máximo de 255 veces
if(!mUSBGenTxIsBusy())
USBGenWrite2(usrBuzzerHandler, userBuzzerCounter);
}//end if
}//end UserBuzzerReceived</syntaxhighlight>

En este ejemplo se puede apreciar como se reciben los pedidos de comandos desde la aplicación que ejecuta en el computador y como se obtienen los parámetros necesarios para implementar los comandos y se devueleven los datos (en caso de ser requeridos) a la aplicación.

'''Entrada/Salida en user modules:'''
Una de las tareas más importantes de los ''usermodules'' es la de realizar entrada/salida con diferentes periféricos electrónicos. Para realizar ésta tarea existen dos paradigmas:
 
* Polling
* Interrupciones
 
Dentro de la arquitectura USB4all existen formas de que los módulos implementen entrada/salida utilizando estos paradigmas, para el caso de pooling existe un servicio que permite registrar una función para ser ejecutada cuando el procesador este disponible.

<syntaxhighlight lang="C">
addPollingFunction(&UserBuzzerProcessIO);
</syntaxhighlight>

Existe soporte para interrupciones mediante el módulo ''DynamicISR'' el cual permite que otros módulos se registren para ser notificados cuando ocurren interrupciones.

<syntaxhighlight lang="C">
addISRFunction(&timmerISRFunction);
</syntaxhighlight>

Una forma que mantiene alta la cohesión del sistema es registrar módulos que se encarguen de esperar un evento en particular y brinde una interfaz para que los ''usermodules'' se registren para ser notificados de eventos generados por el componente de hardware que esta siendo modelado. Hoy día se dispone del módulo T0service que se encarga de brindar servicio de timmers a los ''usermodules''. Al igual que el resto de los componentes funciona registrando funciones que son invocadas por el ''basefirmware''

También existen funciones para desregistrar los ''usermodules'' de las notificaciones, es conveniente realizar la desregistración en la función que implementa el evento de liberación de recursos del módulo.

Por ahora el único componente de hardware del microcontrolador modelado de esta forma es el timmer, pero puede escalarse a otros que requieran ser compartidos por más de un módulo.
Hay que recordar que la concurrencia implementada es puramente colaborativa entre ''usermodules'' por lo cual se debe tener especial cuidado al programar las funciones que atienden estos eventos ya que si se queda "colgada" va a degradar la disponibilidad de todo el sistema.

Para agregar el usermodule a la placa de entrada salida usb4all ''baseboard'' se debe agregar al proyecto en piklab el módulo y realizar la compilación del proyecto

== Detalles de implementación en el firmware ==

El firmware está organizado en diferentes área que se mapean en secciones definidos dentro de la memoria ROM correspondiente a la memoria del programa del microcontrolador, para implementar esto se encesita especificar en un archivo llamado linker script donde físicamente estan alojadas estas secciones.

//TODO completar esto

Linker script files are the command files of the linker. They specify:
• Program and data memory regions for the target part
• Stack size and location (for MPLAB C18)
• A mapping of logical sections in source code into program and data regions

The CODEPAGE directive is used for program code, initialized data values, constant data values and external memory. It has the following format:
CODEPAGE NAME=memName START=addr END=addr [PROTECTED] [FILL=fillvalue]

where:
memName is any ASCII string used to identify a CODEPAGE.

== Bobot ==
[[Archivo:bobot.png|thumb|bobot logo]][[Archivo:web_bobot.png|thumb|Interacción con dispositivo USB4all de forma web]]
bobot-server (version 2) es un servicio que permite acceder a aplicaciones y usuarios interactuar con dispositivos USB4all.
Consiste en un agente altamente portable y liviano, que exporta la funcionalidad de los dispositivos USB4all presentes de una forma fácil de usar. Ofrece dos métodos de acceso,
uno optimizado para aplicaciones, basado en un socket y un protocolo fácilmente parseable, y otro optimizado para ser usado por humanos, mediante un sitio web
hosteado en el propio agente, el cual atiende en el puerto 2010.
Bobot introduce el concepto de driver, en el cual se codifica el protocolo que utilizan los ''usermodules'' de esta forma se exponen al usuario del sistema bobot los servicios que implementan los ''usermodules'' ocultando los detalles relacionados con el protocolo de intercambio de mensajes.
Para desarrollar compatibilidad con un nuevo dispositivo electronico en la plataforma USB4all utilizando bobot para su control, se debe primero desarrollar el ''usermodule'' necesario como fue descripto en la sección: Escribiendo un ''usermodule'' luego se debe escribir el driver correspondiente a ese ''usermodule''.
El driver está escrito en Lua y esta implementado como una tabla aprovechando la característica de de este lenguaje en el que las funciones son miembros de primer orden, esto permite que una función pueda ser un tipo de datos válido, pasar funciones como arguemnto de funciones o como retorno de las mismas almcenarla en una tabla, entre otras cosas. Por este motivo dentro de la tabla se pueden almacenar funciones donde en la misma se especifican las operaciones que el driver expone, los tipos de parametros que recibe y de que tipo son los mismos. Mucha de ésta información es utilizada por el bobot para generar el sitio web mencionado anteriormente, la cual describe un módulo de usuario otra como el método de la función es utilizada para resolver de forma genérica las invocaciones a los servicios expuestos por el driver.

A continuación se muestra un ejemplo de driver para el módulo de usuario presentado en la sección: Escribiendo un ''usermodule''
<syntaxhighlight lang="lua">
local device = _G
local RD_VERSION = string.char(0x00)
local PRENDER = string.char(0x01)
local APAGAR = string.char(0x02)
local BUZZER_CORTO = string.char(0x03)
local BUZZER_TRIPLE = string.char(0x04)

api={}
api.read_version = {}
api.read_version.parameters = {} --no parameters
api.read_version.returns = {[1]={rname="version", rtype="number"}} --one return
api.read_version.call = function ()
local get_read_version = RD_VERSION
device:send(get_read_version)
local version_response = device:read(2)
local raw_val = string.byte(version_response, 2)
--print("rawval, deg_temp: ", raw_val, deg_temp)
return raw_val
end

api.prender = {}
api.prender.parameters = {} --no parameters
api.prender.returns = {} --no return
api.prender.call = function ()
local write_res, err = device:send(PRENDER)
if write_res then return true else return false end
end

api.apagar = {}
api.apagar.parameters = {} --no parameters
api.apagar.returns = {} --no return
api.apagar.call = function ()
local write_res, err = device:send(APAGAR)
if write_res then return true else return false end
end

api.buzzer_corto = {}
api.buzzer_corto.parameters = {[1]={rname="num", rtype="number"}}
api.buzzer_corto.returns = {} --no return
api.buzzer_corto.call = function (num)
local write_res, err = device:send(BUZZER_CORTO .. string.char(num))
if write_res then return true else return false end
end

api.buzzer_triple = {}
api.buzzer_triple.parameters = {[1]={rname="tiempo1", rtype="number"}, [2]={rname="tiempo2", rtype="number"}, [3]={rname="tiempo3", rtype="number"}}
api.buzzer_triple.returns = {} --no return
api.buzzer_triple.call = function (tiempo1, tiempo2, tiempo3)
local write_res, err = device:send(BUZZER_TRIPLE .. string.char(tiempo1) .. string.char(tiempo2) .. string.char(tiempo3))
if write_res then return true else return false end
end
</syntaxhighlight>

En el ejemplo puede notarse al comparar con el ''usermodule'' presentado de ejemplo, como se realiza el pasaje de parámetros entre el driver y el ''usermodule'', esto corresponde con el protocolo definido por el usuario para codificar los comandos del ''usermodule'' y el orden de los parámetros, este protocolo es llamado en la arquitectura USB4all como ''user protocol''.

Puede descargarse bobot-server desde el git del proyecto butiá en sourceforge.

----

El proyecto USB4all se encuentra disponible bajo licencia GNU/GPL v2 en el [http://sourceforge.net/projects/usb4all/ repositorio sorceforge] 
Este proyecto surge originalmente como un trabajo de [http://www.fing.edu.uy/inco/grupos/mina/pGrado/pgusb tesis de grado] en Ingeniería en Computación de Aguirre, Fernandez y Grossy.

Wiki Butiá

2011-06-08T13:14:43Z

Edgardo: /* Proyecto Butiá */

== Proyecto Butiá ==
Este proyecto plantea como objetivo crear una plataforma simple, la cual ponga al alcance de estudiantes escolares o liceales las herramientas necesarias para permitirles interiorizarse en la programación del comportamiento de robots.
Actualmente la implmentación 1.0 del proyecto está siendo utilizado en formato de kit, distribuido a 28 liceos públicos del Uruguay, con un set de sensores y piezas que permiten cambiar la ubicación de los sensores en la plataforma móvil donde se coloca la computadora XO del proyecto OLPC. 
De todas formas el proyecto butiá fue desarrollado de manera que sea muy sencillo agregar nuevos sensores o actuadores, lo cual abre la posibilidad a que usuarios a los cuales les interese aspectos más relacionados con el hardware puedan implementar sus propios sensores y actudores de forma sencilla. Incluso el diseño industrial del robot es abierto lo cual permite realizarlo con materiales reciclados o de bajo costo.

== TortugArte Butiá ==

Tortugarte es una actividad Sugar la cual pone al alcance de niños conceptos de programación, mediante una interfaz icónica, donde cada instrucción se mapea como un bloque.
El proyecto butiá realizó un plugin para TortugArte que permite controlar el Robot Butiá y tomar valores de sus sensores muy fácilmente. 
Dado que el robot Butiá tiene soporte plug and play para los sensores/actuadores que se conectan al mismo son detectados permitiendo cambiar el color de los bloques correspondientes a los elementos de sensado/actuación según lo que se haya conectado al robot. 
Puede descargarse una versión autoinstalable de TortugArte Butia desde el [http://activities.sugarlabs.org/es-ES/sugar/addon/4434 Repositorio de actividades Sugar]

*[[Ejemplos_TortugArteButiá|Ejemplos de comportaminetos que pueden realizarse en tortugarte con el plugin Butiá]]

== Curso módulo taller Butiá ==

* [[proyectos_mtbutia_2011|Proyectos módulo taller butiá 2011]]

* [[proyectos_mtbutia_2010|Proyectos módulo taller butiá 2010]]

== Extensión Universitaria ==

* [[talleres_y_charlas|Talleres y charlas]]

* [[entrega_de_Butiá_V1.0|Entrega de 28 robots Butiá en el evento Sumo.uy 2010]]

== Charlas Butiá ==

* [http://www.fing.edu.uy/inco/proyectos/butia/mediawiki/public/pres_seMINArios_2011_handouts.pdf Charla del robot Butiá el los seMINArios del Instituto de Computación, UdelaR, Montevideo, Uruguay, 2011]

* [http://www.fing.edu.uy/inco/proyectos/butia/mediawiki/public/presCASE2011HandsOut.pdf Charla del robot Butiá en el congreso argentino de sistemas embebidos, Buenos Aires, 2011]

* [http://www.fing.edu.uy/inco/proyectos/butia/mediawiki/public/butia-jornadasANTel-FIng2011.pdf Charla del robot Butiá en las jornadas de telecomunicaciones realizadas, Rocha, Uruguay, 2011]

* [http://www.fing.edu.uy/inco/proyectos/butia/mediawiki/public/presCPBRASIL.pdf Charla del robot Butiá en el campus party, San Pablo, Brasil, 2011]

== Construcción ==

* [[construcción_Butiá_V1.0|Construyendo un Robot Butiáv1.0 paso a paso]]

== Desarrollo ==

La plataforma Butiá fue liberada como software libre a la comunidad y puedes contribuir con el proyecto como desarrollador uniendote en [https://sourceforge.net/projects/butia/ proyecto butiá en sourceforge]

== Empezando ==

Consulta la [http://meta.wikimedia.org/wiki/Ayuda:Contenido Guía de usuario] para obtener información sobre el uso del software wiki.
* [http://www.mediawiki.org/wiki/Manual:Configuration_settings Lista de ajustes de configuración]
* [http://www.mediawiki.org/wiki/Manual:FAQ/es FAQ de MediaWiki]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce Lista de correo de anuncios de distribución de MediaWiki]