Display Control 128x64

Proyecto basado en la tarjeta uniandes SAM7S256 by Carol Ximena Naranjo

= Preliminares = Este proyecto utiliza la tarjeta de desarrollo uniandes SAM7S256 como plataforma, y se desarrolla bajo el entorno de desarrollo Yagarto. Remitase a la sección de la tarjeta para conocer más al respecto aquí.

= Descripción = En este tutorial se usa la tarjeta uniandes SAM7S256 como plataforma para controlar un display de 128x64 pixeles con controlador KS0108, se incluirán varios ejemplos de uso del display partiendo de un proyecto base en eclipse adaptado para usar el sistema operativo FreeRTOS creado por Carlos Villarraga. El proyecto base puede descargarlo aquí Descargar, sin embargo más adelante encontrará un proyecto más completo incluyendo las librerías necesarias para usar el display. Para empezar a usar el display se empezará mostrando las conexiones correspondientes del display y los pines utilizados en la plataforma.

=Plano eléctrico =

El display usado aquí tiene dimensiones de 128x64 pixeles y usa un controlador KS0108 como este. Aquí se presenta un esquemático con el conector del display y los pines del microcontrolador AT91SAM7S256 asignados a lo largo de este tutorial. Sin embargo, como se explica más adelante, usted puede modificar la asignación de pines según le convenga, recuerde tener en cuenta la distribución de los pines del micro en la tarjeta de desarrollo uniandes SAM7S256. Verifique el manual de usuario de la tarjeta de desarrollo.

El potenciómetro es para ajustar el contraste de la pantalla. '' La librería contempla la existencia de CS3, en los displays de 128x64 este pin no existe externamente. Favor ignorarlo.''

= Librería KS0108= Para usar el controlador del display se puede consultar directamente el datasheet. Sin embargo, en internet se dispone de librerías útiles para dicho controlador. En este este link podrá encontrar la librería para el controlador con varias configuraciones aptas para diferentes microcontroladores, en este caso se usará el archivo KS0108-AT91.c. Para este caso, la librería se ha adaptado para usar los pines disponibles en la tarjeta uniandes SAM7S256 como se describe más adelante.

Configuración e inicialización de la pantalla
Para empezar a usar la librería debe incluir la librería del controlador en el proyecto editando el archivo Makefile, además de colocar el encabezado correspondiente en el archivo principal main.c, como se muestra aquí:

...
 * 1) include 
 * 2) include 

// Librerías para el uso del display ... int main( void ) {    ... }
 * 1) include "KS0108.h" //inicialización y funciones básicas
 * 2) include "graphic.h" //funciones adicionales de formas y gráficos
 * 3) include "KS0108-AT91.h" //definiciones de pines del display

Para incluir la librería debe modificar el Makefile del proyecto así:

En primer lugar se agrega un path adicional en donde se encuentran las librerías a incluir. En este caso, en la carpeta del proyecto se creó la carpeta ks108 en donde se encuentran las librerías correspondientes al controlador del display: ... GLCD_DIR = ks108 ...
 * 1) Ojo: modifique o adicione paths segun sea el caso

Luego, se debe incluir la carpeta donde se encuentran los archivos .h a utilizar, que en este caso están dentro de la carpeta ks108/include: INCLUDES = -I. ... INCLUDES+= -I$(GLCD_DIR)/include ...
 * 1) Ojo: adicionar o ajustar librerias aqui

Finalmente se deben especificar todos los archivos .c utilizados en el proyecto: THUMB_SOURCE= \ main.c \ ...		$(GLCD_DIR)/include/graphic.c \ $(GLCD_DIR)/include/KS0108.c \ $(GLCD_DIR)/include/KS0108-AT91.c \ ...
 * 1) Ojo: adicionar los archivos en C necesarios aqui

El archivo KS0108-AT91.h incluye las definiciones de los pines utilizados en el microcontrolador. En este caso, se han modificado los pines que vienen por defecto en la librería para adaptarse mejor a la distribución de pines disponibles en la tarjeta uniandes, sin embargo usted puede modificar estos pines según desee. La distribución asignada aquí es:

// Definiciones de pines de display:
 * 1) define KS0108_RS			(1 << 12)
 * 2) define KS0108_RW			(1 << 10)
 * 3) define KS0108_EN			(1 << 8)


 * 1) define KS0108_CS1			(1 << 4)
 * 2) define KS0108_CS2			(1 << 6)
 * 3) define KS0108_D0		16

En esta distribución, d0 indica el pin menos significativo del vector data del display, de igual forma en los pines siguientes del microcontrolador corresponden a los bits consecutivos más significativos del vector data.

Ejemplo: Colocar un punto en la pantalla
A partir del proyecto base con las librerías concluidas se ha creado un ejemplo para colocar un punto en el display. En este ejemplo, dada la simplicidad del mismo por el momento no se está utilizando el sistema operativo FreeRTOS aunque por defecto las librerías se encuentran incluidas. Puede descargar el ejemplo aquí. Para este ejemplo basta con usar la función GLCD_SetPixel( implementada en KS0108.c) en el método main así:

int main( void ) {	Init; //Inicialización de periféricos. De main.c	GLCD_Initialize; //De la librería GLCD_ClearScreen; //De la librería

/* Creacion tareas */ while(1) {		//pinta 3 pixeles alineados horizontalmente en la pantalla GLCD_SetPixel(64,32,1); GLCD_SetPixel(32,32,1); GLCD_SetPixel(96,32,1); } 	return 0; }

Funciones disponibles
Aunque siempre es posible colocar o limpiar un pixel manualmente, la librería disponible cuenta con diferentes funciones útiles en graphic.h/.c que facilitan el uso del display. Entre estas se encuentran GLCD_Rectangle para pintar el contorno de un rectángulo, GLCD_fill para pintar un rectángulo sólido, GLCD_Circle para pintar una circunferencia, GLCD_Line para pintar una línea recta. Estas funciones a su vez se basan en funciones básicas para acceder al display disponibles en KS0108.h/.c, que se explican más adelante.

Colocar una imagen en la pantalla
Entre las funciones con las que cuenta la librería se incluye la función GLCD_Bitmap para colocar una imagen en pantalla, la función permite colocar una imagen con tamaño definido partiendo de una coordenada inicial. En primer lugar, se debe utilizar la aplicación LCDAssistant, que es una herramienta adicional para convertir imágenes en un arreglo de bytes cuya dirección es recibida por la función GLCD_Bitmap de la librería KS0108.h/c. Puede descargar LCDAssistant aquí. En primer lugar se debe crear una imagen de tamaño igual o inferior a 128x64 pixeles; para asegurar que el resultado en el display es el deseado es recomendable usar una imágen monocromática, pues de no serlo la transformación podría no ser la esperada. En paint por ejemplo usted puede configurar el tamaño deseado de la imágen en el menú principal > propiedades, y puede guardar la imagen como "Mapa de bits monocromático":



En la herramienta LCDAssistant se hace la conversión de bitmap a un arreglo de caractéres en c. Primero debe cargarla imagen (File>Load Image) y luego guardar el resultado en la ruta que desee (File>Save Output), la aplicación está comprobada usando las opciones de orientación vertical, little endian y 8 pixeles/byte. El archivo resultante es un archivo de texto plano cuyo contenido es un arreglo de caracteres que deberá incluir en su código de programación. Por comodidad y organización, puede resultar útil colocar los arreglos resultantes en una librería adicional al proyecto (en especial si se desea usar varias imágenes). Para esto es necesario incluir la nueva librería en el encabezado del archivo principal (main.c), y editar el Makefile, de forma similar a como se hizo con las librerías del controlador. Aquí se pone a disposición un proyecto de ejemplo con algunas imágenes a ser mostradas, puede descargar dicho proyecto aquí. Para este ejemplo, se creó la librería imagenes.h (donde están los arreglos de caracteres con las imágenes) incluido en el encabezado de main.c dentro de la carpeta ks108/imagenes. Una vez incluida la librería, puede usar la función GLCD_Bitmap que recibe como parámetros un apuntador a la imagen a pintar, las coordenadas iniciales 'x' y 'y' y el tamaño de la imagen correspondiente. Para este ejemplo se pintan algunas imágenes de diferentes tamaños consecutivamente, el main queda de la siguiente forma:

int main( void ) {	/* llama funcion que inicializa perifericos */

Init; GLCD_Initialize; GLCD_ClearScreen;

/* Creacion tareas */

while(1) {			//Animación x. La misma imagen se pinta corrida 3 veces. GLCD_Bitmap(&nino,0,0,42,64); //Se pasa el apuntador al arreglo de caracteres de la imagen. delay_ms(3600); GLCD_Bitmap(&nino,43,0,42,64); delay_ms(3600); GLCD_Bitmap(&nino,85,0,42,64); delay_ms(3600); GLCD_ClearScreen; } 	return 0; }

En el proyecto disponible en la descarga la animación es un poco más larga. Las imágenes utilizadas están incluidas en la descarga del proyecto dentro de la carpeta imagenes.

Edición de la librería
Aunque la librería cuenta con varias funciones predefinidas útiles, siempre es posible que necesitemos adicionar alguna función en particular. En esta sección se explican los comandos básicos del display, con el fin de hacer modificaciones sencillas de ser necesario. Las funciones básicas para controlar el display están implementadas dentro de KS0108.c y KS0108-AT91.c y son:
 * "void GLCD_GoTo(unsigned char, unsigned char):" Ubica el cursor del display en las cordenadas absolutas x y y pasadas por parámetro. En esta posición se editaran cambios de los 8 pixeles correspondientes al escribir un dato (GLCD_WriteData), o de donde se obtendrá la información si se lee (GLCD_Readdata).
 * "void GLCD_WriteCommand(unsigned char, unsigned char):" Habilita el display en modo de escritura de comandos, y envía el comando en el primer parámetro al controlador que indique el chip select del segundo parámetro.
 * "void GLCD_ClearScreen(void):" Limpia la pantalla.
 * "void GLCD_WriteData(unsigned char):" Habilita el display en modo de escritura de datos para indicar que se deseaa modificar los 8 pixeles correspondientes a la posición actual del cursor, y envía el parámetro pasado al vector DATA del display.
 * "unsigned char GLCD_ReadData(void):" Proporciona información de los 8 pixeles correspondientes a la posición actual del cursor.
 * "unsigned char GLCD_ReadByteFromROMMemory(char *)" : En la ROM del controlador del display se almacenan los caracteres de los que dispone para el soporte de escritura de caracteres en pantalla, es el método usado en la impresión en pantalla de cadenas de caracteres (GLCD_WriteString).
 * "void GLCD_WriteString(char *):" Escribe una cadena de caracteres basandose en la información de la ROM y las definiciones de la librería fotn5x8.h.

A partir de estas funciones están definidas las demás funciones de la librería. Por ejemplo, en la implementación de GLCD_SetPixel dado que el controlador maneja información cada 8 pixeles(vector DATA) la función lee los 8 pixeles de la posición correspondiente en 1 char y coloca un 1 únicamente en el bit del pixel correspondiente a la coordenada pasada por parámentro, byte que luego es escrito en el controlador a traves del DATA: void GLCD_SetPixel(unsigned char x, unsigned char y, unsigned char color) {	unsigned char tmp; GLCD_GoTo(x, (y / 8)); //Ubica el cursor según las coordenadas pasadas por parámetro tmp = GLCD_ReadData; //Lee la información de los 8 pixeles correspondientes tmp |= (1 << (y % 8)); //Coloca 1 en el pixel correspondiente GLCD_WriteData(tmp); //Escribe el nuevo vector de 8 pixeles modificado } Para ilustrar una pequeña modificación, si lo que se quiere ahora es limpiar un pixel, a diferencia del ejemplo anterior, el bit correspondiente deberá tener un cero así: void GLCD_ClearPixel(unsigned char x, unsigned char y) { unsigned char tmp; GLCD_GoTo(x, (y / 8)); tmp = GLCD_ReadData; tmp &= ~(1 << (y % 8)); //Coloca 0 en el pixel correspondiente GLCD_GoTo(x, (y / 8)); GLCD_WriteData(tmp); } De igual forma es fácil realizar diferentes modificaciones a la librería para crear más formas predefinidas(por ejemplo GLCD_fill es una variación de GLCD_Rectangle) u obtener el negativo de una sección del display por ejemplo (esto último no está implementado actualmente, no olvide alimentar la wiki con sus eventuales aportes).

= Videos de demostración =

Ejemplo 2: Progresión de imágenes
SAOvIRSNGUk

Agradecimientos: Al grupo 12 10 ADSD p4 G8 por la toma del video.

= Display en la plataforma Condorboard = La librería del display también ha sido portada a la plataforma CondorBoard bajo la distribución de Linux embebido Angstrom, tanto como un driver (a nivel de kernel), como a nivel de usuario. Para conocer los proyectos correspondientes visite: //Falta! link para el driver del grupo de jumah,zuluaga,jurado Implementación del display 128x64 a nivel de usuario

También se cuenta con una tarjeta para la condorboard a la que se puede adaptar el display de 128x64px, así como uno más pequeño de 7x2 caracteres: LCDBoard

= Descargas =

Herramientas utilizadas

 * Librería para el microcontrolador at91sam7s256 [[Media:ks108.zip|Descargar]]
 * Herramienta LCDAssistant (Bitmap converter) [[Media:LCDAssistant.zip|Descargar]]
 * Entorno de desarrollo: Remitase a la sección "FreeRTOS - Sistema Operativo en Tiempo Real" de la tarjeta de desarrollo uniandes aquí.

Proyectos de ejemplo

 * Ejemplo inicialización - Colocar un punto en la pantalla [[Media:Proyecto_setPixel.zip‎|Descargar]]
 * Ejemplo de imágenes bitmap en el display [[Media:Proyecto_bitmap.zip‎|Descargar]]
 * Ejemplo de uso dentro del sistema operativo FreeRTOS Proyecto Tamagotchi Link

= Bibliografía =
 * Datasheet del microcontrolador AT91SAM7S256 Descargar
 * Tarjeta de desarrollo uniandes SAM7S256 Ir
 * Datasheet del controlador del display KS0108 Descargar
 * Información técnica del display. Descargar
 * Fuente de la librería original para el controlador KS0108Ir