			Kommunikation med microd
			------------------------

Microd har 3 uppgifter.

	vervaka ntpserverns offset/dispersion och tillta eller frbjuda
	inkommande ntpfrgor beroende p offset och dispersionsvrdena.

	Ta emot offset/drift vrden utifrn och uppdatera mikrosteppern
	enligt dessa vrden. Nya berkningar av aktuell offset grs med
	jmna mellanrum fr att stadkomma driftkompensering.

	Svara p frgor utifrn och leverera svar innehllande uppgifter
	om nuvarande offset och vriga instllningar.


Microd kommunicerar normalt med omvrlden via SSL, men kan ven kommunicera
i klartext utan autentisering.

Microd konfigureras med en konfigurationsfil som beskriver hur den skall
uppfra sig. Nyckelorden i den frsta kolumnen kan skrivas med eller utan
versala tecken.
Microd lser normalt sin konfiguration frn /etc/microd.conf, man kan frms
att lsa en annan fil om den anges p kommandoraden.

Typisk konfigurationsfil :

	updateinterval      600
	clientport          273
	ppsdevice           /dev/ppsd0
	offsetfile          /etc/microd.offset
	ntpfilter           yes
	allowresponses      yes
	allowcontrol        no
	deviceaddress       127.127.32.0
	maxoffset           0.000050
	maxdispersion       0.00100
	usessl              yes
	certfile            /etc/certificate/Microd_cert.pem
	keyfile             /etc/certificate/Microd_key.pem
	cafile              /etc/certificate/Cacert.pem
	cipher              RC4-MD5


updateinterval

	Kan ven skrivas interval.
	Anger hur ofta ( i sekunder ) som aktuell offset skall berknas
	med hjlp av de offset och driftvrden som senast mottogs.

clientport

	Kan ven skrivas port.
	Anger vilken tcp port som microd lyssnar p.

ppsdevice

	Kan ven skrivas ppsdev.
	Anger vilken devicefil som anvnds fr att prata med pps-drivrutinen.

offsetfile

	Kan ven skrivas som ofile.
	Anger den fil dr senast mottagna offset/drift lagras.


ntpfilter

	Yes eller true aktiverar vervakningen av ntpserverns
	offset/dispersion och aktivering/inaktivering av mottagna ntpfrgor.
	No eller false deaktiverar vervakningen.

allowresponses

	Kan ven skrivas allowresp. Anvnds bara om ntpfilter r aktiverat.
	Yes eller true tillter inkommande ntpsvar.
	No eller false tillter inte inkommande ntpsvar.

allowcontrol

	Kan ven skrivas allowctrl. Anvnds bara om ntpfilter r aktiverat.
	Yes eller true tillter inkommande ntp-kontrollmeddelanden.
	No eller false tillter inte inkommande ntp-kontrollmeddelanden.

deviceaddress

	Kan ven skrivas devaddr. Anvnds bara om ntpfilter r aktiverat.
	Anger vilken peeradress som motsvarar pps-signalen till ntp.

maxoffset

	Kan ven skrivas maxoff. Anvnds bara om ntpfilter r aktiverat.
	Anger vilken maximal offset ( + eller - ) som tillts fr att
	ntpfrgor skall tilltas.

maxdispersion

	Kan ven skrivas maxdisp. Anvnds bara om ntpfilter r aktiverat.
	Anger vilken maximal dispersion som tillts fr att ntpfrgor skall
	tilltas.

usessl

	Yes eller true anger att all kommunikation med omvrlden skall ske
	med SSL. No eller false anger att all kommunikation sker i klartext.

certfile

	Kan ven skrivas cert. Anvnds bara om usessl r aktiverat.
	Anger vilken fil som innehller microd:s ssl-certifikat.

keyfile

	Kan ven skrivas key. Anvnds bara om usessl r aktiverat.
	Anger vilken fil som innehller microd:s privata nyckel.

cafile

	Kan ven skrivas ca. Anvnds bara om usessl r aktiverat.
	Anger vilken fil som innehller microd:s CA-certifikat.

cipher
	Anvnds bara om usessl r aktiverat.
	Anger vilken typ av kryptering som skall anvndas.



Programmeringsinterface
-----------------------

Microd anvnder en tcpsocket med eller utan SSL fr att kommunicera med
omvrlden. Alla kommandon r uppbyggda p samma stt enligt nedanstende
struktur.

/*
 * Clockevent from pps device driver.
 */
struct ppsclockev {
        struct timeval tv;
        u_int serial;
};

/*
 * Statistic summary from pps device driver.
 */
struct ppsstat {
        int minhw;
        int maxhw;
        int minsys;
        int maxsys;
};

/*
 * Microstepper offset data block.
 */
struct ClockData { int          Offset;         /* Signed offset in ns    */
                   int          Drift;          /* Signed drift in ps/24h */
                   short        Leap;           /* Leap second. -1, 0, +1 */
                   short        Status;         /* Other status bits      */
};

/*
 * Union of all commands.
 */
union Cmds { short              Ecode;          /* Error code             */
             int                NanoSec;        /* Time in ns             */
             int                MicroSec;       /* Time in us             */
             int                Hz;             /* Frequency              */
             int                Mode;           /* Clock mode             */
             struct ppsstat     Stat;           /* Pps statistics         */
             struct ppsclockev  ClockEvent;     /* Event from pps driver  */
             struct ClockData   ClkStatus;      /* Offset data block      */
};

/*
 * Complete command structure.
 */
struct ClkCmd { short           Length;         /* Size of Data + Type    */
                short           Type;           /* Command type code      */
                union Cmds      Data;           /* Command data block     */
};


struct ClkCmd innehller allts det kompletta kommandot som bestr av ett
16-bits lngdflt fljt av ett 16-bits typflt som i sin tur fljs av data
fr det aktuella kommandot identifierat av typfltet.
Kommandots data kan vara tomt eller best av enstaka heltal eller en
sammansatt datastruktur. I samtliga fall r alla dataflt i "network order"
d.v.s. "big endian" eller med andra ord den mest signifikanta byten frst.
Alla kommandon ger ett svar som innehller resultat eller felkod.

De kommandon som har implementerats r :

	CLK_OFFSET		Numeriskt vrde 1.
				Uppdatera offset och driftvrden.
				Dataflt r en "struct ClockData" som
				innehller offset och driftvrden. Leap
				och statusflten anvnds inte nnu.
			Svar :
				Ett datablock av typ CLK_ECODE som innehller
				0 om allt var OK och en felkod annars.

	CLK_GETTIMESTAMP	Numeriskt vrde 2.
				Begr en "struct ppsclockev" frn pps-drivern.
				Inget dataflt anvnds.
			Svar :
				En "struct ppsclockev" i ett datablock av
				typen CLK_TIMESTAMP eller en felkod i ett
				datablock av typen CLK_ECODE.

	CLK_GETMICROSTEP	Numeriskt vrde 4.
				Begr aktuellt mikrosteppervrde i ns.
				Inget dataflt anvnds.
			Svar :
				Ett datablock av typ CLK_MICROSTEP innehllande
				vrdet i ett heltal eller en felkod i ett
				datablock av typen CLK_ECODE.

	CLK_GETPPSOUTPUT	Numeriskt vrde 7.
				Begr aktuellt PPS-utgngsvrde i ns.
				Inget dataflt anvnds.
			Svar :
				Ett datablock av typ CLK_PPSOUTPUT innehllande
				vrdet i ett heltal eller en felkod i ett
				datablock av typen CLK_ECODE.

	CLK_GETMED		Numeriskt vrde 12.
				Begr medianvrdet frn de 3 sista mtningarna
				av skillnaden mellan sekundpulsen och datorns
				interna klocka.
				Inget dataflt anvnds.
			Svar :
				Ett datablock av typ CLK_MED innehllande
				vrdet i ett heltal eller en felkod i ett
				datablock av typen CLK_ECODE.

	CLK_GETHZ		Numeriskt vrde 14.
				Begr aktuell klockfrekvens frn pps-drivern.
				Inget dataflt anvnds.
			Svar :
				Ett datablock av typ CLK_HZ innehllande
				vrdet i ett heltal eller en felkod i ett
				datablock av typen CLK_ECODE.

	CLK_GETCLKMODE		Numeriskt vrde 16.
				Begr aktuell klockmode ( extern/intern )
				frn pps-drivern.
				Inget dataflt anvnds.
			Svar :
				Ett datablock av typ CLK_CLKMODE innehllande
				0 fr extern och 1 fr intern klocka eller en
				felkod i ett datablock av typen CLK_ECODE.
