A Maxim Integrated Products Brand 78M6612 M-API Library User Guide September 30, 2010 Rev. 1.
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 Integrated Products, 120 San Gabriel Drive, Sunnyvale, CA 94086 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.
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 .........................................
UG_6612_036 78M6612 M-API Library User Guide 1 Introduction This document describes the Metrology Application Programming 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.
78M6612 M-API Library User Guide 1.2 UG_6612_036 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 Frequency data as well as RMS Current, Active Power, and Reactive Power for each outlet.
UG_6612_036 1.3 78M6612 M-API Library User Guide 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 FS POWERSCALE VRMS_MSCALE IRMS_MSCALE : 1806 : 3641 : 2.3439E-06 : 9.6827E-05 : 2.
78M6612 M-API Library User Guide 1.3.3 UG_6612_036 Example Calculation 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.
UG_6612_036 78M6612 M-API Library User Guide 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.
78M6612 M-API Library User Guide UG_6612_036 3 Build Environment and Software/Firmware Configurations 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.
UG_6612_036 3.2.2 78M6612 M-API Library User Guide 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 512 2000-20FF Volatile CE data Miscellaneous I/O RAM (configuration RAM) 256 3.
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 Relay Management/Misc. 3.3.2 2K Timer 0 driver. Relay Control/On/Off, some math logic, IRQ.
UG_6612_036 3.3.3 78M6612 M-API Library User Guide 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 shown in the project, the libraries 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.
78M6612 M-API Library User Guide 3.3.4 UG_6612_036 Module’s Selection within a Library The M-API libraries are organized into separate modules based on their functions so that code size and RAM size can be easily optimized during Keil’s build/link time. Some of the modules are mandatory and must be included while others can be de-selected to save Flash space if the functions/features are not used. Typically, when an API is called directly, the Keil Linker would automatically include the module.
UG_6612_036 78M6612 M-API Library User Guide Table 6: MAPI Feature/Module Selections Module Optional (O)/Mandatory (M) ?C_STARTUP M CEIVIV200F0_1_CE CEIVIV200F0_1_DAT M CALW (Watt cal) CALP (Phase cal) CALT (Temperature cal) CALV (Volt cal) CALI (Current cal) REINIT_CALI (Current cal) FLASH LIBRARY TSC ACCESS DEFAULTS SET_DEFAULTS MAPI 80515 Startup CE data and code modules O O O O O M (if any CALW/CALI is M) If calib2ration is required, these modules are needed based on the type of calibration i
78M6612 M-API Library User Guide UG_6612_036 The following figure shows the Keil IDE/UV4 IDE menu where the module can be selected or de-selected. To invoke this menu, left-click on a highlighted library and select ‘Options for File ‘6612S22_NB_MAPI.LIB or 6612S22_WB_MAPI.LIB’: 16 Rev. 1.
UG_6612_036 78M6612 M-API Library User Guide 4 MAPI Libraries The following sections describe the available MAPI calls supported by these libraries. 4.1 Library Initialization and Operation 4.1.1 4.1.2 4.1.3 MAPI_Init() Purpose Initialize all critical variables, start the Compute Engine (CE) and its interrupts, start the MPU timer, setup all default values. The application must first call this API before any attempt to use other APIs. Synopsis Void MAPI_Init( Parameters None. Return Codes None.
78M6612 M-API Library User Guide UG_6612_036 4.2 Library Inputs and Outputs 4.2.1 MAPI_GetSetRegister() Purpose Get or Set the value of a specific register location. An error will be returned if the address is out of range or within the restricted location. Care must be taken when calling this API to Set the value into a register. There are three types of registers: MPU, CE and I/O Hardware Control.
UG_6612_036 Parameters 78M6612 M-API Library User Guide Operation Input parameter. WRITE(1) – Set Operation, READ(0) – Get Operation. Struct _Reg_t When Operation=READ, Output parameter. When Operation=WRITE, Input parameter. Address Four-byte address location. Address where its content will be extracted (Operation=READ) or stored (Operation = WRITE). Value Four-byte value to be stored or retrieved. If Content from Address to be extracted (Operation=READ) or stored (Operation = WRITE).
78M6612 M-API Library User Guide UG_6612_036 4.2.1.1 Auto-Scaling When retrieving measurement data using the MAPI_GetSetRegister() call, the returned data value is automatically converted to usable data according to the TypeSize of the register location. The ScaleFactor is for information only. When writing alarm thresholds to library input registers, usable data values are automatically converted to raw values according to the TypeSize of the target register address. 4.2.1.
UG_6612_036 78M6612 M-API Library User Guide 4.2.1.3 MPU Library Inputs The following inputs can be modified (and saved to Flash) using API calls. For more information on register descriptions, refer to the 6612_OMU Firmware Description Document.
78M6612 M-API Library User Guide UG_6612_036 4.2.1.4 CE Library Inputs The following inputs can only be modified (and saved to Flash) using API calls. For more information on register descriptions, refer to the 6612 OMU Firmware Description Document.
UG_6612_036 78M6612 M-API Library User Guide 4.3 CE and MPU Control 4.3.1 4.3.2 4.3.3 4.3.4 MAPI_CEOn() Purpose Turn CE on. After calling MAPI_Init(), CE is automatically turned on. This API is provided as a convenience for the Application level to control the CE, especially when reading/writing to Flash is necessary (writing to Flash is not allowed when CE is on). Synopsis void MAPI_CEOn ( void ); Parameters None. Return Codes None. MAPI_CEOff() Purpose Turn CE off.
78M6612 M-API Library User Guide 4.3.5 4.3.6 4.3.7 24 UG_6612_036 MAPI_HardReset() Purpose Reset the MPU, this includes stopping the CE, and setting all registers to hardware Power-On Reset values. Synopsis void Parameters None. Return Codes None. MAPI_HardReset ( Void ); MAPI_UpdateMPU() Purpose Update the MPU contents permanently into Flash. The MPU measurement input and calibration default values are stored in Flash.
UG_6612_036 78M6612 M-API Library User Guide 4.4 Calibration and Power Measurement 4.4.1 MAPI_CalSetGet() Purpose Set or Get Calibration referenced and tolerance parameters as specified in the MPU_CParms_t structure. New values are kept in RAM only. When all calibration data is setup and calibrated correctly, it shall be kept and recorded, permanently in Flash by calling MAPI_UpdateCE() and MAPI_UpdateMPU(). A typical calibration of the part proceeds as follows: 1. Call MAPI_CalSetGet (FALSE, ….
78M6612 M-API Library User Guide Parameters SetData UG_6612_036 Input parameter. TRUE(1) – Set calibration data as specified in MPU_CParms_t. FALSE(0) – Get current calibration data and return values in MPU_CParms_t. MAPI_CParams: C_Tcal Input parameter – read-only. Calibration type. None(0x00). C_Wcal Output parameter (SetData = FALSE), Input parameter (SetData = TRUE) Referenced Wattage calibration value (in Watts). Default = 120W.
UG_6612_036 4.4.2 78M6612 M-API Library User Guide MAPI_Calibrate() Purpose Calibrate the part using referenced meter values and tolerance values as specified in the MPU_CParms_t data structure (see the MAPI_CalSetGet API for more information). A typical application shall use this API as follows: 1. Call MAPI_CalSetGet (FALSE, ….) to get current calibration data. 2.
78M6612 M-API Library User Guide Outlets Return Codes 4.4.3 UG_6612_036 Input parameter Bit representations of outlet # to be calibrated. For example: 0x03 represents outlet #1 and 2 to be calibrated. MAPI_OK MAPI_ERROR //Calibration passed. //Calibration failed. Call MAPI_CalStatus() for specifics. MAPI_MeterStatus() Purpose Run this function after a failed calibration or periodically to detect any error/warning. Any non-zero value returned indicates some failure/warning has occurred.
UG_6612_036 Rev. 1.
78M6612 M-API Library User Guide 4.4.4 UG_6612_036 MAPI_TimeToAverage() Purpose Set/Get the time increment (in seconds) in which the power (in Watts) is to be averaged. If a Time Interval has been set previously, it will be reset from this point forward and the accumulator’s value will also be reset. Default value will be 10 seconds if this API is not called or if it is called with TimeInterval = 0. This time is global time that is applicable to both channels.
UG_6612_036 4.4.6 78M6612 M-API Library User Guide MAPI_GetVoltageCurrent() Purpose Get the current values of Voltage and Current . This function can be useful for determining referenced voltage and current values for calibration. Follow the steps below for a sample usage of this API: 1. Call MAPI_CalSetGet() to get default calibration values. 2. Call MAPI_GetVoltageCurrent() to get current Voltage and Current. 3. Set new parameters with call to MAPI_CalSetGet(). 4.
78M6612 M-API Library User Guide UG_6612_036 4.5 Zero Crossing and Relay Control 4.5.1 MAPI_RelayConfig() Purpose Read/Write relay configuration values. channels/outlets.
UG_6612_036 4.5.2 78M6612 M-API Library User Guide MAPI_RelayControl () Purpose Turning Relay ON/OFF (close/open circuit) on all channels. Synopsis void Parameters Channels MAPI_RelayControl( IN unsigned char Channels); Input parameter. Each bit indicates turning ON(1) or OFF(0). The bit’s position represents the specific channel/outlet number. For example: 0x01h – Turn relay ON on channel 1/A. Turn relays OFF on channel 2/B. 0x02h – Turn relay ON on channel 2/B. Turn relays OFF on channel 1/A.
78M6612 M-API Library User Guide UG_6612_036 4.6 Soft-Timers There are eight soft-timers in the 8051 Timer 0. Only six of these timers are available to application level as two are used internally by the library. The timer is a fixed 10-milisecond time increment. When TSC_Init() is called, the timer will be started and setup. It also calls MAPIstm_init() so the application layer does NOT need to call MAPIstm_init(). 4.6.1 4.6.2 MAPIstm_init() Purpose Initialize soft-timers variables and structures.
UG_6612_036 78M6612 M-API Library User Guide 4.7 DIO Configuration (future release) 4.7.1 MAPI_DIOConfig() Purpose Configure the DIOs to be a specific function. Note: DIO 1 – 8 are part of 80515 USER0 SFR (0x80). DIO8-15 are part of 80515 USER1 SFR (0x90). And DIO16-21 are part of 80515 USER2 SFR (0xA0). These are all bit-addressable SFR. An application shall call this API either right before or right after calling MAPI_Init() to setup all the signals properly.
78M6612 M-API Library User Guide 4.7.2 UG_6612_036 MAPI_DIORW() Purpose Perform the Read/Write operation of/to the DIO. Synopsis void MAPI_DIORW ( enum SIGNAL_TYPE Signal, unsigned char *Value, uint8_t OP ); Where: enum SIGNAL_TYPE {ACTIVEB, ALARM, FAULTB, READYB, RELAY1B, RELAY2B, SAG, WATTPULSE, AC_OK, PFC_CTRL, PFC_OK, PFC_ON, Q183_ON, UNUSED1, UNUSED2, UNUSED3}; Also where OP = (READ/ 0, WRITE = 1 Parameters OP: Input parameter. 0 = read, 1 = write.
UG_6612_036 78M6612 M-API Library User Guide 4.8 Flash Management 4.8.1 Memcpy_rx() Purpose Write to Flash the content data from a specific RAM location. If the length of the source and the starting ROM location cause the write operation to span more than one 512-byte Flash page, the Read/Erase/Verify/Write will take place on all the pages involved. An erase operation will result in the Flash contents being set to 0xFF. CE will be disabled during execution of this API.
78M6612 M-API Library User Guide 4.8.2 UG_6612_036 Memcpy_xr() Purpose Use to write to Flash the content data to a specific RAM location. An example use of this API is as follows: memcpy_xr (RAMData, ROMData, ROMSIZE); Synopsis Void memcpy_xr ( Unsigned char xdata *dst, Unsigned char code *src, Unsigned integer len ); Parameters dst src len Return Codes 4.8.3 TRUE if the Write was successful. FALSE if the Write was not completed.
UG_6612_036 78M6612 M-API Library User Guide 4.9 Serial/RS232 Interface 4.9.1 MAPI_UARTInit() Purpose Configure the communication speed, flow control, character parity and number of stop bits. The serial interrupt service routine is NOT maskable, the interrupt vector is set internally. Xon/Xoff will always be enabled. Non-parity, 8 data bit, 1 stop bit is the only supported configuration. The only thing the application can change is the baud rate.
78M6612 M-API Library User Guide 4.9.3 4.9.4 MAPI_TxLen() Purpose Number of bytes transmitted thus far. Synopsis Unsigned integer MAPI_ TxLen ( void ) Parameters None. Return Value Unsigned integer specifying the number of bytes left in the Tx buffer, i.e. the remaining bytes to be sent. MAPI_UARTRx() Purpose Setup the receive buffer and start receiving. Always call this function after MAPI_UARTInit() to make sure the receive buffer is available.
UG_6612_036 78M6612 M-API Library User Guide 5 Default Values The following default values are used to build the MAPI library: struct MPU_CParms_t MPU_CParams = { Unsigned Char Channels = 0 float C_Wcal = 120W float C_Vcal = 120V float C_Ical = 1A Unsigned Integer t C_Pcal = 0 float float float float C_Wtolerance C_Vtolerance C_Itolerance C_Ptolerance = = = = 10mA 10mV 10mA 0.
78M6612 M-API Library User Guide 6 UG_6612_036 Contact Information For more information about Maxim products or to check the availability of the 78M6612, contact technical support at www.maxim-ic.com/support. 42 Rev. 1.
UG_6612_036 78M6612 M-API Library User Guide Revision History Revision 1.00 Rev. 1.00 Date 09/30/2010 Description First publication.
