You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
364 lines
12 KiB
364 lines
12 KiB
#if 0
|
|
INDI
|
|
Copyright (C) 2003 Elwood C. Downey
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the terms of the GNU Lesser General Public
|
|
License as published by the Free Software Foundation; either
|
|
version 2.1 of the License, or (at your option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public
|
|
License along with this library; if not, write to the Free Software
|
|
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
|
|
#endif
|
|
|
|
#ifndef INDI_API_H
|
|
#define INDI_API_H
|
|
|
|
/** \mainpage Instrument Neutral Distributed Interface INDI
|
|
\section Introduction
|
|
|
|
INDI is a simple XML-like communications protocol described for interactive and automated remote control of diverse instrumentation.\n
|
|
|
|
INDI is small, easy to parse, and stateless. In the INDI paradigm each Device poses all command and status functions in terms of settings and getting Properties. Each Property is a vector of one or more names members. Each property has a current value vector; a target value vector; provides information about how it should be sequenced with respect to other Properties to accomplish one coordinated unit of observation; and provides hints as to how it might be displayed for interactive manipulation in a GUI.\n
|
|
|
|
Clients learn the Properties of a particular Device at runtime using introspection. This decouples Client and Device implementation histories. Devices have a complete authority over whether to accept commands from Clients. INDI accommpdates intermediate servers, broadcasting, and connection topologies ranging from one-to-one on a single system to many-to-many between systems of different genre.\n
|
|
|
|
The INDI protocol can be nested within other XML elements such as constraints for automatic scheduling and execution.\n
|
|
|
|
For a complete review on the INDI protocol, please refer to the INDI <a href="http://www.clearskyinstitute.com/INDI/INDI">white paper</a>.
|
|
|
|
\section Audience Intended Audience
|
|
|
|
INDI is intended for developers who seek a scalable API for device control and automation. Hardware drivers written under INDI can be used under any INDI-compatible client. INDI serves as a backend only, you need frontend clients to control devices. Current clients include <a href="http://edu.kde.org/kstars">KStars</a>, <a href="http://www.clearyskyinstitute.com/xephem">Xephem</a>, and <a href="http://www.stargazing.net/astropc">Cartes du Ciel</a>.
|
|
|
|
\section Development Developing under INDI
|
|
|
|
Please refere to the <a href="http://indi.sf.net/manual/">INDI Developers Manual</a> for a complete guide on INDI's driver developemnt framework.
|
|
|
|
\section Help
|
|
|
|
You can find information on INDI development in the <a href="http://indi.sf.net">INDI sourceforge</a> site. Furthermore, you can discuss INDI related issues on the <a href="http://sourceforge.net/mail/?group_id=90275">INDI development mailing list</a>.
|
|
|
|
\author Elwood Downey
|
|
\author Jasem Mutlaq
|
|
*/
|
|
|
|
/** \file indiapi.h
|
|
\brief Constants and Data structure definitions for the interface to the reference INDI C API implementation.
|
|
\author Elwood C. Downey
|
|
*/
|
|
|
|
/*******************************************************************************
|
|
* INDI wire protocol version implemented by this API.
|
|
* N.B. this is indepedent of the API itself.
|
|
*/
|
|
|
|
#define INDIV 1.5
|
|
|
|
/*******************************************************************************
|
|
* Manifest constants
|
|
*/
|
|
|
|
/** \typedef ISState
|
|
\brief Switch state.
|
|
*/
|
|
typedef enum {
|
|
ISS_OFF, ISS_ON
|
|
} ISState; /* switch state */
|
|
|
|
/** \typedef IPState
|
|
\brief Property state.
|
|
*/
|
|
typedef enum {
|
|
IPS_IDLE, IPS_OK, IPS_BUSY, IPS_ALERT
|
|
} IPState; /* property state */
|
|
|
|
/** \typedef ISRule
|
|
\brief Switch vector rule hint.
|
|
*/
|
|
typedef enum {
|
|
ISR_1OFMANY, ISR_ATMOST1, ISR_NOFMANY
|
|
} ISRule; /* switch vector rule hint */
|
|
|
|
/** \typedef IPerm
|
|
\brief Permission hint, with respect to client.
|
|
*/
|
|
typedef enum {
|
|
IP_RO, IP_WO, IP_RW
|
|
} IPerm; /* permission hint, WRT client */
|
|
|
|
/* The XML strings for these attributes may be any length but implementations
|
|
* are only obligued to support these lengths for the various string attributes.
|
|
*/
|
|
#define MAXINDINAME 32
|
|
#define MAXINDILABEL 32
|
|
#define MAXINDIDEVICE 32
|
|
#define MAXINDIGROUP 32
|
|
#define MAXINDIFORMAT 32
|
|
#define MAXINDIBLOBFMT 32
|
|
#define MAXINDITSTAMP 32
|
|
|
|
/*******************************************************************************
|
|
* Typedefs for each INDI Property type.
|
|
*
|
|
* INumber.format may be any printf-style appropriate for double
|
|
* or style "m" to create sexigesimal using the form "%<w>.<f>m" where
|
|
* <w> is the total field width.
|
|
* <f> is the width of the fraction. valid values are:
|
|
* 9 -> :mm:ss.ss
|
|
* 8 -> :mm:ss.s
|
|
* 6 -> :mm:ss
|
|
* 5 -> :mm.m
|
|
* 3 -> :mm
|
|
*
|
|
* examples:
|
|
*
|
|
* to produce use
|
|
*
|
|
* "-123:45" %7.3m
|
|
* " 0:01:02" %9.6m
|
|
*/
|
|
|
|
/** \struct IText
|
|
\brief One text descriptor.
|
|
*/
|
|
typedef struct {
|
|
/** index name */
|
|
char name[MAXINDINAME];
|
|
/** short description */
|
|
char label[MAXINDILABEL];
|
|
/** malloced text string */
|
|
char *text;
|
|
/** pointer to parent */
|
|
struct _ITextVectorProperty *tvp;
|
|
/** handy place to hang helper info */
|
|
void *aux0;
|
|
/** handy place to hang helper info */
|
|
void *aux1;
|
|
} IText;
|
|
|
|
/** \struct _ITextVectorProperty
|
|
\brief Text vector property descriptor.
|
|
*/
|
|
typedef struct _ITextVectorProperty {
|
|
/** device name */
|
|
char device[MAXINDIDEVICE];
|
|
/** property name */
|
|
char name[MAXINDINAME];
|
|
/** short description */
|
|
char label[MAXINDILABEL];
|
|
/** GUI grouping hint */
|
|
char group[MAXINDIGROUP];
|
|
/** client accessibility hint */
|
|
IPerm p;
|
|
/** current max time to change, secs */
|
|
double timeout;
|
|
/** current property state */
|
|
IPState s;
|
|
/** texts comprising this vector */
|
|
IText *tp;
|
|
/** dimension of tp[] */
|
|
int ntp;
|
|
/** ISO 8601 timestamp of this event */
|
|
char timestamp[MAXINDITSTAMP];
|
|
/** handy place to hang helper info */
|
|
void *aux;
|
|
} ITextVectorProperty;
|
|
|
|
/** \struct INumber
|
|
\brief One number descriptor.
|
|
*/
|
|
typedef struct {
|
|
char name[MAXINDINAME]; /** index name */
|
|
char label[MAXINDILABEL]; /** short description */
|
|
char format[MAXINDIFORMAT]; /** GUI display format, see above */
|
|
double min, max; /** range, ignore if min == max */
|
|
double step; /** step size, ignore if step == 0 */
|
|
double value; /** current value */
|
|
struct _INumberVectorProperty *nvp; /** pointer to parent */
|
|
void *aux0, *aux1; /** handy place to hang helper info */
|
|
} INumber;
|
|
|
|
/** \struct _INumberVectorProperty
|
|
\brief Number vector property descriptor.
|
|
|
|
INumber.format may be any printf-style appropriate for double or style "m" to create sexigesimal using the form "%\<w\>.\<f\>m" where:\n
|
|
\<w\> is the total field width.\n
|
|
\<f\> is the width of the fraction. valid values are:\n
|
|
9 -> \<w\>:mm:ss.ss \n
|
|
8 -> \<w\>:mm:ss.s \n
|
|
6 -> \<w\>:mm:ss \n
|
|
5 -> \<w\>:mm.m \n
|
|
3 -> \<w\>:mm \n
|
|
|
|
examples:\n
|
|
|
|
To produce "-123:45", use \%7.3m \n
|
|
To produce " 0:01:02", use \%9.6m
|
|
*/
|
|
typedef struct _INumberVectorProperty {
|
|
/** device name */
|
|
char device[MAXINDIDEVICE];
|
|
/** property name */
|
|
char name[MAXINDINAME];
|
|
/** short description */
|
|
char label[MAXINDILABEL];
|
|
/** GUI grouping hint */
|
|
char group[MAXINDIGROUP];
|
|
/** client accessibility hint */
|
|
IPerm p;
|
|
/** current max time to change, secs */
|
|
double timeout;
|
|
/** current property state */
|
|
IPState s;
|
|
/** numbers comprising this vector */
|
|
INumber *np;
|
|
/** dimension of np[] */
|
|
int nnp;
|
|
/** ISO 8601 timestamp of this event */
|
|
char timestamp[MAXINDITSTAMP];
|
|
/** handy place to hang helper info */
|
|
void *aux;
|
|
} INumberVectorProperty;
|
|
|
|
/** \struct ISwitch
|
|
\brief One switch descriptor.
|
|
*/
|
|
typedef struct {
|
|
char name[MAXINDINAME]; /** index name */
|
|
char label[MAXINDILABEL]; /** this switch's label */
|
|
ISState s; /** this switch's state */
|
|
struct _ISwitchVectorProperty *svp; /** pointer to parent */
|
|
void *aux; /** handy place to hang helper info */
|
|
} ISwitch;
|
|
|
|
/** \struct _ISwitchVectorProperty
|
|
\brief Switch vector property descriptor.
|
|
*/
|
|
typedef struct _ISwitchVectorProperty {
|
|
/** device name */
|
|
char device[MAXINDIDEVICE];
|
|
/** property name */
|
|
char name[MAXINDINAME];
|
|
/** short description */
|
|
char label[MAXINDILABEL];
|
|
/** GUI grouping hint */
|
|
char group[MAXINDIGROUP];
|
|
/** client accessibility hint */
|
|
IPerm p;
|
|
/** switch behavior hint */
|
|
ISRule r;
|
|
/** current max time to change, secs */
|
|
double timeout;
|
|
/** current property state */
|
|
IPState s;
|
|
/** switches comprising this vector */
|
|
ISwitch *sp;
|
|
/** dimension of sp[] */
|
|
int nsp;
|
|
/** ISO 8601 timestamp of this event */
|
|
char timestamp[MAXINDITSTAMP];
|
|
/** handy place to hang helper info */
|
|
void *aux;
|
|
} ISwitchVectorProperty;
|
|
|
|
/** \struct ILight
|
|
\brief One light descriptor.
|
|
*/
|
|
typedef struct {
|
|
char name[MAXINDINAME]; /** index name */
|
|
char label[MAXINDILABEL]; /** this lights's label */
|
|
IPState s; /** this lights's state */
|
|
struct _ILightVectorProperty *lvp; /** pointer to parent */
|
|
void *aux; /** handy place to hang helper info */
|
|
} ILight;
|
|
|
|
/** \struct _ILightVectorProperty
|
|
\brief Light vector property descriptor.
|
|
*/
|
|
typedef struct _ILightVectorProperty {
|
|
/** device name */
|
|
char device[MAXINDIDEVICE];
|
|
/** property name */
|
|
char name[MAXINDINAME];
|
|
/** short description */
|
|
char label[MAXINDILABEL];
|
|
/** GUI grouping hint */
|
|
char group[MAXINDIGROUP];
|
|
/** current property state */
|
|
IPState s;
|
|
/** lights comprising this vector */
|
|
ILight *lp;
|
|
/** dimension of lp[] */
|
|
int nlp;
|
|
/** ISO 8601 timestamp of this event */
|
|
char timestamp[MAXINDITSTAMP];
|
|
/** handy place to hang helper info */
|
|
void *aux;
|
|
} ILightVectorProperty;
|
|
|
|
/** \struct IBLOB
|
|
\brief One Blob (Binary Large Object) descriptor.
|
|
*/
|
|
typedef struct { /* one BLOB descriptor */
|
|
/** index name */
|
|
char name[MAXINDINAME];
|
|
/** this BLOB's label */
|
|
char label[MAXINDILABEL];
|
|
/** format attr */
|
|
char format[MAXINDIBLOBFMT];
|
|
/** malloced binary large object bytes */
|
|
void *blob;
|
|
/** bytes in blob */
|
|
int bloblen;
|
|
/** n uncompressed bytes */
|
|
int size;
|
|
/** pointer to parent */
|
|
struct _IBLOBVectorProperty *bvp;
|
|
/** handy place to hang helper info */
|
|
void *aux0, *aux1, *aux2;
|
|
} IBLOB;
|
|
|
|
/** \struct _IBLOBVectorProperty
|
|
\brief BLOB (Binary Large Object) vector property descriptor.
|
|
*/
|
|
|
|
typedef struct _IBLOBVectorProperty { /* BLOB vector property descriptor */
|
|
/** device name */
|
|
char device[MAXINDIDEVICE];
|
|
/** property name */
|
|
char name[MAXINDINAME];
|
|
/** short description */
|
|
char label[MAXINDILABEL];
|
|
/** GUI grouping hint */
|
|
char group[MAXINDIGROUP];
|
|
/** client accessibility hint */
|
|
IPerm p;
|
|
/** current max time to change, secs */
|
|
double timeout;
|
|
/** current property state */
|
|
IPState s;
|
|
/** BLOBs comprising this vector */
|
|
IBLOB *bp;
|
|
/** dimension of bp[] */
|
|
int nbp;
|
|
/** ISO 8601 timestamp of this event */
|
|
char timestamp[MAXINDITSTAMP];
|
|
/** handy place to hang helper info */
|
|
void *aux;
|
|
} IBLOBVectorProperty;
|
|
|
|
|
|
/** \brief Handy macro to find the number of elements in array a[]. Must be used with actual array, not pointer.
|
|
*/
|
|
#define NARRAY(a) (sizeof(a)/sizeof(a[0]))
|
|
|
|
#endif
|