lcm_interface.h

/* 
 *   lcm_telemetry.h
 *   Copyright 2010 Joby Energy, Inc.
 *   Matt Peddie
 */

/**********************************************************************
 * This file contains brief documentation concerning how to use the
 * autogenerating types/telemetry/settings system.  If this sentence
 * is still here, then this system is still in the very earliest of
 * the wee alpha stages.  It's prone to break in strange ways.  I'm
 * working on it.
 * 
 * ********************************************************************
 * The goal of this new system is to require as little programmer work
 * as possible in the actual C code.  One slight hack is involved
 * (explained below); for remembering one rule, the user is rewarded
 * with far less integration work than with the old paparazzi system
 * when he or she wants to add a new telemetry message or setting.  
 *
 * <> Things relating to how the program flows and what math happens
 *    should be in the C code.
 *
 * <> Things related to interacting with the program from the ground
 *    station should be in the XML.
 *
 * <> Things related to a specific airframe should be in the XML.
 *
 * ********************************************************************
 * Types are specified in `types.xml'.  You unfortunately have to work
 * within the confines of the LCM system with these, which means using
 * int32_t instead of int or whatever; no enums*; no pointers*; can't
 * include externally defined structs; etc.  
 * 
 * The asterisks above mean that enums can be replicated in the
 * autogenerated interface (see the example in types.xml), and if you
 * define a type with a pointer in the XML, it is implemented as an
 * array of size one.  
 * 
 * The example code in types.xml gives a pretty decent idea of what
 * sorts of stuff you can do (while better documentation is being
 * created).
 *
 * *******************************************************************
 * Telemetry is specified in `telemetry.xml'.  You specify only a few
 * things: what the variable you want to send is called where it's
 * defined, what type it is, and what rates it should be sent at in
 * the sim and in flight.
 * 
 * In the code where you define the thing you want to send (call it
 * `foobar' of type `ap_xyz_t'), you must #include
 * <telemetry/ap_xyz_t_foobar.h> AFTER YOU DECLARE `foobar'.  This
 * relies on C's scoping rules to work properly.  This makes it
 * slightly brittle, but hopefully the following example will convince
 * you that it is worth it:
 *
 *     static ap_xyz_t foobar;
 *     #include <telemetry/ap_xyz_t_foobar.h>
 *
 * That is all that's necessary (ap is the "type class" that foobar
 * belongs to -- the <class> directive that contains the definition of
 * <xyz_t> in `types.xml'.  Again, you have to #include the
 * appropriate telemetry header AFTER YOU DECLARE the object being
 * sent.  The object will show up on the network at the rate specified
 * by the preprocessor value DT and the rate fields you give in
 * telemetry.xml.
 *
 * ******************************************************************
 * Settings work very much like telemetry does.  They are configured
 * in `settings.xml'.  In addition, since the settings system sends
 * the modified object back down the telemetry link for confirmation
 * and synchronization purposes, you don't have to #include a
 * telemetry header if something is a setting.  It will be sent down
 * the link whenever it's modified by settings, as well as
 * (optionally) at a rate you specify if you explicitly include it in
 * telemetry.xml.  So the setting looks like this:
 *
 *     static ap_xyz_t foobar;
 *     #include <settings/ap_xyz_t_foobar.h>
 * 
 * Once AGAIN, you have to #include the appropriate header AFTER YOU
 * DECLARE the object being sent.
 *
 * ******************************************************************
 * To start the lcm system, you should only have to call
 * lcm_init(const char *provider); this will initialize all the
 * telemetry classes you've defined.  telemetry_send() and
 * settings_check() do roughly what you'd expect: send all the
 * periodic telemetry classes and look for new settings messages.  You
 * should call these in your periodic loop that runs with period DT.
 * 
 ******************************************************************/

#ifndef __LCM_TELEMETRY_H__
#define __LCM_TELEMETRY_H__

#include <lcm/lcm.h>

/* This is where most of the magic comes from. */
#include "lcm_telemetry_auto.h"
#include "lcm_settings_auto.h"

#ifdef __cplusplus
extern "C"{
#endif

/* initialize an LCM object. */
void lcm_initialize(const char *provider, lcm_t **lcm, int *fd);

/* If there are any pending LCM messages, process them and return. */
void lcm_check(lcm_t *lcm, int fd);

/* Don't return until an LCM message has been received and
 * processed.*/
void lcm_wait(lcm_t *lcm);

#ifdef __cplusplus
}
#endif

#endif // __LCM_TELEMETRY_H__