EfiO2Meter DataTransfer

From efiHacks Wiki
Jump to: navigation, search

Contents

Serial Data Transfer Structures

This page provides an overview of the efiO2Meter serial data streams and packages.

In addition to our application software we provide an open interface policy to enable any customer to design their own interface to get the measured data and being able to configure the efiO2Meter with their own individual hardware and software.

There are 2 different ways to get the data from the efiO2Meter, one being an ASCII readable data stream in CSV format and the other in binary data package format. For easier debugging we also provide the data packages in ASCII chars with the disadvantage of 1/3 data rate of the binary throughput.

We also offer sample interface code in Java and C# along with data access funtions to the package data.

Binary Data Structure definitions

The following paragraphs outline the transmitted binary data package formats.
The packages are sync'ed with a sync character 0x02 in the package header and byte stuffed with and additional sync characted in case the sync value appears within the data stream. This additional sync character in the data stream only applies to the 1st one in case of multiple back to back sync data values.

UniTalk Data Definitions

We developed a generic package transfer protocol which we call UniTalk. This consists of a simple 4 Byte header (3 would be sufficient, but the Arm CPUs require 4 byte aligned data structures to save code space and faster run-time performance, followed by the data bytes.
A package has to be less then or max 64 bytes. This makes it conform to the USB implementation on our Arm CPUs. More smaller packages also allow to more rapidly send the inportant data and put the less important data at a lower rate in between the repetion of the time critical data.

A UniTalk package starts with a spacer / align byte "nid" which could be used as a node ID or similar, but currently only align / space function.
The next byte is the total package length including the header. Since a null package at least consists of the 4 byte header, there can be no length being less than 4 guaranteeing being a NON-Sync byte.
Followed by a sync byte 0x02.
The last byte of this UniTalk header is the UniTalk package type as outlined in the code sample below.

UniTalk Package Definition Bit-Fields

This UniTalk package type consists of the following fields :

  1. bit 0 - 3 : there are currently 4 data format types in use
    eTNOP (unused at the moment)
    eTDAT is the simplest header format, adding the data immediately after the header.
    eTREC the record data format adds a 2byte record type (addr) to the eTDAT format.
    eTHEX the hex data format adds a 4 byte hex data byte count field and a 4 byte hex read / write address to a TREC package.
    there is still room for types 0x06 to 0x0f for type expansion.
  2. bit 4 - 5 : data transfer types
    bTRO read only : performs a read data at the receipient end and returns the requested data.
    bTWO write only : performs a write sent data at the receipient end, no data is returned.
    bTRW read / write : performs a data read at the receipient end before the sent data is written. The read data is then returned to the initiator.
    bTWR write / read : performs a write of the sent data at the recepient end and then reads the data back (depending on the hardware, it can be different data than written) and sends it back to the initiator.
    bit 6 : transfer direction flag, indicating that package is a request or acknowledge package.
    bit 7 : indicates an error condition to the other side.

UniTalk Package Definition Enumerations

  enum eTYP { eNID  = 0x00,
	      eTNOP = 0x00,
	      eRESV = 0x01,	/* reserved		*/ <br/>
	      eSYNC = 0x02,	/* sync	   byte		*/ <br/>
	      eTDAT = 0x03,	/* data    package	*/ <br/>
	      eTREC = 0x04,	/* record  package	*/
	      eTHEX = 0x05,	/* hex-rec package	*/
	      bTMSK = 0x0f,	/* type    mask		*/

	      bTRO  = 0x00,	/* read    only		*/
	      bTWO  = 0x10,	/* write   only		*/
	      bTRW  = 0x20,	/* read    write	*/
	      bTWR  = 0x30,	/* write   read		*/
	      bTOP  = 0x30,	/* operation mask	*/

	      bTREQ = 0x00,	/* request package	*/
	      bTACK = 0x40,	/* ackn.   package	*/
	      bTDIR = 0x40 } ;	/* direction mask	*/

  enum eREG { bRERR = 0x8000,
	      bRMSK = 0x7fff } ; 

UniTalk Package Data Structure Definitions

  typedef struct {
    BYTE nid ;		/*   1,  1	bytes	*/
    BYTE len ;		/*   1,  1	bytes	*/
/* - - 	buffer DWORD alignment	- - */
    BYTE sync ;		/*   1,  1	bytes	*/
    BYTE typ ;		/*   1,  1	bytes	*/
  } PACKED Hdr_t ;	/*   4		bytes	*/

  enum { eHdrSz = sizeof(Hdr_t) } ;

  typedef struct {
    Hdr_t h ;		/*   4,  4	bytes	*/
    BYTE   dat[1] ;	/* NOT word-4 aligned	*/
  } PACKED Dat_t ;	/*   4		bytes	*/

  enum { eDatSz = sizeof(Dat_t) - sizeof(BYTE) } ;

  typedef struct {
    Hdr_t h ;		/*   4,  4	bytes	*/
    WORD   reg ;	/*   2,  2	bytes	*/
    BYTE   dat[1] ;
  } PACKED Rec_t ;	/*   6		bytes	*/

  enum { eRecSz = sizeof(Rec_t) - sizeof(BYTE) } ;

  typedef struct {
    Hdr_t h ;		/*   4,  4	bytes	*/
    WORD   reg ;	/*   2,  2	bytes	*/
    DWORD  cnt ;	/*   4,  4	bytes	*/
    void  *adr ;	/*   4,  4	bytes	*/
    BYTE   dat[1] ;
  } PACKED Hex_t ;	/*  14		bytes	*/

  enum { eHexSz = sizeof(Hex_t) - sizeof(BYTE) } ; 

RunTime Data Definitions

These data structures are typically the enclosed payload of the Unitalk Packages.

RunTime Data Package Content

There are 5 types of RunTime Data Structures being sent from the efiO2Meter over a serial channel to the host computer.

Each one of these RunTime Data Packages have a unique Unitalk Record Addr.

  • RtData0 record addr : 0x0010
  • RtData1 record addr : 0x0011
  • RtData2 record addr : 0x0012
  • RtDataP record addr : 0x0013

RunTime Data Package Headers

Four of them contain a RunTime Data Package Header and one, the Print Debug Channel does not.

  • RtData0 RunTime Data ID : 0x0021
  • RtData1 RunTime Data ID : 0x0022
  • RtData2a RunTime Data ID : 0x0024
  • RtData2b RunTime Data ID : 0x0028

The 1st byte is the Package Identifier ID.
Followd by an incrementing package number Pkg to detect the missing of packages.
And finally a 4 byte timestamp Tref in milli-seconds.

  typedef struct {
    WORD   Lo, Hi ;			/*   4,  2 x 2	bytes	*/
  } PACKED Tref_t ;			/*   4		bytes	*/

  typedef struct {
    BYTE   Id ;				/*   1,  1	bytes	*/
    BYTE   Pkg ;			/*   1,  1	bytes	*/
    Tref_t Tref ;			/*   4,  4	bytes	*/
  } PACKED Hdr_t ;			/*   6		bytes	*/ 

RtData0 RunTime Data Structure

This is the most frequently sent data package structure.

  typedef struct {			/*   6,	 rec	bytes	*/
    Hdr_t  Hdr ;			/*   6,  6	bytes	*/

    short  Dat[2] ;			/*   4,  2 x 2	bytes	*/
    WORD   Lam[2] ;			/*   4,  2 x 2	bytes	*/
    short  Cur[2] ;			/*   4,  2 x 2	bytes	*/
    short  Htr[2] ;			/*   4,  2 x 2	bytes	*/
    BYTE   Mod[2] ;			/*   2,  1 x 2	bytes	*/

    WORD   Tim ;			/*   2,  2	bytes	*/
    WORD   Rpm ;			/*   2,  2	bytes	*/
    WORD   Acc ;			/*   2,  2	bytes	*/

    WORD   Ext ;			/*   2,  2	bytes	*/
    WORD   Tpv ;			/*   2,  2	bytes	*/
    BYTE   Tps ;			/*   1,  1	bytes	*/
    BYTE   Typ ;			/*   1,  1	bytes	*/
  } PACKED RtData0_t ;			/*  36, 42	bytes	*/ 

RtData1 RunTime Data Structure

This is the 2nd most frequently sent data package structure.

  typedef struct {			/*   6,	 rec	bytes	*/
    Hdr_t  Hdr ;			/*   6,  6	bytes	*/

    WORD   ADat[2] ;			/*   4,  2 x 2	bytes	*/
    WORD   RDat[2] ;			/*   4,  2 x 2	bytes	*/

    short  PErr[2] ;			/*   4,  2 x 2	bytes	*/
    short  PDat[2] ;			/*   4,  2 x 2	bytes	*/
    short  IDat[2] ;			/*   4,  2 x 2	bytes	*/
  } PACKED RtData1_t ;			/*  26, 32	bytes	*/ 

RtData2a RunTime Data Structure

This is one of the less frequently sent data package structure.

  enum { eAraw, eAavg, eAvlt, eAdat, eAmax } ;

  typedef struct {			/*   6,	 rec	bytes	*/
    Hdr_t  Hdr ;			/*   6,  6	bytes	*/

    WORD   ACal[2][2] ;			/*   8,  2 x 4	bytes	*/
    WORD   RCal[2] ;			/*   4,  2 x 2	bytes	*/
    WORD   VBat ;			/*   2,  2	bytes	*/

    BYTE   Spc ;			/*   1,  1	bytes	*/
    BYTE   Adx ;			/*   1,  1	bytes	*/
    WORD   AdcDat[TAdc::eCmax] ;	/*  22,  2 x 11	bytes	*/
  } PACKED RtDat2a_t ;			/*  44, 50	bytes	*/ 

RtData2b RunTime Data Structure

This is another less frequently sent data package structure.

  typedef struct {
    WORD   Min,  Max ;			/*   4,  2 x 2	bytes	*/
  } PACKED Plim_t ;			/*   4		bytes	*/

  typedef struct {
    short  Dat0, Dat1 ;			/*   4,  2 x 2	bytes	*/
    WORD   Sel ;			/*   2,  2	bytes	*/
  } PACKED Dset_t ;			/*   6		bytes	*/

  typedef struct {
    bool   CjEna ;			/*   1,  1	bytes	*/
    bool   Lsu49 ;			/*   1,  1	bytes	*/

    WORD   Xp, Xi ;			/*   4,  2 x 2	bytes	*/

    WORD   CAir ;			/*   2,  2	bytes	*/

    Plim_t Plim[2] ;			/*   8,  4 x 2	bytes	*/
    Dset_t Dset[2] ;			/*  12,  6 x 2	bytes	*/

    WORD   HErr ;			/*   2,  2	bytes	*/
    WORD   LErr ;			/*   2,  2	bytes	*/
    WORD   SErr ;			/*   2,  2	bytes	*/
  } PACKED Cha_t ;			/*  34		bytes	*/

  typedef struct {
    BYTE   DivX ;			/*   1,  1	bytes	*/
    BYTE   Fsel ;			/*   1,  1	bytes	*/
    BYTE   Rsel ;			/*   1,  1	bytes	*/
    BYTE   Spc ;			/*   1,  1	bytes	*/

    WORD   TimW ;			/*   2,  2	bytes	*/

    WORD   DivP ;			/*   2,  2	bytes	*/
    WORD   MulP ;			/*   2,  2	bytes	*/

    WORD   V120 ;		/* ee-cal    2,  2	bytes	*/
    WORD   V033 ;		/* ee-cal    2,  2	bytes	*/
  } PACKED Cfg_t ;			/*  14		bytes	*/

  enum { eUch0, eUch1, eUcfg, eUmax } ;

  typedef struct {			/*   6,	 rec	bytes	*/
    Hdr_t  Hdr ;			/*   6,  6	bytes	*/

    BYTE   Spc ;			/*   1,  1	bytes	*/
    BYTE   Uni ;			/*   1,  1	bytes	*/
    union {
      Cha_t  Cha ;			/*  34, 34	bytes	*/
      Cfg_t  Cfg ;			/*  14, 14	bytes	*/
    } ;
  } PACKED RtDat2b_t ;			/*  42, 48	bytes	*/ 

RtDataP RunTime Data Structure

This data structure contains any serial print debug information sent from the efiO2Meter.


  enum { ePrnSz = 0x30 } ;

  typedef struct {			/*   6,	 rec	bytes	*/
    char   Cnt ;			/*   1,  1	bytes	*/
    char   Dat[ePrnSz] ;		/*  48,  1 x 48	bytes	*/
  } PACKED RtDataP_t ;			/*  49, 55	bytes	*/  

Sample Data Packet Transfer Snippet

Below is a short snippet of the binary package transfer ... not all binary since the ASCII flag was on and encodes any 8-bit into a ASCII hex pair

 
 00 32 02 14 12 00 28 fe 00 08 ce 00 00 01 00 01 64 00 64 00 7b 00 00 00 88 13 00 00 72 06 8a 02 02 30 75 08 00 b6 03 1a 04 00 00 00 00 00 00 00 00 27
 00 2b 02 14 10 00 21 e7 00 20 cf 00 c5 05 00 00 ed 03 00 00 06 00 00 00 b8 0c 00 00 00 01 00 00 00 00 00 00 7b 11 68 11 35 00 2e
 00 08 02 14 13 00 20 8d
 00 2b 02 14 10 00 21 e8 00 20 cf 00 c5 05 00 00 ed 03 00 00 06 00 00 00 b8 0c 00 00 00 01 00 00 00 00 00 00 7c 11 68 11 35 00 76
 00 08 02 14 13 00 20 8d
 00 2b 02 14 10 00 21 e9 00 38 d0 00 c6 05 00 00 ee 03 00 00 07 00 00 00 b8 0c 00 00 00 01 00 00 00 00 00 00 7c 11 69 11 35 00 0d
 00 21 02 14 11 00 22 fc 00 38 d0 00 17 06 01 00 40 0a 00 00 00 00 00 00 00 00 00 00 00 00 00 00 66
 00 2b 02 14 10 00 21 ea 00 50 d1 00 c6 05 00 00 ee 03 00 00 07 00 00 00 b8 0c 00 00 00 01 00 00 00 00 00 00 7c 11 69 11 35 00 91
 00 08 02 14 13 00 20 8d
 00 2b 02 14 10 00 21 eb 00 68 d2 00 c6 05 00 00 ee 03 00 00 08 00 00 00 b8 0c 00 00 00 01 00 00 00 00 00 00 7c 11 69 11 35 00 b6
 00 3a 02 14 12 00 24 fe 00 80 d3 00 10 06 0f 06 01 00 01 00 14 02 02 00 00 c1 30 00 02 02 14 02 02 3f 0a e6 03 e5 03 ea 03 00 00 00 00 00 00 00 00 00 00 ca 08 31 0b 3d 0b 51
 00 2b 02 14 10 00 21 ec 00 80 d3 00 c5 05 00 00 ed 03 00 00 06 00 00 00 b7 0c 00 00 00 01 00 00 00 00 00 00 7b 11 68 11 35 00 b2
 00 08 02 14 13 00 20 8d
 00 2b 02 14 10 00 21 ed 00 80 d3 00 c6 05 00 00 ee 03 00 00 07 00 00 00 b7 0c 00 00 00 01 00 00 00 00 00 00 7c 11 68 11 35 00 d3
 00 08 02 14 13 00 20 8d
 00 2b 02 14 10 00 21 ee 00 98 d4 00 c6 05 00 00 ee 03 00 00 07 00 00 00 b8 0c 00 00 00 01 00 00 00 00 00 00 7b 11 69 11 35 00 fa
 00 21 02 14 11 00 22 fd 00 98 d4 00 16 06 01 00 3f 0a 00 00 00 00 00 00 00 00 00 00 00 00 00 00 1e
 00 2b 02 14 10 00 21 ef 00 98 d4 00 c6 05 00 00 ee 03 00 00 07 00 00 00 b8 0c 00 00 00 01 00 00 00 00 00 00 7b 11 69 11 35 00 1a
 00 08 02 14 13 00 20 8d
 00 2b 02 14 10 00 21 f0 00 b0 d5 00 c6 05 00 00 ee 03 00 00 07 00 00 00 b8 0c 00 00 00 01 00 00 00 00 00 00 7c 11 69 11 35 00 e4
 00 34 02 14 12 00 28 ff 00 b0 d5 00 00 02 02 00 02 02 00 00 88 13 7b 00 00 00 d2 04 e4 0c 72 06 8a 02 02 30 75 08 00 b6 03 1a 04 00 00 00 00 00 00 00 00 be
 00 2b 02 14 10 00 21 f1 00 c8 d6 00 c6 05 00 00 ee 03 00 00 07 00 00 00 b7 0c 00 00 00 01 00 00 00 00 00 00 7b 11 68 11 35 00 4a
 00 08 02 14 13 00 20 8d
 00 2b 02 14 10 00 21 f2 00 e0 d7 00 c5 05 00 00 ed 03 00 00 06 00 00 00 b8 0c 00 00 00 01 00 00 00 00 00 00 7b 11 68 11 35 00 43
 00 08 02 14 13 00 20 8d
 00 2b 02 14 10 00 21 f3 00 e0 d7 00 c5 05 00 00 ed 03 00 00 06 00 00 00 b7 0c 00 00 00 01 00 00 00 00 00 00 7c 11 69 11 35 00 a5
 00 21 02 14 11 00 22 fe 00 e0 d7 00 16 06 01 00 3f 0a 00 00 00 00 00 00 00 00 00 00 00 00 00 00 59
 00 2b 02 14 10 00 21 f4 00 e0 d7 00 c6 05 00 00 ee 03 00 00 07 00 00 00 b8 0c 00 00 00 01 00 00 00 00 00 00 7b 11 69 11 35 00 ba 


More to come as soon as we qualify more firmware for publication.


Note : All published design documentation is Copyright efiLabs.com and its use is without exception FOR NON COMMERCIAL PURPOSE ONLY. For commercial licenses contact efilabs.com ... try us, we're reasonable :)

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox