1 | #if 0 |
---|
2 | INDI |
---|
3 | Copyright (C) 2003 Elwood C. Downey |
---|
4 | |
---|
5 | This library is free software; you can redistribute it and/or |
---|
6 | modify it under the terms of the GNU Lesser General Public |
---|
7 | License as published by the Free Software Foundation; either |
---|
8 | version 2.1 of the License, or (at your option) any later version. |
---|
9 | |
---|
10 | This library is distributed in the hope that it will be useful, |
---|
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
---|
13 | Lesser General Public License for more details. |
---|
14 | |
---|
15 | You should have received a copy of the GNU Lesser General Public |
---|
16 | License along with this library; if not, write to the Free Software |
---|
17 | Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
---|
18 | |
---|
19 | #endif |
---|
20 | |
---|
21 | #ifndef INDI_API_H |
---|
22 | #define INDI_API_H |
---|
23 | |
---|
24 | /** \mainpage Instrument Neutral Distributed Interface INDI |
---|
25 | \section Introduction |
---|
26 | |
---|
27 | INDI is a simple XML-like communications protocol described for interactive and automated remote control of diverse instrumentation.\n |
---|
28 | |
---|
29 | 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 |
---|
30 | |
---|
31 | 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 accommadates 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 |
---|
32 | |
---|
33 | The INDI protocol can be nested within other XML elements such as constraints for automatic scheduling and execution.\n |
---|
34 | |
---|
35 | For a complete review on the INDI protocol, please refer to the INDI <a href="http://www.clearskyinstitute.com/INDI/INDI.pdf">white paper</a>. |
---|
36 | |
---|
37 | \section Audience Intended Audience |
---|
38 | |
---|
39 | 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>, <a href="http://pygtkindiclient.sourceforge.net/">DCD</a>, and <a href="http://www.stargazing.net/astropc">Cartes du Ciel</a>. |
---|
40 | |
---|
41 | \section Development Developing under INDI |
---|
42 | |
---|
43 | <p>Please refere to the <a href="http://indi.sourceforge.net/index.php/Manual">INDI Developers Manual</a> for a complete guide on INDI's driver developemnt framework.</p> |
---|
44 | |
---|
45 | <p>The INDI Library API is divided into the following main sections:</p> |
---|
46 | <ul> |
---|
47 | <li><a href="indidevapi_8h.html">INDI Device API</a></li> |
---|
48 | <li><a href="indicom_8h.html">INDI Common Routine Library</a></li> |
---|
49 | <li><a href="lilxml_8h.html">INDI LilXML Library</a></li> |
---|
50 | <li><a href="http://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/cfitsio.html">CFITSIO Library</a></li> |
---|
51 | </ul> |
---|
52 | |
---|
53 | |
---|
54 | \section Help |
---|
55 | |
---|
56 | 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>. |
---|
57 | |
---|
58 | \author Elwood Downey |
---|
59 | \author Jasem Mutlaq |
---|
60 | */ |
---|
61 | |
---|
62 | /** \file indiapi.h |
---|
63 | \brief Constants and Data structure definitions for the interface to the reference INDI C API implementation. |
---|
64 | \author Elwood C. Downey |
---|
65 | */ |
---|
66 | |
---|
67 | /******************************************************************************* |
---|
68 | * INDI wire protocol version implemented by this API. |
---|
69 | * N.B. this is indepedent of the API itself. |
---|
70 | */ |
---|
71 | |
---|
72 | #define INDIV 1.7 |
---|
73 | |
---|
74 | |
---|
75 | /* INDI Library version */ |
---|
76 | #define INDI_LIBV 0.6 |
---|
77 | |
---|
78 | /******************************************************************************* |
---|
79 | * Manifest constants |
---|
80 | */ |
---|
81 | |
---|
82 | /** \typedef ISState |
---|
83 | \brief Switch state. |
---|
84 | */ |
---|
85 | typedef enum |
---|
86 | { |
---|
87 | ISS_OFF, /*!< Switch is OFF */ |
---|
88 | ISS_ON /*!< Switch is ON */ |
---|
89 | } ISState; /* switch state */ |
---|
90 | |
---|
91 | /** \typedef IPState |
---|
92 | \brief Property state. |
---|
93 | */ |
---|
94 | typedef enum |
---|
95 | { |
---|
96 | IPS_IDLE, /*!< State is idle */ |
---|
97 | IPS_OK, /*!< State is ok */ |
---|
98 | IPS_BUSY, /*!< State is busy */ |
---|
99 | IPS_ALERT /*!< State is alert */ |
---|
100 | } IPState; /* property state */ |
---|
101 | |
---|
102 | /** \typedef ISRule |
---|
103 | \brief Switch vector rule hint. |
---|
104 | */ |
---|
105 | typedef enum |
---|
106 | { |
---|
107 | ISR_1OFMANY, /*!< Only 1 switch of many can be ON (e.g. radio buttons) */ |
---|
108 | ISR_ATMOST1, /*!< There is only ONE switch */ |
---|
109 | ISR_NOFMANY /*!< Any number of switches can be ON (e.g. check boxes) */ |
---|
110 | } ISRule; /* switch vector rule hint */ |
---|
111 | |
---|
112 | /** \typedef IPerm |
---|
113 | \brief Permission hint, with respect to client. |
---|
114 | */ |
---|
115 | typedef enum |
---|
116 | { |
---|
117 | IP_RO, /*!< Read Only */ |
---|
118 | IP_WO, /*!< Write Only */ |
---|
119 | IP_RW /*!< Read & Write */ |
---|
120 | } IPerm; /* permission hint, WRT client */ |
---|
121 | |
---|
122 | /* The XML strings for these attributes may be any length but implementations |
---|
123 | * are only obligued to support these lengths for the various string attributes. |
---|
124 | */ |
---|
125 | #define MAXINDINAME 32 |
---|
126 | #define MAXINDILABEL 32 |
---|
127 | #define MAXINDIDEVICE 32 |
---|
128 | #define MAXINDIGROUP 32 |
---|
129 | #define MAXINDIFORMAT 32 |
---|
130 | #define MAXINDIBLOBFMT 32 |
---|
131 | #define MAXINDITSTAMP 32 |
---|
132 | |
---|
133 | /******************************************************************************* |
---|
134 | * Typedefs for each INDI Property type. |
---|
135 | * |
---|
136 | * INumber.format may be any printf-style appropriate for double |
---|
137 | * or style "m" to create sexigesimal using the form "%<w>.<f>m" where |
---|
138 | * <w> is the total field width. |
---|
139 | * <f> is the width of the fraction. valid values are: |
---|
140 | * 9 -> :mm:ss.ss |
---|
141 | * 8 -> :mm:ss.s |
---|
142 | * 6 -> :mm:ss |
---|
143 | * 5 -> :mm.m |
---|
144 | * 3 -> :mm |
---|
145 | * |
---|
146 | * examples: |
---|
147 | * |
---|
148 | * to produce use |
---|
149 | * |
---|
150 | * "-123:45" %7.3m |
---|
151 | * " 0:01:02" %9.6m |
---|
152 | */ |
---|
153 | |
---|
154 | /** \struct IText |
---|
155 | \brief One text descriptor. |
---|
156 | */ |
---|
157 | typedef struct { |
---|
158 | /** index name */ |
---|
159 | char name[MAXINDINAME]; |
---|
160 | /** short description */ |
---|
161 | char label[MAXINDILABEL]; |
---|
162 | /** malloced text string */ |
---|
163 | char *text; |
---|
164 | /** pointer to parent */ |
---|
165 | struct _ITextVectorProperty *tvp; |
---|
166 | /** handy place to hang helper info */ |
---|
167 | void *aux0; |
---|
168 | /** handy place to hang helper info */ |
---|
169 | void *aux1; |
---|
170 | } IText; |
---|
171 | |
---|
172 | /** \struct _ITextVectorProperty |
---|
173 | \brief Text vector property descriptor. |
---|
174 | */ |
---|
175 | typedef struct _ITextVectorProperty { |
---|
176 | /** device name */ |
---|
177 | char device[MAXINDIDEVICE]; |
---|
178 | /** property name */ |
---|
179 | char name[MAXINDINAME]; |
---|
180 | /** short description */ |
---|
181 | char label[MAXINDILABEL]; |
---|
182 | /** GUI grouping hint */ |
---|
183 | char group[MAXINDIGROUP]; |
---|
184 | /** client accessibility hint */ |
---|
185 | IPerm p; |
---|
186 | /** current max time to change, secs */ |
---|
187 | double timeout; |
---|
188 | /** current property state */ |
---|
189 | IPState s; |
---|
190 | /** texts comprising this vector */ |
---|
191 | IText *tp; |
---|
192 | /** dimension of tp[] */ |
---|
193 | int ntp; |
---|
194 | /** ISO 8601 timestamp of this event */ |
---|
195 | char timestamp[MAXINDITSTAMP]; |
---|
196 | /** handy place to hang helper info */ |
---|
197 | void *aux; |
---|
198 | } ITextVectorProperty; |
---|
199 | |
---|
200 | /** \struct INumber |
---|
201 | \brief One number descriptor. |
---|
202 | */ |
---|
203 | typedef struct { |
---|
204 | char name[MAXINDINAME]; /** index name */ |
---|
205 | char label[MAXINDILABEL]; /** short description */ |
---|
206 | char format[MAXINDIFORMAT]; /** GUI display format, see above */ |
---|
207 | double min, max; /** range, ignore if min == max */ |
---|
208 | double step; /** step size, ignore if step == 0 */ |
---|
209 | double value; /** current value */ |
---|
210 | struct _INumberVectorProperty *nvp; /** pointer to parent */ |
---|
211 | void *aux0, *aux1; /** handy place to hang helper info */ |
---|
212 | } INumber; |
---|
213 | |
---|
214 | /** \struct _INumberVectorProperty |
---|
215 | \brief Number vector property descriptor. |
---|
216 | |
---|
217 | INumber.format may be any printf-style appropriate for double or style "m" to create sexigesimal using the form "%\<w\>.\<f\>m" where:\n |
---|
218 | \<w\> is the total field width.\n |
---|
219 | \<f\> is the width of the fraction. valid values are:\n |
---|
220 | 9 -> \<w\>:mm:ss.ss \n |
---|
221 | 8 -> \<w\>:mm:ss.s \n |
---|
222 | 6 -> \<w\>:mm:ss \n |
---|
223 | 5 -> \<w\>:mm.m \n |
---|
224 | 3 -> \<w\>:mm \n |
---|
225 | |
---|
226 | examples:\n |
---|
227 | |
---|
228 | To produce "-123:45", use \%7.3m \n |
---|
229 | To produce " 0:01:02", use \%9.6m |
---|
230 | */ |
---|
231 | typedef struct _INumberVectorProperty { |
---|
232 | /** device name */ |
---|
233 | char device[MAXINDIDEVICE]; |
---|
234 | /** property name */ |
---|
235 | char name[MAXINDINAME]; |
---|
236 | /** short description */ |
---|
237 | char label[MAXINDILABEL]; |
---|
238 | /** GUI grouping hint */ |
---|
239 | char group[MAXINDIGROUP]; |
---|
240 | /** client accessibility hint */ |
---|
241 | IPerm p; |
---|
242 | /** current max time to change, secs */ |
---|
243 | double timeout; |
---|
244 | /** current property state */ |
---|
245 | IPState s; |
---|
246 | /** numbers comprising this vector */ |
---|
247 | INumber *np; |
---|
248 | /** dimension of np[] */ |
---|
249 | int nnp; |
---|
250 | /** ISO 8601 timestamp of this event */ |
---|
251 | char timestamp[MAXINDITSTAMP]; |
---|
252 | /** handy place to hang helper info */ |
---|
253 | void *aux; |
---|
254 | } INumberVectorProperty; |
---|
255 | |
---|
256 | /** \struct ISwitch |
---|
257 | \brief One switch descriptor. |
---|
258 | */ |
---|
259 | typedef struct { |
---|
260 | char name[MAXINDINAME]; /** index name */ |
---|
261 | char label[MAXINDILABEL]; /** this switch's label */ |
---|
262 | ISState s; /** this switch's state */ |
---|
263 | struct _ISwitchVectorProperty *svp; /** pointer to parent */ |
---|
264 | void *aux; /** handy place to hang helper info */ |
---|
265 | } ISwitch; |
---|
266 | |
---|
267 | /** \struct _ISwitchVectorProperty |
---|
268 | \brief Switch vector property descriptor. |
---|
269 | */ |
---|
270 | typedef struct _ISwitchVectorProperty { |
---|
271 | /** device name */ |
---|
272 | char device[MAXINDIDEVICE]; |
---|
273 | /** property name */ |
---|
274 | char name[MAXINDINAME]; |
---|
275 | /** short description */ |
---|
276 | char label[MAXINDILABEL]; |
---|
277 | /** GUI grouping hint */ |
---|
278 | char group[MAXINDIGROUP]; |
---|
279 | /** client accessibility hint */ |
---|
280 | IPerm p; |
---|
281 | /** switch behavior hint */ |
---|
282 | ISRule r; |
---|
283 | /** current max time to change, secs */ |
---|
284 | double timeout; |
---|
285 | /** current property state */ |
---|
286 | IPState s; |
---|
287 | /** switches comprising this vector */ |
---|
288 | ISwitch *sp; |
---|
289 | /** dimension of sp[] */ |
---|
290 | int nsp; |
---|
291 | /** ISO 8601 timestamp of this event */ |
---|
292 | char timestamp[MAXINDITSTAMP]; |
---|
293 | /** handy place to hang helper info */ |
---|
294 | void *aux; |
---|
295 | } ISwitchVectorProperty; |
---|
296 | |
---|
297 | /** \struct ILight |
---|
298 | \brief One light descriptor. |
---|
299 | */ |
---|
300 | typedef struct { |
---|
301 | char name[MAXINDINAME]; /** index name */ |
---|
302 | char label[MAXINDILABEL]; /** this lights's label */ |
---|
303 | IPState s; /** this lights's state */ |
---|
304 | struct _ILightVectorProperty *lvp; /** pointer to parent */ |
---|
305 | void *aux; /** handy place to hang helper info */ |
---|
306 | } ILight; |
---|
307 | |
---|
308 | /** \struct _ILightVectorProperty |
---|
309 | \brief Light vector property descriptor. |
---|
310 | */ |
---|
311 | typedef struct _ILightVectorProperty { |
---|
312 | /** device name */ |
---|
313 | char device[MAXINDIDEVICE]; |
---|
314 | /** property name */ |
---|
315 | char name[MAXINDINAME]; |
---|
316 | /** short description */ |
---|
317 | char label[MAXINDILABEL]; |
---|
318 | /** GUI grouping hint */ |
---|
319 | char group[MAXINDIGROUP]; |
---|
320 | /** current property state */ |
---|
321 | IPState s; |
---|
322 | /** lights comprising this vector */ |
---|
323 | ILight *lp; |
---|
324 | /** dimension of lp[] */ |
---|
325 | int nlp; |
---|
326 | /** ISO 8601 timestamp of this event */ |
---|
327 | char timestamp[MAXINDITSTAMP]; |
---|
328 | /** handy place to hang helper info */ |
---|
329 | void *aux; |
---|
330 | } ILightVectorProperty; |
---|
331 | |
---|
332 | /** \struct IBLOB |
---|
333 | \brief One Blob (Binary Large Object) descriptor. |
---|
334 | */ |
---|
335 | typedef struct { /* one BLOB descriptor */ |
---|
336 | /** index name */ |
---|
337 | char name[MAXINDINAME]; |
---|
338 | /** this BLOB's label */ |
---|
339 | char label[MAXINDILABEL]; |
---|
340 | /** format attr */ |
---|
341 | char format[MAXINDIBLOBFMT]; |
---|
342 | /** malloced binary large object bytes */ |
---|
343 | void *blob; |
---|
344 | /** bytes in blob */ |
---|
345 | int bloblen; |
---|
346 | /** n uncompressed bytes */ |
---|
347 | int size; |
---|
348 | /** pointer to parent */ |
---|
349 | struct _IBLOBVectorProperty *bvp; |
---|
350 | /** handy place to hang helper info */ |
---|
351 | void *aux0, *aux1, *aux2; |
---|
352 | } IBLOB; |
---|
353 | |
---|
354 | /** \struct _IBLOBVectorProperty |
---|
355 | \brief BLOB (Binary Large Object) vector property descriptor. |
---|
356 | */ |
---|
357 | |
---|
358 | typedef struct _IBLOBVectorProperty { /* BLOB vector property descriptor */ |
---|
359 | /** device name */ |
---|
360 | char device[MAXINDIDEVICE]; |
---|
361 | /** property name */ |
---|
362 | char name[MAXINDINAME]; |
---|
363 | /** short description */ |
---|
364 | char label[MAXINDILABEL]; |
---|
365 | /** GUI grouping hint */ |
---|
366 | char group[MAXINDIGROUP]; |
---|
367 | /** client accessibility hint */ |
---|
368 | IPerm p; |
---|
369 | /** current max time to change, secs */ |
---|
370 | double timeout; |
---|
371 | /** current property state */ |
---|
372 | IPState s; |
---|
373 | /** BLOBs comprising this vector */ |
---|
374 | IBLOB *bp; |
---|
375 | /** dimension of bp[] */ |
---|
376 | int nbp; |
---|
377 | /** ISO 8601 timestamp of this event */ |
---|
378 | char timestamp[MAXINDITSTAMP]; |
---|
379 | /** handy place to hang helper info */ |
---|
380 | void *aux; |
---|
381 | } IBLOBVectorProperty; |
---|
382 | |
---|
383 | |
---|
384 | /** \brief Handy macro to find the number of elements in array a[]. Must be used with actual array, not pointer. |
---|
385 | */ |
---|
386 | #define NARRAY(a) (sizeof(a)/sizeof(a[0])) |
---|
387 | |
---|
388 | #endif |
---|