Maxim Integrated 78M6612 User Manual
A Maxim Integrated Products Brand
78M6612 M-API Library
User Guide
September 30, 2010
Rev. 1.00
UG_6612_036
78M6612 M-API Library User Guide UG_6612_036
Maxim cannot assume responsibility for use of any circuitry other than circuitry entirely embodied in a Maxim product. No circuit
patent licenses are implied. Maxim reserves the right to change the circuitry and specifications without notice at any time.
Maxim Int egrated Products, 120 San Gabriel Drive, Sunnyvale, CA 9408 6 408-737-7600
2010 Maxim Integrated Products Maxim is a registered trademark of Maxim Integrated Products.
UG_6612_036 78M6612 M-API Library User Guide
Table of Contents
1 Introduction ......................................................................................................................................... 5
1.1 Terminology .................................................................................................................................. 5
1.2 Library Measurement Equations ................................................................................................... 6
1.3 Library Parameters ....................................................................................................................... 7
1.3.1 Global Symbols ................................................................................................................. 7
1.3.2 Formulae for Scaled Parameters ...................................................................................... 7
1.3.3 Example Calculation of Sensor Parameters ..................................................................... 8
1.4 Reference Documentation ............................................................................................................ 8
2 Firmware Partitions ............................................................................................................................ 9
3 Build Environment and Software/Firmware Configurations ........................................................ 10
3.1 Firmware Library and CE Mem ory Configurations ..................................................................... 10
3.2 Program and RAM Memory ........................................................................................................ 10
3.2.1 Program Memory ............................................................................................................. 10
3.2.2 RAM/Data Memory .......................................................................................................... 11
3.3 Build Configuration...................................................................................................................... 11
3.3.1 Flash/Code and RAM Size .............................................................................................. 11
3.3.2 Flash/Code Space Assignment ....................................................................................... 12
3.3.3 Library Assignment .......................................................................................................... 13
3.3.4 Module’s Selection within a Library ................................................................................. 14
4 MAPI Libraries ................................................................................................................................... 17
4.1 Library Initialization and Operation ............................................................................................. 17
4.1.1 MAPI_Init() ....................................................................................................................... 17
4.1.2 MAPI_MeterRun() ........................................................................................................... 17
4.1.3 MAPI_MinMaxSetGet() ................................................................................................... 17
4.2 Library Inputs and Outputs ......................................................................................................... 18
4.2.1 MAPI_GetSetRegister() ................................................................................................... 18
4.3 CE and MPU Control .................................................................................................................. 23
4.3.1 MAPI_CEOn().................................................................................................................. 23
4.3.2 MAPI_CEOff().................................................................................................................. 23
4.3.3 MAPI_GetCEName() ....................................................................................................... 23
4.3.4 MAPI_SoftReset() ........................................................................................................... 23
4.3.5 MAPI_HardReset() .......................................................................................................... 24
4.3.6 MAPI_UpdateMPU() ........................................................................................................ 24
4.3.7 MAPI_UpdateCE() ........................................................................................................... 24
4.4 Calibration and Power Measurement ......................................................................................... 25
4.4.1 MAPI_CalSetGet() ........................................................................................................... 25
4.4.2 MAPI_Calibrate() ............................................................................................................. 27
4.4.3 MAPI_MeterStatus() ........................................................................................................ 28
4.4.4 MAPI_TimeToAverage() .................................................................................................. 30
4.4.5 MAPI_GetEnergyUsed() .................................................................................................. 30
4.4.6 MAPI_GetVoltageCurrent() ............................................................................................. 31
4.5 Zero Crossing and Relay Control ............................................................................................... 32
4.5.1 MAPI_RelayConfig() ........................................................................................................ 32
4.5.2 MAPI_RelayControl () ..................................................................................................... 33
4.5.3 MAPI_CloseCircuit_0X() ................................................................................................. 33
4.5.4 MAPI_OpenCircuit_0X() .................................................................................................. 33
4.6 Soft-Timers ................................................................................................................................. 34
4.6.1 MAPIstm_init() ................................................................................................................. 34
4.6.2 MAPIstm_fn_start() ......................................................................................................... 34
4.6.3 MAPIstm_run() ................................................................................................................ 34
4.6.4 MAPIstm_wait() ............................................................................................................... 34
Rev. 1.00 3
78M6612 M-API Library User Guide UG_6612_036
4.7 DIO Configuration (future release) .............................................................................................. 35
4.7.1 MAPI_DIOConfig() .......................................................................................................... 35
4.7.2 MAPI_DIORW() ............................................................................................................... 36
4.8 Flash Management ..................................................................................................................... 37
4.8.1 Memcpy_rx() .................................................................................................................... 37
4.8.2 Memcpy_xr() .................................................................................................................... 38
4.8.3 Memcpy_xx() ................................................................................................................... 38
4.9 Serial/RS232 Interface ................................................................................................................ 39
4.9.1 MAPI_UARTInit() ............................................................................................................. 39
4.9.2 MAPI_UARTTx().............................................................................................................. 39
4.9.3 MAPI_TxLen() ................................................................................................................. 40
4.9.4 MAPI_UARTRx() ............................................................................................................. 40
4.9.5 MAPI_RxLen() ................................................................................................................. 40
5 Default Values ................................................................................................................................... 41
6 Contact Information .......................................................................................................................... 42
Revision History ........................................................................................................................................ 43
Figure
Figure 1: High Level Host/Firmware Interface Architecture
Tables
Table 1: CE Configuration ........................................................................................................................... 10
Table 2: Flash Memory Map ....................................................................................................................... 10
Table 3: Data RAM Shared by CE and MPU .............................................................................................. 11
Table 4: Flash and RAM Consumption by MAPI and Sample Application ................................................. 11
Table 5: Breakdown of M-API’s Flash Consumption .................................................................................. 11
Table 6: MAPI Feature/Module Selections ................................................................................................. 15
.......................................................................... 9
4 Rev. 1.00
UG_6612_036 78M6612 M-API Library User Guide
1 Introduction
This document describes the Metrology Appl icat ion Pro gr am ming Interface (M-API) version 2.00 firmware
libraries available from Teridian for use with the 78M6612 IC. These libraries are specifically designed for
measurement and switch control of two (2) single-phase AC outlets (same phase).
The firmware delivery is a set of metrology libraries that configure and operate the measurement front
end (e.g. MUX, ADC, CE, etc.) and provides simplified access to measurement output data such as
Power, Voltage, Current, accumulated Energy and Line Frequency. All measurement calculations are
computed by the MAPI library every accumulation interval and mapped to a dedicated block of registers
reserved by the library.
Measurement data are made available to the user application via API calls. A demo application making
use of the M-API library set and serial UART interface is included as part of the 78M6612 OMU
Evaluation Kit.
Timer functions using the hardware RTC are also available and can be accessed directly by the
application. APIs specific to RTC are not available in the current library. Contact a Teridian
representative for more information on non-Volatile RTC operation (e.g. battery backup modes).
1.1 Terminology
The following terminology is used throughout this document:
• CREEP – Threshold value where meas urem ent outp ut s are sque lched t o zero.
• IMAX – External RMS current corresponding to 250 mVpk at the current input of the 78M6612. It should be set
IMAX= (Vpk/√2)/R
• VARs – Reactive Power (Q)
SENSE
.
• VAs – Apparent Power (S).
• Watts – Active Power (P).
• VMAX – External RMS voltage corresponding to 250 mVpk at the voltage input of the 78M6612 (VA, VB). It
must be set high enough to account for over-voltages.
• NB – Narrowband values.
• WB – Wideband values.
Rev. 1.00 5
78M6612 M-API Library User Guide UG_6612_036
1.2 Library Measurement Equations
The integrated Compute Engine (CE) accumulates the raw samples from the ADC and provides to the
80515 MPU the critical *atomic measurements needed to derive all other data. This consists of RMS
Voltage, Voltage Sag Status , and AC Line Freq uency data as well as RMS Current, Active Po wer, and
Reactive Power for each outlet. The MAPI library provides the application developer with two equation
options for processing the atomic values before updating the libraries output data registers. One equation
option is defined as “Narrowband” (NB) and the other is defined as “Wideband” (WB).
When using NB equations; RMS Voltage, Active Power, and Reactive Power data is provided by
the CE and used to derive RMS Current, Apparent Power, and Power Factor in the MPU for each
outlet. Harmonic content is not included in the reported current measurement.
*Voltage (V
Current (I
) = √∑v(t)2
RMS
) = S/V
RMS
RMS
*Active Power (P) = ∑ (i(t) * v(t))
*Reactive Power (Q) = ∑ (i(t) * v(t) shift 90º)
Apparent Power (S) = √(P
2
+ Q2)
Power Factor (PF) = P/S
When using WB equations (recommended); RMS Voltage, RMS Current, and Active Power data
provided by the CE is used to derive Reactive Power, Apparent Power, and Power Factor in the
MPU for each outlet.
*Voltage (V
*Current (I
) = √∑v(t)2
RMS
) = √∑i(t)2
RMS
*Active Power (P) = ∑ (i(t) * v(t))
RMS
2
– P2)
* I
RMS
Reactive Power (Q) = √(S
Apparent Power (S) = V
Power Factor (PF) = P/S
6 Rev. 1.00
UG_6612_036 78M6612 M-API Library User Guide
1.3 Library Parameters
This section describes critical constants and variable parameters of the MAPI library and their
recommended usage.
1.3.1 Global Symbols
The following symbols are fixed constants for the MAPI v2.00 firmware library:
Samples : 1806
FS : 3641
POWERSCALE : 2.3439E-06
VRMS_MSCALE : 9.6827E-05
IRMS_MSCALE : 2.4207E-05
The following variables are unique to the sensor configuration and represent the real world values
mapped to the upper range of the 78M6612 analog front end.
IMAX : 52 Amps for 4mOhm shunt
VMAX : 471.5 Volts
1.3.2 Formulae for Scaled Parameters
The measurement outputs (and respective alarm thresholds) for the M-API library are stored in a raw
format to preserve native resolution of the computed measurements. When using API calls to access or
fetch measurement data, the values are automatically scaled and converted according to the data types,
below.
I
rms
V
rms
Watts = float(Val)* POWERSCALE*IMAX*VMAX/1000
Frequency = integer(Val)/100
Val : library data
In some rare cases, when raw measurement data (Val) is directly accessed without going through the
library, which is not recommended, scaling to and from real world or usable values must be done using
the formulae above.
= float(Val)* IRMS_MSCALE* IMAX*√(FS/Sampl es)
= float(Val)* VRMS _MSCALE* VMAX*√(FS/Samples)
Rev. 1.00 7
78M6612 M-API Library User Guide UG_6612_036
1.3.3 Exam pl e Calculati on of Sensor Parameters
This example demonstrates the calculation of IMAX and VMAX for the default sensor configuration. For
more information on sensor selection and configuration, refer to the 78M6612 Hardware Design
Guidelines.
IMAX Calculation:
IMAX = Imax (pk) / sqrt(2) = Imax (rms)
Max ADC input = 250 mV = IMax (pk) * R shunt
Example:
With a 4 MΩ current shunt, IMax (pk) = 62.5A
=> IMAX = 52 Amps.
VMAX Calculation:
VMAX = Vmax (pk) / sqrt(2) = Vmax (rms)
Max ADC input = 250 mV = Vmax (pk) * Shunt R / (Series R - Shunt R)
Example:
With a Series R of 2 MΩ and a Shunt R of 750 ohms, VMax (pk) = 666.42 Volts.
=> VMAX = 471.23 Volts
1.4 Reference Documentation
• 78M6612 Data Sheet
• 78M6612 Hardware R efer e nce Manua l
• 78M6612 OMU Evaluat ion Boar d User Manua l (reference schematics)
• 78M6612 OMU Demo Application User Manual (CLI)
• 78M6612 OMU Firmware Description Document (register descriptions)
8 Rev. 1.00
UG_6612_036 78M6612 M-API Library User Guide
UART/RS232 or I2C
Serial/I2C Host
Application
Host Controller
78M6612
CE
M-API
Application
2 Firmware Partitions
The 78M6612 firmware provided by Teridian is partitioned into three main components:
• The Compute Engine (CE) firmware, although a separate set of source code, is a component of the
MAPI libraries responsible for precision Voltage, Current, Watts, and VARs measurements handled
by a dedicated processor. The source code for the CE is not described in this document or made
available for user modification.
• The 80515-based M-API firmware, in combination with the CE firmware, completes the M-API librar y
set and provides all the necessary IC configuration, calibration sub-routines, scaling, data conversion,
and timing control. This set of libraries is to be linked to the application firmware specific to the
desired host interface.
• The Application firmware exercises the M-API library and manages the communication to the host
controller/application. Teridian provides an example Serial Driver to be used as sample code as well
as the application firmware that uses this Serial Driver to exercise the MAPI library. Refer to the
applicable Firmware Description Document for more information on the application firmware.
Figure 1 shows a high level partitioning of the firmware architecture. The black boxes indicate object
and
code to be provided by Teridian. The white box indicates object
source code provided by Teridian.
Figure 1: High Level Host/Firmware Interface Architecture
Rev. 1.00 9
78M6612 M-API Library User Guide UG_6612_036
3 Build Environment and Software/Firmware Configurati ons
The Metrology Application Programming Interface (MAPI) is built using Keil Compiler version 8.02,
although any Keil version 7.00 or higher is also compatible.
The MAPI is built using specific default configuration as listed below.
3.1 Firmware Library and CE Memory Configurations
Processing of ADC inputs is done by the CE. The MAPI libraries are built to link to the specific CE code
according to the specific hardware conf ig urati on. The table below shows the different libraries as built
with specific CE code to support different configurations:
Table 1: CE Configuration
Library Name Default Accumulation Interval = 500ms
6612S22_WB_MAPI.lib Built for Wide-Band.
6612S22_NB_MAPI.lib Built for Narrow-Band.
3.2 Program and RAM Memory
The embedded 80515 MPU within the 78M6612 has separate program memory (32K bytes) and data
memory (2K bytes).
3.2.1 Pr ogr am Memory
The Flash program memory is non-volatile and is segmented into 512-byte pages. The last 2.5K (five
512-byte pages) of Flash space is reserved for CE data, CE code and default values used for Energy
Calibration and Measurement. The code for the Compute Engine program resides in the MPU program
memory (flash) and must begin on 1K-byte boundary.
Table 1 below shows the partitions of Flash memory.
Table 2: Flash Memory Map
Address (hex) Type Typical Usage
0000-75FF
7600-773E
777F-7FFF Non-volatile
Non-volatile
Non-volatile
Program and any non-volatile
data. Shared by the MAPI and
application layer.
Reserved for MAPI energy
measurement constants
(defaults).
Reserved for CE code and CE
data.
Wait States
(at 5 MHz)
0
0
0
Size (bytes)
29.5KB
< ~350B
2KB
10 Rev. 1.00
UG_6612_036 78M6612 M-API Library User Guide
3.2.2 RAM/Data Memory
The 78M6612 has 2K bytes of Data Memory for exclusive use by the embedded 80515 MPU library and
application layers. In addition, there are 512 bytes reserved for the Compute Engine.
Table 3: Data RAM Shared by CE and MPU
Address (hex) Type Typical Usage Size (bytes)
0000-07FF Volatile MPU data XRAM, 2KB
1000-11FF Volatile CE data 512
2000-20FF Volatile
Miscellaneous I/O RAM
(configuration RAM)
256
3.3 Build Configuration
The accompanying example application source code has been set up to link to each library under specific
hardware configuration. Each configuration is defined under a different ‘Target’. However, for all ‘Targets’,
specific area of Flash is reserved for specific function as described below.
3.3.1 Flash/Code and RAM Size
The attached zipped file (78M6612MAPIv200.zip) contains a sample Application code, of which source
code is also included. The functions of this application are detailed in Section 6.
This sample applic at ion is taking up Flash/RAM usage according to the table below. It was written to
demonstrate the use of the MAPI libraries via two types of commands: the ‘M’ commands (as shown in
Section 6) to specifically address the MAPI calls; and the ‘CLI’, aka Command Line Interface, commands
for backward compatibility to support those who have evaluated, or are familiar with, Teridian OMU
products in the past.
The following tables show RAM and Flash consumptions by this sample application. They also show a
breakdown of Flash consumption by different features as implemented in the MAPI libraries.
Table 4: Flash and RAM Consumption by MAPI and Sample Application
Firmware Module
6612S22_WB_MAPI.lib
6612S22_NB_MAPI.lib
6612IVIV_50F0_v200WB.hex
6612IVIV_50F0_v200NB.hex
Table 5: Breakdown of M-API’s Flash Consumption
Library:
6612S22_WB_MAPI.lib
6612S22_NB_MAPI.lib
Calibration 5.7K Includes calibration for: Temperature, Current, Voltage,
Initialization, Default Settings 5.8K Initializes Defaults, Metering Constants Tables,
MAPI Interface (to App) 1.5K Direct interface to the library from application.
Flash Manager 2K Flash Read/Write management.
Rev. 1.00 11
RAM
Used
~ 26K The RAM usage is overlay-able. See the
1.7K 6K + 26K(lib) The app from this build uses every single API
Flash Used Features
Flash Used Note
breakdown of Flash usage in Table 5.
library call.
Watt and Phase.
Registers, etc.
78M6612 M-API Library User Guide UG_6612_036
Metering 6K Metrology functions (alarms, power factor, RMS, etc.)
Measurement 2K Metrology computations
Serial Driver 1K Serial 0/RS232 I/O
Timer < 0.5K Timer 0 driver.
Relay Management/Misc . 2K Relay Control/On/Off, some math logic, IRQ.
3.3.2 Flash/Code Space Assignment
As shown in Table 1, in order to reserve specific regions of Flash for specific MAPI default data, CE code
and CE data, the build file of the firmware application must be setup to specify where the modules will
reside. It is necessary to keep images of CE code/data and default data isolated at the application’s build
file. The accompanying application code has setup these assignments as follows: Default data is at
starting address 0x7600. CE Data is at starting address 0x777E. CE Code is at starting address
0x77FE.
This information is represented in the mapped file (.M51) as follows:
SEGMENTS (?CO?DEFAULTS(C:0X7600),
?CO?CEIVIV200F0_1_DAT(C:0X777E),
?CO?CEIVIV200F0_1_CE (C:0X77FE))
The following figures show how the setup is done.
12 Rev. 1.00
UG_6612_036 78M6612 M-API Library User Guide
3.3.3 Library Assignment
The firmware application source code, as shipped with this document, is setup such that its project file
contains all the supported libraries as built for the specific CE code and data to support different
configuration options. As sho wn in the projec t, the libr ar ies built for Narrow-Band and Wide-Band are
included in the project but only one library shall be selected to be built with a specific ‘Target’ at a time.
The ‘Target’s as defin ed in the Keil proj ec t file for the sample application are shown below. When modify
this project’s targets, it is important that the correct library is selected:
Rev. 1.00 13
Loading...