Documentation for serdisplib >= V 1.93

DISCLAIMER:
THIS IS EXPERIMENTAL SOFTWARE AND HARDWARE. USE AT YOUR OWN RISK. THE MAINTAINER(S) OF THESE PAGES AND THE DEVELOPER(S) OF SOFTWARE AND HARDWARE PRESENTED ON THESE PAGES CAN NOT BE HELD LIABLE UNDER ANY CIRCUMSTANCES FOR DAMAGE TO HARDWARE OR SOFTWARE, LOST DATA, OR OTHER DIRECT OR INDIRECT DAMAGE RESULTING FROM THE USE OF THIS SOFTWARE OR HARDWARE. IF YOU DO NOT AGREE TO THESE CONDITIONS, YOU ARE NOT PERMITTED TO USE OR FURTHER DISTRIBUTE THIS SOFTWARE OR TO USE ANY TEMPLATES FOR BUILDING HARDWARE PRESENTED HERE.

overview

API changes:

serdisplib v.1.92

The additional support of direct I/O starting with version 1.92 requested a change in the API:
instead of int filehandles a structure ppd (parallel port descriptor) is now used.
serdisp_init() now has an extra parameter that will be used in the future.

serdisplib v.1.93

Starting with version 1.93, more output devices are supported (besides parallel port now also serial port for i2c-displays). This requested another API-change: further infos on changes: HISTORY and README

supported displays

see http://serdisplib.sourceforge.net/index.html#displays for a detailed overview.

serdisp_connect.h: accessing an output device

serdisp_connect.h offers some functions for opening and closing output devices using a descriptor ('sdcd').
supported access methods: The default output-method uses 'ioctl'-calls using device names (eg: /dev/parport0).
serdisplib also supports using direct-IO (using port-addresses and inline-assembler).

pros and cons:

supported output devices: supported operating systems: compile tests for *bsd operating systems where made using sourceforge's compile farm.

either the functions provided by serdisp_connect.h may be used or any other (non-serdisplib) function / code / ... that is returning either a file handle which may be controlled using ioctl-calls or direct I/O using outp-calls. to be able to use such a file handle together with serdisplib it has to to be imported using SDCONN_import_PP() (only parallel port supported for now).

serdisp_control.h: accessing and controlling a display

all elementary functions for controlling a display are defined here

NOTA BENE: only these functions should be used. no descriptor fields or internal functions should be accessed directly as these are subject to change.

messages, error handling, useful defines

serdisplib no longer uses fprintf() for reporting debugging information, errors and warnings, instead of this, syslog is now used.
thus /var/log/messages (or /var/adm/messages depending on operating system used) may contain useful informations.

message and error handling is defined in serdisp_messages.h:

version information and useful defines:

examples

complete example: 
#include <stdio.h>
#include <stdlib.h>

#include "serdisplib/serdisp_connect.h"
#include "serdisplib/serdisp_control.h"
#include "serdisplib/serdisp_messages.h"

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

  char sdcdev[] = "/dev/parport0";  /* use parallel port */
  /*char sdcdev[] = "serport:/dev/ttyS0";*/  /* use serial port */

  char dispname[] = "PCD8544";  /* display name */

  serdisp_CONN_t* sdcd;
  serdisp_t* dd = 0;
  int i;

  /* opening the output device */             
  sdcd = SDCONN_open(sdcdev);
                
  if (sdcd == (serdisp_CONN_t*)0) {        
    fprintf(stderr, "Error opening %s, additional info: %s\n", sdcdev, sd_geterrormsg());
    exit (1);
  }

  /* opening and initialising the display */
  dd = serdisp_init(sdcd, dispname, "");
  if (!dd) {
    SDCONN_close(sdcd);
    fprintf(stderr, "Error opening display %s, additional info: %s\n", dispname, sd_geterrormsg());
    exit(1);
  }


  /* turning on backlight */
  serdisp_feature(dd, FEATURE_BACKLIGHT, FEATURE_YES);

  /* clearing the display */
  serdisp_clear(dd);

  /* draw a border (only internal display buffer is affected!!) */
  for (i = 0; i < serdisp_getwidth(dd); i++) {
    serdisp_setpixel(dd, i, 0, 1);
    serdisp_setpixel(dd, i, serdisp_getheight(dd)-1, 1);
  }  
  for (i = 1; i < serdisp_getheight(dd)-1; i++) {
    serdisp_setpixel(dd, 0, i, 1);
    serdisp_setpixel(dd, serdisp_getwidth(dd)-1, i, 1);
  }

  /* commit changes -> update the display using the internal display buffer */
  serdisp_update(dd);

  /* wait 30 seconds */
  sleep(30);

  /* shutdown display and release device*/
  serdisp_quit(dd);
  
  return(0);
}

open display, draw something, and exit without clearing display: 

  /* initialising, a.s.o.: see example above */
  ...

  /* draw something */
  ...


  /* release display without switching it off / clearing it */
  serdisp_close(dd);
  exit(0);

documentation for former versions

(c) 2003-2004 by wolfgang astleitner // version: 1.93 // 2004-07-18