[tuxdroid-svn] r663 - firmware/tuxdefs

[jaguarondi <c2m...@c2...>]

Author: jaguarondi
Date: 2007-11-08 10:36:40 +0100 (Thu, 08 Nov 2007)
New Revision: 663

Modified:
   firmware/tuxdefs/commands.h
Log:
* Added a 'variation' member to the author structure.

* Added doxygen comments on all information commands, reorganized them and sis
  some cleaning.


Modified: firmware/tuxdefs/commands.h
===================================================================
--- firmware/tuxdefs/commands.h	2007-11-07 15:35:18 UTC (rev 662)
+++ firmware/tuxdefs/commands.h	2007-11-08 09:36:40 UTC (rev 663)
@@ -19,35 +19,68 @@
 
 /* $Id$*/
 
+/** \file commands.h
+    \brief Firmware API
+    \ingroup commands
+*/
+
+/** \defgroup commands Firmware API
+
+    These firmware commands constitute the program interface between all CPUs
+    and the computer. Both actions (also called commands) and status are
+    transmitted by these commands.
+ *  @{ */
+
 #ifndef _COMMAND_H_
 #define _COMMAND_H_
 
 #include <stdint.h>
 
-/*
- * Version numbers
+/**
+ * \name Request information
+ * These commands request some general information of the CPUs and their
+ * firmware. This includes identifiers, versions, revisions, author, etc.
+ *  @{ */
+/**
+ * \brief CPU identifiers
  */
+enum CPU_IDENTIFIERS
+{
+    /** 'tuxcore' is the core CPU of tuxdroid, it manages the sensors and
+     * actuators. */
+    TUXCORE_CPU_NUM = 0,
+    /** 'tuxaudio' is the CPU of tuxdroid that handles audio (microphone,
+     * speaker and the audio flash) and communications between the RF and
+     * tuxcore. */
+    TUXAUDIO_CPU_NUM = 1,
+    /** 'tuxrf' is the RF CPU of tuxdroid. */
+    TUXRF_CPU_NUM = 2,
+    /** 'fuxrf' is the RF CPU inside the dongle. */
+    FUXRF_CPU_NUM = 3,
+    /** 'fuxusb' is the USB CPU inside the dongle. */
+    FUXUSB_CPU_NUM = 4,
+};
 
-#define TUXCORE_CPU_NUM         0x00
-#define TUXAUDIO_CPU_NUM        0x01
-#define TUXRF_CPU_NUM           0x02
-#define FUXRF_CPU_NUM           0x03
-#define FUXUSB_CPU_NUM          0x04
+/**
+ * /brief I2C addresses of all CPUs
+ *
+ * tuxcore, tuxaudio, tuxrf and fuxrf have different I2C addresses when they're
+ * running in normal or bootloader mode.
+ */
+enum I2C_ADDRESSES
+{
+    TUXCORE_BL_ADDR = 0X30,
+    TUXAUDIO_BL_ADDR = 0X31,
+    TUXRF_BL_ADDR = 0X32,
+    FUXRF_BL_ADDR = 0X33,
+    /* XXX we should remove these TWAR stuff from here */
+    TUXCORE_BL_TWAR = (TUXCORE_BL_ADDR << 1),
+    TUXAUDIO_BL_TWAR = (TUXAUDIO_BL_ADDR << 1),
+    TUXRF_BL_TWAR = (TUXRF_BL_ADDR << 1),
+    FUXRF_BL_TWAR = (FUXRF_BL_ADDR << 1),
+};
 
 /*
- * I2C Adresses
- */
-/* Bootloader */
-#define TUXCORE_BL_ADDR         0X30
-#define TUXAUDIO_BL_ADDR        0X31
-#define TUXRF_BL_ADDR           0X32
-#define FUXRF_BL_ADDR           0X33
-#define TUXCORE_BL_TWAR         (TUXCORE_BL_ADDR << 1)
-#define TUXAUDIO_BL_TWAR        (TUXAUDIO_BL_ADDR << 1)
-#define TUXRF_BL_TWAR           (TUXRF_BL_ADDR << 1)
-#define FUXRF_BL_TWAR           (FUXRF_BL_ADDR << 1)
-
-/*!
  * COMMANDS
  *
  * Commands are divided in 4 groups depending on the number of parameters they
@@ -63,7 +96,7 @@
  * Tux's commands, audio commands, and status.
  *
  * 1. Tux's commands are sent from the computer to Tux in order to control all
- *    actuators: motors, leds, IR, etc. They can have any number of parameters
+ *    actuators: motors, LEDs, IR, etc. They can have any number of parameters
  *    (from 0 to 3) and are defined in "Tux's core API";
  *
  * 2. Audio commands are sent from the computer or from Tux to the audio chip.
@@ -71,41 +104,61 @@
  *
  * 3. Status are sent from Tux back to the computer in order to give feedback
  *    on sensor states or send some received IR code.
- */
-
-/*
+ *
  * Note: Audio commands are sent from the computer or from Tux to the audio
  * chip. The audio chip also receives status which it transfers to the
  * computer. In order to differentiate status from audio commands easily, we
- * choosed to have audio commands < 0xC0 which means they can have 0, 1 or 2
+ * chose to have audio commands <0xC0 which means they can have 0, 1 or 2
  * parameters but not 3.  Status commands will always have 3 parameters has we
  * always want to send as much information as possible anyway.
+ *
+ * /todo TODO this is still relevant but should be clarified
  */
 
+
 /*
  * Version commands
  */
-#define INFO_TUXCORE_CMD        0x02
-#define INFO_TUXAUDIO_CMD       0x03
-#define INFO_TUXRF_CMD          0x04
-#define INFO_FUXRF_CMD          0x05
-#define INFO_FUXUSB_CMD         0x06
+/** Request generic informations from tuxcore. */
+#define INFO_TUXCORE_CMD 0x02
+/** Request generic informations from tuxcaudio. */
+#define INFO_TUXAUDIO_CMD 0x03
+/** Request generic informations from tuxrf. */
+#define INFO_TUXRF_CMD 0x04
+/** Request generic informations from fuxrf. */
+#define INFO_FUXRF_CMD 0x05
+/** Request generic informations from fuxusb. */
+#define INFO_FUXUSB_CMD 0x06
 
-#define VERSION_CMD             0xC8
-/*
+/**
+ * Return the CPU number and the firmware version in major.minor.update
+ * format.
+ *
+ * In the current implementation, each firmware simply fetches the version_t
+ * structure.
+ */
+#define VERSION_CMD 0xC8
+
+/**
+ * Version structure (DEPRECATED)
  * This version_bf_t type can't be used to send the bytes over a channel as the
- * order of the bits in the bitfield may be freely rearranged by GCC.
+ * order of the bits in the bit field may be freely rearranged by GCC.
+ *
+ * /todo TODO check that no firmware is using this anymore and delete this.
  */
 typedef struct
 {
     uint8_t version_cmd;
-    uint8_t cpu_nbr:3;          /* 3 lower bits are the CPU number */
-    uint8_t ver_major:5;        /* 5 higher bits are the major version number */
+    uint8_t cpu_nbr:3; /* 3 lower bits are the CPU number */
+    uint8_t ver_major:5; /* 5 higher bits are the major version number */
     uint8_t ver_minor;
     uint8_t ver_update;
 } version_bf_t;
 
-/*
+/**
+ * Version structure that holds the raw data that will be sent when the
+ * VERSION_CMD is received.
+ *
  * This version_t type should be used to send the bytes over a channel such as
  * USB or TCP-IP. Use the macros to set or retrieve values of the cpu_ver_maj
  * byte.
@@ -113,37 +166,89 @@
 typedef struct
 {
     uint8_t version_cmd;
-    uint8_t cpu_ver_maj;        /* 3 lower bits are the CPU number, 5 higher bits are the major version number */
+    uint8_t cpu_ver_maj; /** 3 lower bits are the CPU number, 5 higher bits are
+                            the major version number */
     uint8_t ver_minor;
     uint8_t ver_update;
 } version_t;
 
+/** Concatenate the CPU number and the major version number to create
+ * 'cpu_ver_maj'.
+ * /param[cpu_nbr] CPU number
+ * /param[ver_major] major version number
+ * /return true if successful, false otherwise */
 #define CPU_VER_JOIN(cpu_nbr, ver_major) ((cpu_nbr & 0x7) + (ver_major << 3))
-#define CPU_VER_CPU(cpu_ver_maj) (cpu_ver_maj & 0x07)   /* cpu_nbr: 3 lower bits */
-#define CPU_VER_MAJ(cpu_ver_maj) ((cpu_ver_maj & 0xF8) >> 3)    /* ver_major: 5 higher bits */
+/** Retrieve the CPU number from 'cpu_ver_maj'. */
+#define CPU_VER_CPU(cpu_ver_maj) (cpu_ver_maj & 0x07)
+/** Retrieve the major version number from 'cpu_ver_maj'. */
+#define CPU_VER_MAJ(cpu_ver_maj) ((cpu_ver_maj & 0xF8) >> 3)
 
-#define REVISION_CMD            0xC9
+/**
+ * Return the firmware revision number.
+ *
+ * In the current implementation, each firmware simply fetches the revision_t
+ * structure.
+ * As the AVR is little-endian, the 16 bits revision is sent with the LSB
+ * first.
+ *
+ * 1st parameter: LSB of the revision number.
+ * 2nd parameter: MSB of the revision number.
+ * 3rd parameter: undefined.
+ */
+#define REVISION_CMD 0xC9
+/**
+ * Revision number of the firmware from the subversion repository.
+ */
 typedef struct
 {
     uint8_t revision_cmd;
     uint16_t revision;
-    uint8_t _undefined_;        /* XXX reserved, maybe a branch ID? */
+    uint8_t _undefined_;
 } revision_t;
 
-#define AUTHOR_CMD             0xCA
+/**
+ * Return the firmware author information.
+ *
+ * In the current implementation, each firmware simply fetches the author_t
+ * structure.
+ * As the AVR is little-endian, the 16 bits author number is sent with the LSB
+ * first.
+ *
+ * The author id can be used to differentiate official firmware from other
+ * custom versions.
+ * The variation number can be used by one author to differentiate multiple
+ * variations of a firmware. This is useful if someone develops a couple of
+ * firmware that would require specific external sensors for example, or .
+ * firmware that implements some functions differently like the flash usage, or
+ * driving the motors another way.
+ *
+ * Official firmware from Kysoh has the author id '0'. If you're developing
+ * firmware, use another number.
+ *
+ * 1st parameter: LSB of the author id.
+ * 2nd parameter: MSB of the author id.
+ * 3rd parameter: variation number.
+ */
+#define AUTHOR_CMD 0xCA
+/**
+ * Author information of the firmware.
+ */
 typedef struct
 {
     uint8_t author_cmd;
-    uint16_t author_id;         /* official releases have id=0, other authors can have their own id's */
-    uint8_t _undefined_;        /* XXX reserved */
+    uint16_t author_id;
+    uint8_t variation;
 } author_t;
 
-/*
- * Various information commands
+/**
+ * Return the sound flash information.
+ *
+ * 1st parameter: number of sounds stored in the flash.
  */
-#define SOUND_VAR_CMD           0xCB
-/* 1st parameter: number of sounds stored in the flash */
+#define SOUND_VAR_CMD 0xCB
 
+/*! @} */
+
 /*
  * Move commands
  */
@@ -162,26 +267,26 @@
 
 #define WAVE_WINGS_CMD      0x80        /* move the wings up and down */
 /* 1st parameter: number of movements before the wings will stop */
-/* 2nd parameter: pwm value between 1 (slow) and 5 (fast) */
+/* 2nd parameter: PWM value between 1 (slow) and 5 (fast) */
 #define STOP_WINGS_CMD      0x30        /* stop the wings motor */
-#define RESET_WINGS_CMD     0x31        /* reset the wings in the low position */
-#define RAISE_WINGS_CMD     0x39	/* move the wings in the upper position */
-#define LOWER_WINGS_CMD     0x3A	/* move the wings in the lower position */
+#define RESET_WINGS_CMD     0x31     /* reset the wings in the low position */
+#define RAISE_WINGS_CMD     0x39     /* move the wings in the upper position */
+#define LOWER_WINGS_CMD     0x3A     /* move the wings in the lower position */
 
 #define SPIN_LEFT_CMD       0x82        /* spin left of a given angle */
 /* 1st parameter: angle to turn, the unit is approximately 1/8th of a turn */
-/* 2nd parameter: pwm value between 1 (slow) and 5 (fast) */
+/* 2nd parameter: PWM value between 1 (slow) and 5 (fast) */
 #define SPIN_RIGHT_CMD      0x83        /* spin right of a given angle */
 /* 1st parameter: angle to turn, the unit is approximately 1/8th of a turn */
-/* 2nd parameter: pwm value between 1 (slow) and 5 (fast) */
+/* 2nd parameter: PWM value between 1 (slow) and 5 (fast) */
 #define STOP_SPIN_CMD       0x37        /* stop the spinning motor */
 
 /*
  * IR commands
  */
 
-#define TURN_IR_ON_CMD      0x17        /* turn IR led on */
-#define TURN_IR_OFF_CMD     0x18        /* turn IR led off */
+#define TURN_IR_ON_CMD      0x17        /* turn IR LED on */
+#define TURN_IR_OFF_CMD     0x18        /* turn IR LED off */
 #define IR_SEND_RC5_CMD     0x91        /* send RC5 ir code */
 /* 1st parameter: address - xxTAAAAA (T: toggle bit, A: RC5 5 bits address) */
 /* 2nd parameter: command - xxCCCCCC (C: RC5 6 bits command) */
@@ -190,31 +295,31 @@
  * LED commands
  */
 
-#define LED_ON_CMD          0x1A        /* Turn all leds on */
-#define LED_OFF_CMD         0x1B        /* Turn all leds off */
-#define LED_L_ON_CMD        0x1C        /* Turn left led on */
-#define LED_L_OFF_CMD       0x1D        /* Turn left led off */
-#define LED_R_ON_CMD        0x1E        /* Turn right led on */
-#define LED_R_OFF_CMD       0x1F        /* Turn right led off */
-#define LED_BLINK_CMD       0x9A        /* Blink both leds multiple time */
-/* 1st parameter: number of led toggles */
-/* 2nd parameter: delay between each led toggle, in multiple of 4ms */
+#define LED_ON_CMD          0x1A        /* Turn all LEDs on */
+#define LED_OFF_CMD         0x1B        /* Turn all LEDs off */
+#define LED_L_ON_CMD        0x1C        /* Turn left LED on */
+#define LED_L_OFF_CMD       0x1D        /* Turn left LED off */
+#define LED_R_ON_CMD        0x1E        /* Turn right LED on */
+#define LED_R_OFF_CMD       0x1F        /* Turn right LED off */
+#define LED_BLINK_CMD       0x9A        /* Blink both LEDs multiple time */
+/* 1st parameter: number of LED toggles */
+/* 2nd parameter: delay between each LED toggle, in multiple of 4ms */
 
 /*
  * Audio commands
  *
  * Audio commands can't have 3 parameters, see the above note for details
  */
-#define PLAY_SOUND_CMD      0x90        /* play a sound from the flash sound bank */
+#define PLAY_SOUND_CMD 0x90        /* play a sound from the flash sound bank */
 /* 1st parameter: sound number */
 /* 2nd parameter: sound volume */
-#define STORE_SOUND_CMD     0x52        /* start flash sound bank storage [1] */
+#define STORE_SOUND_CMD 0x52        /* start flash sound bank storage [1] */
 /* 1st parameter: number of sounds to store */
-#define STORE_INDEX_CMD     0xD0        /* get indexes of the flash sound bank [1] */
+#define STORE_INDEX_CMD 0xD0 /* get indexes of the flash sound bank [1] */
 /* 1st parameter: lower address byte */
 /* 2nd parameter: middle address byte */
 /* 3rd parameter: higher address byte */
-#define TEST_SOUND_CMD      0x10        /* test the audio input and output [1] */
+#define TEST_SOUND_CMD 0x10        /* test the audio input and output [1] */
 #define MUTE_CMD            0x92        /* mute/unmute the audio amplifier */
 /* 1st parameter: mute state 0:unmute 1:mute */
 /* 2nd parameter: reserved */
@@ -234,7 +339,7 @@
 #define DEEPSLEEP_MODE 1 /* minimal power consumption, can't wake-up from this
                             mode */
 #define SLEEP_MODE 2 /* standard sleep mode */
-#define SLEEP_ACK_CMD        0xF7       /* acknowledge of the sleep mode command */
+#define SLEEP_ACK_CMD 0xF7 /* acknowledge of the sleep mode command */
 /* 1st parameter: acknowledge of tuxcore */
 /* 2nd parameter: acknowledge of tuxaudio */
 /* 3rd parameter: acknowledge of tuxrf */
@@ -257,8 +362,8 @@
 /* 2nd parameter: PORTC
  *   PC0: phototransistor pull-up load
  *   PC1: wings position switch
- *   PC2: right blue led
- *   PC3: left blue led
+ *   PC2: right blue LED
+ *   PC3: left blue LED
  *   PC4: i2c SDA line
  *   PC5: i2c SCL line
  *   PC6: reset
@@ -269,21 +374,24 @@
  *   PD2: IR receiver signal
  *   PD3: spin position switch
  *   PD4: wings motor forward
- *   PD5: IR led
+ *   PD5: IR LED
  *   PD6: eyes open position switch
  *   PD7: eyes closed position switch
  */
 
-#define SEND_AUDIOSENSORS_CMD       0xF0        /* send sensors status of the audio CPU to the core CPU */
-#define STATUS_SENSORS1_CMD         0xC1        /* send sensors status of the audio CPU to the computer */
+/* send sensors status of the audio CPU to the core CPU */
+#define SEND_AUDIOSENSORS_CMD 0xF0
+/* send sensors status of the audio CPU to the computer */
+#define STATUS_SENSORS1_CMD 0xC1
 /* 1st parameter: switches and status from the audio CPU
  *   .0: left wing push button
  *   .1: right wing push button
  *   .2: power plug insertion switch
  *   .3: head push button
- *   .4: charger led status
- *   .5: rf connection status (0: disconnected, 1: connected)
- *   .6: internal power switch for the audio amplifier, motor drivers and IR led
+ *   .4: charger LED status
+ *   .5: RF connection status (0: disconnected, 1: connected)
+ *   .6: internal power switch for the audio amplifier, motor drivers and IR
+ *       LED
  *   .7: mute status (0: muted, 1: unmuted)
  */
 #define STATUS_LEFTWINGBTN_MK       0x01
@@ -302,12 +410,14 @@
 /* 2nd parameter: light level low byte */
 /* 3rd parameter: light mode: 0: low light, 1:strong light */
 
-#define STATUS_POSITION1_CMD        0xC3        /* send position counters which is related to the motor status */
+/* send position counters which is related to the motor status */
+#define STATUS_POSITION1_CMD 0xC3
 /* 1st parameter: eyes position counter */
 /* 2nd parameter: mouth position counter */
 /* 3rd parameter: wings position counter */
 
-#define STATUS_POSITION2_CMD        0xC4        /* send position counters which is related to the motor status */
+/* send position counters which is related to the motor status */
+#define STATUS_POSITION2_CMD 0xC4
 /* 1st parameter: spin position counter */
 /* 2nd parameter: */
 /* 3rd parameter: */
@@ -320,7 +430,7 @@
 /* 2nd parameter: undefined */
 /* 3rd parameter: undefined */
 
-#define STATUS_ID_CMD	            0xC6
+#define STATUS_ID_CMD               0xC6
 /* 1st parameter: Tux ID number (MSB) */
 /* 2nd parameter: Tux ID number (LSB) */
 
@@ -334,7 +444,7 @@
 /* 2nd parameter: Programming steps :
  *                0 : no programming
  *                1 : Flash erased
- *                2 : TOC 
+ *                2 : TOC
  *                3 : Sounds track */
 /* 3rd parameter: The track number which is programming*/
 
@@ -355,7 +465,7 @@
 /* 1st parameter: number of pongs pending */
 /* 2nd parameter: number of pongs lost by the I2C */
 /* 3rd parameter: number of pongs lost by the RF link */
-#define COND_RESET_CMD  0x3E    /* reset conditional flags that are resettable */
+#define COND_RESET_CMD 0x3E /* reset conditional flags that are resettable */
 
 /*
  * Error numbers
@@ -364,7 +474,8 @@
 enum error_numbers_t
 {
     E_STACK_CORRUPTION,
-    /* 3rd parameter: see source code, depends on the function that report the error */
+    /* 3rd parameter: see source code, depends on the function that report the
+     * error */
     E_STATUS_INVALID,
     /* 3rd parameter: invalid status value */
 };
@@ -375,4 +486,5 @@
 
 #define RESERVED        0
 
+/*! @} */
 #endif /* _COMMAND_H_ */