78M6618 M-API Library User Guide
Contents
1. amp amp A toupper bptr 1 toupper bptr 0 amp amp L toupper bptr 1 toupper bptr 1 amp amp C toupper bptr 2 toupper bptr 1 amp amp C toupper bptr 2 toupper bptr 1 amp amp M toupper bptr 2 30 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide 4 3 2 Memopy xr Purpose Use to write to Flash the content data to a specific RAM location Note it is the task of the application to setup the specific Flash bank before calling this API An example use of this API is as follows FL BANK BANK CE memcpy xr RAMData ROMData ROMSIZE FL BANK saved bank Where FL_BANK iS SFR 0xB6 and BANK CE is defined to be Bank 3 Synopsis Void memcpy_xr Unsigned char xdata dst Unsigned char code src Unsigned integer len Parameters dst Input parameter Specifies starting RAM address to be written destination src Input parameter Use contents at this ROM Flash address location as the source data len Input parameter Length in bytes of data to write to RAM Return Codes TRUE if the Write was successful FALSE if the Write was not completed 4 3 3 Memcpy_xx Purpose Use to copy data from an xdata location to another xdata location Synopsis Void memcpy xx Unsigned char xdata dst Unsigned char xdata src Unsigned integer len Parameters dst Input paramet2. 09 109 11 111 19 119 21 121 Energy mWh ENERGY Fits 0A 10A 12 112 1A 11A 22 122 Cost mUnits FLOAT Accumulated Cost OB 10B 13 113 1B 11B 23 123 Current mArms IRMS T RMS Current Reactive Power oc gem 14 114 ic MEN 24 124 jug mW POWER per accum ower interval Apparent Apparent Power OD 10D 15 115 1D 11D 25 125 B mW POWER per accum ower H interval Power factor Power _ output will be OE 10E 16 116 1E 11E 26 126 Bana FLOAT a too and 1 00 Phase angle Phase output will be OF 10F 17 117 1F 11F 27 127 Anais DEEOAT beween 80000 and 180 000 MPU ADDRESS Outlet 5 Outlet 6 Outlet 7 Outlet 8 Outlet Tota NAME WB NB WB NB WB NB WB NB ETIA 28 128 30 130 38 138 40 140 49 148 pele Power 29 129 31 131 39 139 41 141 49 149 Energy 2A 12A 32 132 3A 13A 42 142 4A 14a Cost 2B 12B 33 133 3B 13B 43 143 4B 14B Current 2c 142C 34 134 3c 130 44 144 ac e PEACE Power 2D 12D 35 135 3D 13D 45 145 o fian Apparent Power 2E 12E 36 136 3E 13E 46 146 Power Factor oF ES 37 137 3F BD 47 147 Phase Angle 26 Rev 1 00 UG 6618 029 78M6618 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 des
3. 00 abs H01 6618 CLIMAPIWv2 00 abs H02 and 6618_ CLIMAPIWv2 00 abs H03 and generates a single hex file 6618 CLIMAPIWv2 00 hex with a memory size of 128kbyte Options for Target 6618B1B2B3CW Device Target Output Listing User csi Abl BL51 Locate BL51 Misc Debug Utilities Run User Programs Before Compilation of a C C File Run 1 o NE D0516 Run 2 I posts Run User Programs Before Build Rebuild Run 1 a posi Run 2 C posts Run User Programs After Bra r NCESbank merge exe 128 6618 CLIMAPIWy2_00 abs 6618 CLIMAPIWyv2_ 00 heim Run 2 V Beep When Complete Start Debugging Cancel Defaults 16 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide 4 M APILibraries The libraries are designed and partitioned to be placed at specific banks as follows Library Name 6618C MAPIW LIB Flash Bank Approx Size Purpose Common Wide Band Option 19K Keeps all common frequently called code Includes but not limited to Interrupt service routines timer APIs Relay APIs Serial 0 APIs Flash management access to all metering registers 6618B1 MAPIW LIB Reserved for metering calculations 6618B2 MAPIW LIB More metering calculations 6618B3 MAPIW LIB 6618C_MAPIN LIB 6618B1_MAPIN LIB 6618B2_MAPIN LIB 6618B3_MAPIN LIB Bank 3 Common 9K 4K The first lower address of 9K is used mostly for calibration accessing registers and the actual lib
4. 11 1 0000 0800 Bit 12 2 1 0000 1000 Bit 13 1 0000 2000 Bit 14 2 1 0000 4000 Bit 15 2 1 0000 8000 Bit 16 2 1 0001 0000 Bit 17 2 1 0002 0000 Bit 18 2 1 0004 0000 Bit 19 2 1 0008 0000 Bit 20 1 0010 0000 Bit 21 21 0020 0000 Bit 22 2 1 0040 0000 Bit 23 2 1 0080 0000 Bit 24 1 0100 0000 Bits 25 31 20 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide NB Status Output Parameter A 32 bit word status that indicates status of narrow band measurements as follows Over max NB current on A Bit O 1 0000 0001 Min Power Factor exceeded on A Bit 1 1 0000 0002 Max Power Factor exceeded on A Bit 2 1 0000 0004 Over max NB current on B Bit 3 1 0000 0008 Min Power Factor exceeded on B Bit 4 1 0000 0010 Max Power Factor exceeded on B Bit5 1 0000 0020 Over max NB current on C Bit 6 1 0000 0040 Min Power Factor exceeded on C Bit 7 1 0000 0080 Max Power Factor exceeded on C Bit 8 1 0000 0100 Over max NB current on D Bit9 2 1 0000 0200 Min Power Factor exceeded on D Bit 10 1 0000 0400 Max Power Factor exceeded on D Bit 11 1 0000 0800 Over max NB current on E Bit 12 2 1 0000 1000 Min Power Factor exceeded on E Bit 13 2 1 0000 2000 Max Power Factor exceeded on E Bit 14 2 1 0000 4000 Over max NB current on F Bit 15 2 1 0000 8000 Min Power Factor exceeded on F Bit 16 2 1 0001 0000 Max Power Factor exceeded on F Bit 17 1 0002 0000 Over max N
5. 44 Rev 1 00 3 78M6618 M API Library User Guide UG 6618 029 4 8 Serial RS232 Interfaco aoirean neran eene nennen nnne 45 4 81 CMAPIUART HDI sh tiet eet haven ced vag dee exeo el el e ee Pene ees 45 4 8 2 MAPI UART EX edicere trei m er pre eed Ed eae dae e ra Boe eee 45 483 MAPI TXLEN NU TL EM 46 4 8 4 MAPIUARTRX i ith dte victoire dee tpa vp veel e deca ape vane ovis eld og e eet a 46 4 815 MAPIBixken 1st derat eite ite agde etn ai nee Gee ies 46 4 9 SSPLIntetface terii ete tias voee caa erra oce haee de de eroe eee aote urere da vente eoa ge era d 47 S ESRB s inu 47 4 9 2 MAPI SPICmd Pending issnin isasi aiia ennt nennen snnt nennen nes 47 4 9 3 MAPI SPIGet Ga A i irte a dae aeterne dec pe verae eee an e aha te oce 47 5 Library Defaults 2 2 ciiiiecceiiiceciecccceeniccocenece ccce Aa plur Ci mies ce Issa cr 48 Revision HISLOEy uaira Ie etti adete te nuit E Mass M uM et AA ae 49 4 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide 1 Introduction This document describes the M API v2 01 firmware libraries available from Teridian for use with the 78M6618 AC power monitoring IC These libraries are specifically designed for measurement and switch control of eight 8 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
6. Flash The CE Data Image is programmed into Flash starting at address OXDFFE During power up its content is copied to XRAM to be used as a working copy Though it is NOT recommended to change any CE Data occasionally such needs arise such as changing the IMAX VMAX or WRATE values The application can change the values of these configurable registers using the MAPI GetSetRegister This change only takes effect in the XRAM copy of the data To permanently save the data into Flash the application must exclusively call this function to perform the permanent save into its specific location of Flash This function is not and should not be called too often as Flash Write does have a life expectancy See the 6618 MAPICLIW uproj for sample usage of this API In order for this function to perform properly the CE must be turned off by calling MAPI CEOff Bool MAPI UpdateCE void None TRUE Successful write of MPU data to Flash FALSE Write was not successful perhaps CE is still running 32 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide 4 3 0 MAPI CEOn Purpose Synopsis Parameters Return Codes Turn CE on After calling MAPI Init CE is turned on This API is available to the application to manually control the CE particularly when reading writing to Flash writing to Flash is not allowed when CE is on void MAPI CEOn void None None 4 3 7 MAPI CEOff Purpose Synopsi
7. Flash program address Flash memory is partitioned as follows Table 2 Flash Memory Shared by the CE and MPU Code Address Memory Memory Memory Size hex Technology Type Name Typical Usage bytes 0x0000 Flash Non volatile Program memory MPU Program and 120 KB 0x1DFFF Memory non volatile data 0x1E000 Flash Non volatile Program memory CE program 8 KB max OxiFFFF Memory Since the 78M6618 uses different memory banks access to specific region of Flash requires careful consideration of how the code is spread out The CE code is currently placed at the highest 8K region of Flash Rev 1 00 9 78M6618 M API Library User Guide UG 6618 029 3 2 Build Configuration The accompanying PDU demo application source code has been set up to link to the libraries as described in the following sections 3 2 1 Bank Assignments The 78M6618 IC has 4 banks of Flash at 32K each The banks are divided such as Common Bank 1 Bank 2 and Bank 8 The project is setup to identify these banks as shown here Options for Target 6618B1B2B3CW Device Target Output Listing User c51 A51 BL51 Locate BL51 Misc Debug Utilties Teridian Semiconductor Corp 71M6513 Xtal MHz meg Use On chip ROM 0x0 0xF FFF Memory Model Large variables in DATA Code Rom Size Compact 2K functions 64K progran Use On chip XRAM DxD Ox1AFF Operating system None Off chip Code memory Off chip
8. Serial RS232 Interface 4 8 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 Synopsis Bool MAPI UARTInit IN enum SERIAL SPD speed Parameters speed Input parameter This selects the communication speed Possible values are RATE 300 0 RATE 600 1 _RATE_1200 2 RATE 2400 3 RATE 4800 4 RATE 9600 5 RATE 19200 6 RATE 38400 7 default Return Codes None 4 8 2 MAPI UARTTXx Purpose Setup the Tx buffer before sending data to the PC UART Subsequent call to this API will append the buffer to the existing transmittal buffer An application should call this API immediately after calling MAPI UARTInit Synopsis enum SERIAL RC data MAPI UARTTx U08x xdata buffer U16 len Parameters buffer Input parameter Specifies a pointer to the data buffer containing data to send to the PC UART Len Input parameter Specifies the current number of bytes to be sent Return Codes S EMPTY Successful transmission S PENDING Successful transmission thus far but not yet finished Where return code SERIAL RC is defined as Enum SERIAL RC After calling this API an
9. format of the register content defined as follows 10 Tenth unit factor 100 Hundredth unit factor 1000 Thousandath unit factor Return Codes MAPI_OK successful operation MAPI RESTRICTED specified address is restricted Rev 1 00 23 78M6618 M API Library User Guide UG 6618 029 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 predefined TypeSize and ScaleFactor are also returned 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 TypeSize and ScaleFactor are predefined and non changeable Example e When getting or retrieving Vrms data the returned value is in mVgys 120000 mVngyg e When setting a Vays alarm threshold the value is entered in Vrms 120 000 Vams 4 2 1 2 Output Data Address Locations The following output data is updated once per accumulation interval and available directly via the SPI interface or via API calls With the current M API architecture only one bandwidth data type narrowband or wideband can be used in each library build MPU ADDRESS NAME LSB TYPE DESCRIPTION WB NB 00 100 Delta Temperature 0 1 C FLOAT Temperature difference from 22 C 01 101 Line Frequency 0 01 Hz
10. soft timers updated and current This API shall be called in the application s main loop after MAPIstm fn start is used This is where fn ptr in MAPIstm fn start above is processed void MAPIstm run void None None Rev 1 00 43 78M6618 M API Library User Guide UG 6618 029 4 6 4 MAPIstm wait Purpose Synopsis Parameters Return Codes Delay processing for a fixed time in 10ms increment Typically use when it is necessary to wait for something to stabilize void MAPIstm wait IN unsigned integer DelayTime DelayTime Input parameter Wait hold up CPU processing for DelayTime 10ms None 4 7 Miscellaneous APIs 4 7 4 MAPI GetCEName Purpose Synopsis Parameters Return Codes Get the CE name embedded as part of the CE data The CE name size is 24 bytes and these exact 24 bytes will be returned in the XDATA string pointed to by ptr void MAPI GetCEName unsigned char xdata ptr ptr Output parameter The CE name will be returned at the xdata location pointed to by ptr For version 1 00 CE release the string will look as follows CE6618 PDU S8 A01 V1 0 None 4 7 2 MAPI SoftReset Purpose Synopsis Parameters Reset the MPU this includes stopping the CE and setting all registers to hardware Power On Reset values void MAPI SoftReset Void None Return Codes None 44 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide 4 8
11. 1 and 2 to be calibrated OxFF represents all eight outlets to be calibrated Calibration passed MAPI ERROR Calibration failed Call MAPI CalStatus for specifics Rev 1 00 37 78M6618 M API Library User Guide UG 6618 029 4 4 3 MAPI GetVoltageCurrent Purpose Synopsis Parameters Get the present 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 ate Call MAPI CalSetGet to get default calibration values and present chip temperature Call MAPI GetVoltageCurrent to get the Voltage and Current at the IC inputs Set new target Voltage and Current parameters if needed correlating to the values obtained in step 2 with a call to MAPT_CalSetGet Call MAPI Calibrate to start the calibration As a check call MAPI GetVoltageCurrent to confirm new calibrated values void MAPI GetVoltageCurrent OUT struct VIT t VIT_Params Where VIT t is defined as Struct VIT U Unsigned char Channel float Current_I float Current V Channel Input parameter Channel outlet number 1 through 8 where present Current value will be read Current I Output parameter Present value of Current for the specified outlet Current V Output parameter Present value of Voltage for Voltage A Return Codes None 38 Rev 1 00 UG 6618 029
12. 18 M API Library User Guide 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 MAPTstm_init so the application layer does NOT need to call MAPIstm_init 4 6 1 MAPIstm_init Purpose Synopsis Parameters Return Codes Initialize soft timers variables and structures void MAPIstm init void None None 4 6 2 MAPIstm fn start Purpose Synopsis Parameters Return Codes Start a soft timer with a call back function pointer Upon expiration of the timer execute the function then remove free the timer unsigned integer MAPIstm fn start unsigned integer tenms count void code fn ptr void tenms count Input parameter Number of counts in 10ms units passed to execute the call back function fn ptr fn ptr Input parameter Pointer to the call back function to execute when the tenms count has expired The function should be a reentrant NULL PTR if there is no more soft timer available Or The address of where tenms count value is stored and counted down is returned This is useful when the application needs to stop the timer at any time before it is expired 4 6 3 MAPIstm run Purpose Synopsis Parameters Return Codes Keep the
13. 4 3 7 MAPIZCEORO staan Gara ce ae el ea ee eee 33 44 Calibration wees CE 34 4 43 MAPI CalSetGet necare ien dade cp ayant doe due nets 34 4 4 2 MAPI Calibrate drop etae ee aeta SY ete Y ape dere oce doge v eee renee 36 4 4 8 MAPI GetVoltageCurrent iasa ansaa antaa aaa nnne nennen aaa enne 38 4 44 MAPI GalStatus senten eite eti ne Eee o e t nde aper edd 39 4 5 Zero Crossing and Relay Control Sena adan ian A a dan ea nan nnne nnne 40 4 51 MAPI RelayGontig Tn dn Kan tet eto ne Eee o e xd eet Kanada sakat 40 4 5 2 MAPI RelayGohtrol iicet nin ti ena nce Per toL EE RE d ENSE atan E ERE 41 4 5 3 MAPI CloseGIrcuit OX u c ihe rtt octets e pedet rape ert eno dd 41 4 54 MAPI OpenCircyit OX Osis iicet rit n eti ea nier tton t ce eet t De RE naat 42 4 6 SOM MIME S 43 4 61 MAPIStm init uir scit on nte ei nce pier teo EE RU A eve EE RAPERE 43 4 6 2 MAPIstm In Start coe ir Hc ete e te re iP e tex ener ire ee IEEE 43 4 6 3 MAPIstmi s Fun sete e ree cce eene tente het t e Pero tete re eee ER ee e ORE 43 4 6 4 MAP IstimicWalt scite tee Eee tecto ro ce tent tede ver Ere nete ROO 44 4 7 Miscellanous APIS neni aec edicere tct ee AGAK 44 4 7 1 MAPI GetCENamey ssssssssssseseeseeeene entrent nennen nns sth A NA senten enne 44 4 7 2 MAP SoftBeset uiid dere SA edit uid aep a eau eese dl ee ana aie d pn EE ai
14. 78M6618 M API Library User Guide 4 4 4 MAPI CalStatus Purpose Synopsis Parameters Run this function if MAPI_Calibrate returns error code to get the exact status of the failure s void MAPI CalStatus unsigned long CAL Status Cal Status Output parameter A 32 bit word status that indicates statuses as follows Voltage A Cal failed Voltage B Cal failed Phase A Cal failed Current A outlet 1 Cal failed Watt A outlet 1 Cal failed Phase B Cal failed Current B outlet 2 failed Watt B outlet 2 failed Phase C Cal failed Current C outlet 3 failed Watt C outlet 3 failed Phase D Cal failed Current D outlet 4 failed Watt D outlet 4 failed Phase E Cal failed Current E outlet 5 failed Watt E outlet 5 failed Phase F Cal failed Current F outlet 6 failed Watt F outlet 6 failed Phase G Cal failed Current G outlet 7 failed Watt G outlet 7 failed Phase H Cal failed Current H outlet 8 failed Watt H outlet 8 failed Return Codes None Bit 1 1 Bit 2 1 N A at present time Bit 3 1 Bit 4 1 Bit 5 1 Bit 6 1 Bit 7 1 Bit 8 1 Bit 9 1 Bit 10 1 Bit 11 2 1 Bit 12 1 Bit 13 1 Bit 14 1 Bit 15 1 Bit 16 1 Bit 17 2 1 Bit 18 1 Bit 19 1 Bit 20 1 Bit 21 1 Bit 22 1 Bit 23 1 Bit 24 1 Bit 25 1 Bit 26 1 Rev 1 00 39 78M6618 M API Library User Guide UG 6618 029 4 5 Zero Crossing and Relay Control 4 5 1 MAPI RelayConfig Purpo
15. 8M6618 M API Library User Guide UG 6618 029 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 Frequency data as well as RMS Current Active Power and Reactive Power for each outlet The M API 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 Vnus NYw t 2 Current Ins S Vnus Active Power P i t v t Reactive Power Q i t v t shift 90 Apparent Power S _ V P Qf 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 Vams NYw t 2 Current les Nyi t 2 Active Power P gt i t v t Reactive Power Q wWs P Apparent Po
16. B current on G Bit 18 2 1 0004 0000 Min Power Factor exceeded on G Bit 19 1 0008 0000 Max Power Factor exceeded on G Bit 20 1 0010 0000 Over max NB current on H Bit 21 2 1 0020 0000 Min Power Factor exceeded on H Bit 22 1 0040 0000 Max Power Factor exceeded on H Bit 23 2 1 0080 0000 Over max NB Current Total Bit 24 1 0100 0000 Return Codes None Rev 1 00 21 78M6618 M API Library User Guide UG 6618 029 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 A callto MAPI UpdateCE and or MAPI_UpdateMPU Will be necessary if it shall be permanently saved into Flash There are three types of registers MPU CE and I O Hardware Control The range of address indicates the type of registers as follows 0x0000 OxO3FF MPU Address Can also be accessed via SPI interface 0x0400 0x07FF CE Address No direct access via SPI interface 0x2000 Ox20FF Hardware I O Control Address No direct access via SPI When calling this function make sure the documented Reg Address is or ed with the specific type of register CE or MPU or I O RAM defined such as enum REG TYPE PU ADDRESS 0x0000 CE ADDRESS 0x0800 RI ADDRESS 0x2000 Synopsis enum
17. Bit 20 1 0010 0000 Creep on IF Bit 21 1 0020 0000 Creep on IG Bit 22 1 0040 0000 Creep on IH Bit 23 1 0080 0000 Rev 1 00 19 78M6618 M API Library User Guide UG 6618 029 WB Status Output Parameter A 32 bit word status that indicates status of wide band measurements as follows Over max current on Outlet 1 Min Power Factor exceeded on Outlet 1 Max Power Factor exceeded on Outlet 1 Over max current on Outlet 2 Min Power Factor exceeded on Outlet 2 Max Power Factor exceeded on Outlet 2 Over max current on Outlet 3 Min Power Factor exceeded on Outlet 3 Max Power Factor exceeded on Outlet 3 Over max current on Outlet 4 Min Power Factor exceeded on Outlet 4 Max Power Factor exceeded on Outlet 4 Over max current on Outlet 5 Min Power Factor exceeded on Outlet 5 Max Power Factor exceeded on Outlet 5 Over max current on Outlet 6 Min Power Factor exceeded on Outlet 6 Max Power Factor exceeded on Outlet 6 Over max current on Outlet 7 Min Power Factor exceeded on Outlet 7 Max Power Factor exceeded on Outlet 7 Over max current on Outlet 8 Min Power Factor exceeded on Outlet 8 Max Power Factor exceeded on Outlet 8 Over Max Current Total Reserved Bit 0 2 1 0000 0001 Bit 1 1 0000 0002 Bit 2 1 0000 0004 Bit 3 2 1 0000 0008 Bit 4 2 1 0000 0010 Bit 5 2 1 0000 0020 Bit 6 2 1 0000 0040 Bit 7 2 1 0000 0080 Bit 8 1 0000 0100 Bit 9 1 0000 0200 Bit 10 1 0000 0400 Bit
18. FREQ Line Frequency Bit 0 MIN Temperature Alarm Bit 1 MAX Temperature Alarm Bit 2 MIN Frequency Alarm Bit 3 MAX Frequency Alarm Bit 4 SAG Voltage Alarm for VA Bit 5 MIN Voltage Alarm for VA Bit 6 MAX Voltage Alarm for VA Bit 7 SAG Voltage Alarm for VB Bit 8 MIN Voltage Alarm for VB Bit 9 MAX Voltage Alarm for VB 02 102 prece Bit 10 Line Neutral Reversal Detected Bits 11 15 Unused Bit 16 Creep Alert for Outlet 1 I Bit 17 Creep Alert for Outlet 2 I Bit 18 Creep Alert for Outlet 3 I Bit 19 Creep Alert for Outlet 4 I Bit 20 Creep Alert for Outlet 5 I Bit 21 Creep Alert for Outlet 6 Bit 22 Creep Alert for Outlet 7 I Bit 23 Creep Alert for Outlet 8 Bits 24 31 Reserved 24 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide MPU ADDRESS WB NB NAME LSB TYPE DESCRIPTION 03 103 Alarm Status outlet specific Bit 0 MAX Current Alarm Outlet Bit 1 MIN Power Factor Alarm Outlet1 Bit 2 MAX Power Factor Alarm Outlet1 Bit 3 MAX Current Alarm Outlet2 Bit 4 MIN Power Factor Alarm Outlet2 Bit 5 MAX Power Factor Alarm Outlet2 Bit 6 MAX Current Alarm Outlet3 Bit 7 MIN Power Factor Alarm Outlet3 Bit 8 MAX Power Factor Alarm Outlet3 Bit 9 MAX Current Alarm Outlet4 Bit 10 MIN Power Factor Alarm Outlet4 Bit 11 MAX Power Fact
19. MAPI RC MAPI GetSetRegister bool Operation struct Reg t Reg Where Reg t is defined as Struct Reg t Unsigned Integer Address Unsigned Long Value Unsigned Char TypeSize Unsigned Integer ScaleFactor 22 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide Parameters Operation Input parameter TRUE 1 Set Operation FALSE 0 Get Operation Struct Reg t When Operation TRUE Output parameter When Operation FALSE Input parameter Address Two byte address location Address where its content will be extracted Operation FALSE or stored Operation TRUE Note Value Four byte value to be stored or retrieved Content from Address to be extracted Operation FALSE or stored Operation TRUE TypeSize Type and Size of register s content This byte is defined as follows Bit 8 Bit 7 4 Bit 3 1 SIGNED Register value TYPE Register value is one of the SIZE Indicates storage size is a signed value following types in bytes of register where 1 negative O positive INTEGER 0x00 CONFIG oxzo char 1 byte FLOAT 0x10 POWER 0x18 imteger TA IRMS_T 0x20 ENERGY 0x28 Word 4 byte VRMS_T 0x30 FREQ 0x38 IRMS_M_ 0x40 COUNT 0x48 VRMS_M 0x50 TIMER 0x58 CONTROL 0x60 Typically used for power Used by API call to determine formulae factor phase adjust for data scaling and conversion ScaleFactor Output parameter This byte indicates presentation
20. Xdata memory Start Size Start Size Eprom ox0000 010000 Ram 0 05A0 Ox0460 Eprom Ram Eprom Ram v Code Banking Start End jE pport Banks 4 Bank Area 08000 OxFFFF j The common library 6618CMAPIW LIB resides in Code Bank Common Options for File 6618C_MAPIW LIB Properties Path C Projects EMC M6618 200 Library HSEEE File Type Library file 4 Include in Target Build Size en 93 Bytes KH last change wed Jun 09 13 06 55 2010 Rz Iz Link Publics Only Code Bank Common Stop on Exit Code t specified C STARTUP BANK SWITCHING DEFAULTS SET_DEFAULTS Select Modules to Always Include IKIKIKIKIK KIKIKIKI Custom Arguments 10 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide The Bank1 library 6618B1_MAPIW LIB resides in Code Bank Bank 1 Options for File 6618B1 MAPIW LIB Properties Path C Projects EMC MB61 8 2004Library EEE SES ea File Type Library file ES IF Include in Target Build Size 23053 Bytes 7 Alway Id last change wed Jun 09 13 06 54 2010 VV Link Publics Only Code Bank Bank 1 Stop on Exit Code Not specified FREQ METER PEAK_ALERTS PHASE_ANGLE POWER PWRFACT RMS_METER YAH VARH Select Modules to Always Include KIKI KI KK Custom Argumen
21. ads to test for pass fail result Default 10 Output parameter SetData FALSE Input parameter SetData TRUE Maximum number of Watts reads to test for pass fail result Default 10 Output parameter Wrate use during calibration 32kh Read only Output parameter SetData FALSE Input parameter SetData TRUE Calibration temperature In 0 1 degree unit Calibration succeeded MAPI ERROR Calibration failed For more detailed descriptions of the failure call MAPT_CALStatus Rev 1 00 35 78M6618 M API Library User Guide UG 6618 029 4 4 2 MAPI Calibrate Purpose Synopsis 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 CallMAPI CalSetGet FALSE to get current calibration data 2 f necessary call MAPI CalSetGet TRUE to set new calibration data tolerance values referenced values average count maximum count etc Call MAPI Calibrate to start the calibration Call MAPI UpdateCE and MAPI UpdateMPU to permanently update the new values in Flash 5 Call MAPI CalSetGet FALSE to make sure the new data is written preserved It is up to the application level to select the CAL TYPE appropriately It is recommended that temperature calibration CTYPE C TEMP shall alw
22. application can make sure all bytes were transmitted by checking that MAPI TxLen returns a 0 Rev 1 00 45 78M6618 M API Library User Guide UG 6618 029 4 8 3 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 4 8 4 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 Subsequent call to this API will append the data to the existing buffer queue if data is being received Synopsis uintl6 t MAPI UARTRx U08x xdata buffer U16 len Parameters buffer Input parameter Specifies a pointer to the data buffer to store the data received from the PC UART len Input parameter Specifies the maximum number of bytes to receive at any one time Return Codes Unsigned integer specifying the number of bytes fetched thus far Use MAPI RxLen to keep track of the remaining number of bytes unfetched in the Rx buffer 4 8 5 MAPI RxLen Purpose Number of bytes received thus far Synopsis Unsigned Integer MAPI RxLen void Parameters None Return Value Unsigned integer specifying the number of bytes in the queued buffer 46 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide 4 9 SPI Interface 78M6618 have ded
23. assignment COMMON main ob BANKS io obj BANKS cli obj BANKS cmd misc obj BANKS menu obj BANKS cmd sfr obj BANK3 cmd MAPI obj BANKS cmd ce obj BANKS3 cmd lOMap obj BANKS c serial obj Library files bank assignment COMMON Library 6618C_MAPIW LIB C_STARTUP BANK SWITCHING DEFAULTS SET_DEFAULTS FLASH LIBRARY CE TRIP TMRO STM TSC 106618 IRQ MATH SFRS SEROCLI BANK1 Library 6618B1_MAPIW LIB FREQ METER PEAK_ALERTS PHASE_ANGLE POWER PWRFACT RMS_METER VAH VARH WH BANK2 Library 6618B2_MAPIW LIB CE6618 COMPENSATION MEASURE RMS BANK3 WMibrary6618B3 MAPIW LIB CE6618A01 1 CE CE6618A01 1 DAT ACCESS MAPI CMD_CALIBRATE IOMAP RTC SPI SLAVE TO 6618 CLIMAPIWv2 00 abs Rev 1 00 13 78M6618 M API Library User Guide UG 6618 029 3 2 2 Flash Code Space Assignment In addition to bank assignments there are three files that are part of the Bank 3 library 6618B3 MAPIW LIB that are assigned to a very specific area of Flash within Bank 3 The Flash Code space assignment is necessary in order to keep the images of the CE code CE data and Energy Measurement Constant isolated These assignments are CE data image is to reside at starting address OxDFFE the CE code image is to reside at starting address OXEFFE and the constants defined in a file called Defaults to reside at starting address 0x7CO00 This information is presented in the M51 fi
24. ays be part of CAL TYPE thus C TEMP shall always be OR ing with c type When this API is called with multiple CAL TYPESs calibration will be done in the following order Temperature Phase Voltage Current Wattage Make sure the referenced values are setup correctly using MAPI CalSetGet otherwise calibration will not pass See Section 4 for default values When the return code is not MAPI OK call MAPT_CalStatus to get detailed descriptions of the calibration error s If an error occurs during this call the part is NOT calibrated It is the task of the application to call this API again if recalibration of the part is necessary MAPI RC MAPI Calibrate IN enum CAL TYPE c type IN Unsigned Char Outlets 36 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide Parameters c type Outlets Return Codes MAPI OK Input parameter The following types are acceptable Enum CAL TYPE C WATT 0x01 Calibrate Wattage C_VOLT 0x02 Calibrate Voltage C_CURRENT 0x04 Calibrate Current C_PHASE 0x08 Calibrate Phase Adjust C_TEMP 0x10 Calibrate Temperature Calibration source The values can be OR ing For example C_WATT C_VOLT indicate calibration to be done on Voltage and Wattage C_TEMP C_VOLT indicate calibration to be done on Voltage and Temperature Input parameter Bit representations of outlet to be calibrated For example 0x03 represents outlet
25. criptions refer to the 6618 PDU S8 URT V1 00 Firmware Description Document MPU zo Category Name Address Description Temperature 240 Min Temperature Alarm Threshold 241 Max Temperature Alarm Threshold Common Alarm Frequency 242 Min Frequency Alarm Threshold Threshold 243 Max Frequency Alarm Threshold Voltage A 244 SAG A Voltage Alarm Threshold 245 Min Voltage A Alarm Threshold 246 Max Voltage A Alarm Threshold Voltage B 247 SAG B Voltage Alarm Threshold 248 Min Voltage B Alarm Threshold 249 Max Voltage B Alarm Threshold WB NB Current Outlet 1 250 269 Max Current Alarm Threshold Outlet Specific Power Factor Outlet 1 251 26A Power Factor Alarm Threshold Alarm Thresholds 252 26B Power Factor Alarm Threshold Current Outlet 2 253 26C Max Current Alarm Threshold Power Factor Outlet 2 254 26D Power Factor Alarm Threshold 255 26E Power Factor Alarm Threshold Current Outlet 3 256 26F Max Current Alarm Threshold Power Factor Outlet 3 257 270 Power Factor Alarm Threshold 258 271 Power Factor Alarm Threshold Current Outlet 4 259 272 Max Current Alarm Threshold Power Factor Outlet 4 25A 273 Power Factor Alarm Threshold 25B 274 Power Factor Alarm Threshold Current Outlet 5 25C 275 Max Current Alarm Threshold Power Factor Outlet 5 25D 276 Power Factor Alarm Threshold 25E 277 Power Factor A
26. d Char Channels 0 float C Wcal 120W float C_Vcal 120V float C_Ical 1A Unsigned Integer t C_Pcal 0 float C_Wtolerance 10mA float C Vtolerance 10mV float C Itolerance 10mA float C Ptolerance 0 1 degree Unsigned Char C Vavg cnt 3 Unsigned Char Iavg cnt 3 Unsigned Char C Wavg cnt 3 Unsigned Integer C Vmax cnt 10 Unsigned Integer C Imax cnt 10 Unsigned Integer C Wmax cnt 10 Unsigned Integer C Wrate cal 2840 shall not change Unsigned Integer C Tempcal read only define DefaultTIQ 10 Default Time Increment Query struct VIT t xdata mapi tVIT 0x01 Channel 1 0 00 Current I 0 00 Current V struct Relay_Config_t xdata RlyConfig 0x00 unsigned char Relay CTL 0x64 unsigned int SeqDlyTime 0x01 unsigned int DeEnergizedTime 0x01 unsigned int EnergizedTime 0x00 InvertPNonLatch 48 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide Revision History Revision Date Description 1 00 9 15 2010 First publication Rev 1 00 49
27. d the return code is reflected from this comparison Note1 When calling this API CE must be turned off See MAPI_CEOff and MAPI CEOn APIs in the sections above Note2 it is the task of the application to setup the specific Flash bank before calling this API An example use of this API is as follows FL BANK BANK CE ok memcpy rx int8r t ROMData int8x t RAMData ROMSIZE FL BANK saved bank Where FL BANK is SFR 0xB6 and BANK_CE is defined to be Bank 3 Bool memcpy rx Unsigned char code dst Unsigned char xdata src Unsigned integer len dst Input parameter Specifies starting ROM address of Flash to be written destination src Input parameter Use contents at this RAM address location as the source data len Input parameter Length in bytes of data to write to Flash TRUE if the Write was successful FALSE if the Write was not completed Note To avoid accidental write to Flash this function requires a flash write confirmation from the application layer This confirmation is done such as follows there shall be a function called get_buff at application level which returns a pointer of Xdata whose content is checked as the following uint8x_t bptr xdata bptr get buff toupper bptr 0 amp amp U toupper bptr 1 toupper bptr 0 amp amp U toupper bptr 1 toupper bptr 0
28. e nicely organized and contiguous object code hex file when it comes to bank assignments instead it produces an individual hex file for each bank So when downloading the code to Flash after successfully compiling and linking with Keil the user will need to manually select and program each corresponding hex file into its bank For example the attached CLI application code after compiling and linking using the Keil compiler will result in three separate hex files 6618 CLIMAPIWv2 00 abs H01 6618 CLIMAPIWv2 00 abs H02 and 6618 CLIMAPIWv2 00 abs H03 Teridian has simplified the Flash programming process by providing the user with a Bank Merge exe application a Dos base program which resides in the library folder of the attached zipped file The Bank Merge exe will take in all the three hex files as described above and merge them into one single contiguous hex file that can be downloaded using the Signum ICE debugger or the Teridian s TFP2 flash programmer s tool At the DOS prompt type in bank merge will display its usage as follows Usage bank merge ROM Size Input Name lt Output gt ROM Size The memory size of ROM in kbyte 64 128 192 256 Input Compiled bank hex files name without extension Output Output file name MUST have hex extension Example as shown below bank merge exe 128 6618 CLIMAPIWv2 00 abs 6618 CLIMAPIV2 00 hex This example merges the three 3 Keil compiled hex files 6618 CLIMAPIWv2
29. els Return Codes None 4 5 3 MAPI CloseCircuit OX Purpose Get zero crossing status when positioning from open circuit to close circuit The value returned TRUE FALSE indicates whether Voltage zero crossing has occurred The usage of this API is intended to be for when the circuit is transitioning from open to close This API uses the hardware Timer 1 in the case when zero crossing does not take place A delay of 20ms is set for such break Synopsis bool MAPI CloseCircuit OX void Parameters None Return Codes TRUE Zero crossing occurs FALSE Zero crossing does not occur Rev 1 00 41 78M6618 M API Library User Guide UG 6618 029 4 5 4 MAPI OpenCircuit 0X Purpose Synopsis Parameters Return Codes Get zero crossing status when transitioning from close circuit to open circuit The value returned TRUE FALSE indicates whether current zero crossing has occurred for a specific channel There is no indication of either direction The usage of this API is intended to be for when the circuit is transitioning from close to open This API uses the hardware Timer 1 in the case when zero crossing does not take place A delay of 12ms is set for such break bool MAPI OpenCircuit O0X unsigned char Channel Channel Input parameter Channel outlet number 1 through 8 where zero crossing will be detected TRUE Zero crossing occurs FALSE Zero crossing does not occur 42 Rev 1 00 UG 6618 029 78M66
30. er Specifies starting RAM address to be written destination src Input parameter Use contents at this RAM address location as the source data len Input parameter Length in bytes of data to write to RAM Return Codes None Rev 1 00 31 78M6618 M API Library User Guide UG 6618 029 4 3 4 MAPI UpdateMPU Purpose Synopsis Parameters Return Codes Update the MPU contents permanently into Flash The MPU measurement input and calibration default values are stored in Flash During power up this content is copied to XRAM to be used as a working copy The application can change some of the values using the MAPI GetSetRegister This change only takes effect in the XRAM copy of the data To permanently save the data into Flash the application must exclusively call this function to perform the permanent save This function is not to and should not be called too often as Flash Write does have a life expectancy It is typically used after the part is calibrated successfully to save the coefficient values See the 6618 MAPICLIW uproj for sample usage of this API In order for this function to perform properly the CE must be turned off by calling MAPI CEOff Bool MAPI UpdateMPU void none TRUE Successful write of MPU data to Flash FALSE Write was not successful perhaps CE is still running 4 3 5 MAPI UpdateCE Purpose Synopsis Parameters Return Codes Update the CE Data contents permanently into
31. f 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 Hardware Design Guidelines application note IMAX Calculation IMAX Imax pk sqrt 2 Imax rms Max ADC input 250 mV IMax pk R shunt Example With a 6 MQ current shunt IMax pk 41 7A gt IMAX 29 5 Amps VMAX Calculation VMAX Vmax pk sqrt 2 Vmax rms Max ADC input 250mV Vmax pk Shunt R Series R Shunt R Example With a Series R of 2 MO and a Shunt R of 750 VMax pk 666 42 Volts gt VMAX 471 23 Volts 1 4 Reference Documentation e 78M6618 Data Sheet v1 3 or later e 78M6618 Programmer s Reference Manual e 78M6618 PDU Evaluation Board User Manual reference schematics e 6618 PDU S8 URT V1 00 Firmware Description Document register descriptions Rev 1 00 7 78M6618 M API Library User Guide UG 6618 029 2 Firmware Partitions The 78M6618 firmware provided by Teridian is partitioned into three main components The CE firmware although a separate set of source code is the component of the M API libraries responsible for precision Voltage Current Watts and Narrowband VARs measurements handled by the dedicated Compute Engine 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
32. gre DIAN 5 SEMICONDUCTOR CORP A Maxim Integrated Products Brand 78M6618 M API Library User Guide September 15 2010 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide UG 6618 029 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 6618 029 78M6618 M API Library User Guide Table of Contents 1 IntrodUctloh 1 erede ete ue Ir bees 5 Tar Terminology x eite iter tete et intend t ia et e ene oes o edo td uen 5 1 2 Library Measurement Equations SS sni ni A AAA ennemis 6 ta Eibrary Parameters ot rette he bandas hein ete Een indus tee Ai 6 1 9 1 Global Syimibols 3 2 need toe te eee pti eite tut eee ioc eiae 6 1 3 2 Formulae for Scaled Parameters cccccccsssceceeeeceeeeeeeeeeeeeeeceaeeeeaaesseneeseeeetaeseeneeeeeneess 7 1 3 3 Example Calculation of Sensor Parameters eek aasaaan 7 1 4 Reference Documentation iie dee cene Pi a eit n eaten ede Pelei a elu oce 7 2 iFimrmware Parttlons ino ncnoDugnul uL uus 8 3 Build Environment and Software Firmware Configuration ce
33. ibrary The M API library is built with careful consideration of Flash Management and Bank Switching mechanism the Keil s standard STARTUP A51 was modified to support the specific Bank Switching thus itis included in the MAPI library Bank assignment is defined during linking time therefore it is not possible to have a single library spreading out into different banks Thus the MAPI library was built as 4 separate smaller libraries for the purpose of bank assignments It is the responsibility of the Application Programmer to make sure the libraries are to be placed at their specific banks for MAPI to work properly Application code maybe placed anywhere within the 4 banks except at the last 8K of Bank 3 as it is designated for CE usage see Table 2 3 1 Program and RAM Memory The 78M6618 IC has a total of 4K data RAM and 128K bytes of program Flash memory The 4K bytes of data RAM is shared between the CE and the MPU It is partitioned and reserved for each controller as follows Table 1 Data RAM Shared by CE and MPU Address Usage 0x0000 0x059F Reserved for CE Data RAM 1 4K 0x05A0 OxOFFF Reserved for use by MPU 2 6K Because the 80515 can only address up to 64 KB of program memory space from 0x0000 to OxFFFF the 78M6618 was designed such that access to program memory above Ox7FFF is controlled by the FL BANKT I 0 bits in register SFR OxB6 These two bits hold the value of the most significant bits of
34. icated segment pins SEG3 PCLK SEG4 PSDO SEG5 PCSZ and SEG6 PSDI for SPI interface When SPI interface is used for communication these pins should not be used for other purpose 4 9 1 MAPI SPllnit Purpose Synopsis Parameters Return Codes Initializes the SPI interface enables the hardware port and interrupt and initializes the required SPI registers void MAPI SPI init void None None 4 9 2 MAPI SPlCmd Pending Purpose Synopsis Parameters Return Codes Indicates whether the MPU has received a new SPI command bool MAPI SPICmd PendingY None TRUE A SPI command is waiting to be processed FLASE There is no pending SPI command 4 9 3 MAPI_SPIGet_Cmd Purpose Synopsis Parameters Return Codes This MAPI returns the command code and data for the currently pending SPI command void MAPI SPI get cmd struct spi cmd param cmd param Where spi cmd param is defined as struct spi cmd param uint8_t cmd_s uint32_t data_s spi_cmd_param Output parameter cmd s Contains the value of the pending SPI command e g 0x81 relay control OX89 CE off etc data s Contains the data of the pending SPI commands if applicable None Rev 1 00 47 78M6618 M API Library User Guide UG 6618 029 5 Library Defaults The following default values are used to build the M API library struct MPU CParms t MPU_CParams Unsigne
35. larm 4 Threshold Current Outlet 6 25F 278 Max Current Alarm Threshold Power Factor Outlet 6 260 279 Power Factor Alarm Threshold 261 27A Power Factor Alarm 4 Threshold Current Outlet 7 262 27B Max Current Alarm Threshold Power Factor Outlet 7 263 27C Power Factor Alarm Threshold 264 27D Power Factor Alarm 4 Threshold Current Outlet 8 265 27E Max Current Alarm Threshold Power Factor Outlet 8 266 27F Power Factor Alarm Threshold 267 280 Power Factor Alarm 4 Threshold Total Current 268 281 Max Current Alarm Threshold Rev 1 00 27 78M6618 M API Library User Guide UG 6618 029 Category Name MPU Address Description Common Alarm Mask for 282 Alarm Mask for Common Status Status Registers Alarm Masks Common Alarm Mask for Alarm 283 Alarm Mask for Common Alarm DIO4 DIO4 WB Alarm Mask for Status 284 Alarm Mask for WB Status Registers WB Alarm Mask for Alarm DIO4 285 Alarm Mask for WB Alarm DIO4 NB Alarm Mask for Status 286 Alarm Mask for NB Status Registers NB Alarm Mask for Alarm DIO4 287 Alarm Mask for NB Alarm DIO4 Sensor Scaling Voltage V A 200 VMAX A Voltage V B 201 VMAX B Current Outlet 1 202 IMAX Outlet 1 IA Current Outlet 2 203 IMAX Outlet 2 IB Current Outlet 3 204 IMAX Outlet 3 IC Current Outlet 4 205 IMAX Outlet 4 ID Current Outlet 5 206 IMAX Outlet 5 IE Current Outlet 6 207 IMAX Outlet 6 IF C
36. le as follows BANKAREA 0X8000 OXFFFF RAMSIZE 256 DISABLEWARNING 6 BANK3 CO CE6618A01 1 DAT 0XDFFE CO CE6618A01 1 CE OXEFFE CODE 0X0000 0XFFFF CO DEFAULTS 0X7C00 XDATA 0X05A0 0XOFFF PDATA 0X0200 And the setup for these files is shown below for defaults Options for Target 6618B1B2B3CW Device Target Output Listing User C51 451 BL51 Locate BL51 Misc Debug Utilities IM Use Memory Layout from Target Dialog Code Range Space Base Segments data Range SS Code CO DEFAULTS Ox7c00 er data Pdata 00200 Precede Bit Data Idata Stack Linker TO 6518 CLIMAPIw v2 00 abs BankArea 0x8000 0 F FFF control RAMSIZE 255 string Cancel Defaults 14 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide And for CE code and data images Options for Target 6618B1B2B3CW Device Target Output Listing User c51 A51 BL51 Locate BL51 Misc Debug Utilities Warnings Disable Warning Numbers e use linker control file Browse Overlay BANK3 CO CE6618401_1_DAT OxDFFE 7CO CE6618401_1_CE OxEFFE Linker TO 6618 CLIMAPIw v2 00 abs BankArea 0x8000 0xFFFF control RAMSIZE 256 v string Cancel Defaults Rev 1 00 15 78M6618 M API Library User Guide UG 6618 029 3 2 3 Flash Code and Bank Switch Putting It All Together The Keil compiler does not produce a singl
37. measurement output data such as Power Voltage Current accumulated Energy and Line Frequency All measurement calculations are computed by the M API library every accumulation interval and mapped to a dedicated block of registers reserved by the library Measurement data can be either directly accessed via the hardware slave SPI interface or made available to the user application via API calls Access to library data via the SPI interface is limited to raw unscaled measurement values A demo application making use of the M API library set and serial UART interface is included with the delivery 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 4 Terminology The following terminology is used throughout this document e CREEP Threshold value where measurement outputs are squelched to zero e IMAX External RMS current corresponding to 250 mVpk at the current input of the 78M6618 It should be set IMAX Vpk V2 Rsense e VARs Reactive Power Q e VA Apparent Power S e VMAX External RMS voltage corresponding to 250 mVpk at the voltage input of the 78M6618 VA VB It must be set high enough to account for over voltages e NB Narrowband values e WB Wideband values Rev 1 00 5 7
38. on target Watts float C Vcal Voltage calibration target Vrms float C_Ical Current calibration target Arms intl6 t C Pcal Phase calibration target Degrees float C Wtolerance Watts Tolerance Watts float C Vtolerance Voltage Tolerance Vrms float C Itolerance Current Tolerance Arms float C Ptolerance Phase Tolerance degrees uint8 t C Vavg cnt Voltage Average count uint8 t C Iavg cnt Current Average count uint8 t C Wavg cnt Watts Average count uintl6 t C Vmax cnt Voltage Max count uintl6 t C Imax cnt Current Max count uintl6 t C Wmax cnt Watts Max count uintl6 t C Wrate cal Wrate during calibration 32Kh Read Only uintl6 t C Tempcal Calibration temperature 0 1 degree 34 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide Parameters SetData MAPI CParams C Tcal C Wcal C Vcal C Ical C Pcal C Wtolerance C Vtolerance C Itolerance C Ptolerance C Vavg cnt C Iavg cnt C Wavg cnt C Vmax cnt C Imax cnt C Wmax cnt C Wrate cal C Tempcal Return Codes MAPI OK 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 Input parameter read only Calibration type None 0x00 Output parameter SetData FALSE Input parameter SetData TRUE Referenced Wattage calibration
39. ong with specific selectable CE Clock rates At present time this API library is using a default configuration with FIR LEN at its highest fastest rate FIR 0 138 CK32 CE cycles The default value is PRE SAMPS 50 and SUM CYCLES 60 with MUX DIV 10 This constitutes an accumulation interval of approximately 1 second In future releases this API may be used to select a different accumulation interval based on a chosen time interval such as 250ms 500ms or 1 second Bool MAPI SelectMeter enum eAccInterval TimeInterval Enum eAccInterval _250ms 500ms 1sec 2sec TimeInterval Input parameter TRUE 1 Successful operation FALSE 0 Failed operation Default values are used which is 1 second accumulation interval 4 1 3 MAPI MeterRun Purpose Synopsis Parameters Return Codes Run this function in foreground mode to reset the watchdog update all measurement outputs and compare data to Min Max thresholds Once MAPI Init is called the CE will update all atomic measurements every accumulation interval It is the task of the application to put this API into its main loop so that it can post process the data just imported from the CE If this API is called more than once within the same accumulation interval no changes will be updated and a FALSE will be returned Typically the application layer will then call MAPI_MeterStatus to check for any alarm conditions and call MAPI GetSetRegister to get
40. or Alarm Outlet4 Bit 12 MAX Current Alarm Outlet5 Bit 13 MIN Power Factor Alarm Outlet5 Bit 14 MAX Power Factor Alarm Outlet5 Bit 15 MAX Current Alarm Outlet6 Bit 16 MIN Power Factor Alarm Outlet6 Bit 17 MAX Power Factor Alarm Outlet6 Bit 18 MAX Current Alarm Outlet7 Bit 19 MIN Power Factor Alarm Outlet7 Bit 20 MAX Power Factor Alarm Outlet7 Bit 21 MAX Current Alarm Outlet8 Bit 22 MIN Power Factor Alarm Outlet8 Bit 23 MAX Power Factor Alarm Outlet8 Bit 24 MAX Total Current Bits 25 31 Reserved 04 104 Over Current Event Count INTEGER Number of accumulation intervals where value exceeded alarm threshold 05 105 Under Voltage Event Count INTEGER Number of accumulation intervals where value exceeded alarm threshold 06 106 Over Voltage Event Count INTEGER Number of accumulation intervals where value exceeded alarm threshold 07 107 Volts mVrms VRMS T AC Line Voltage RMS Rev 1 00 25 78M6618 M API Library User Guide UG 6618 029 MPU ADDRESS Outlet 1 Outlet 2 Outlet 3 Outlet 4 NAME LSB TYPE DESCRIPTION WB NB WB NB WB NB WB NB Active Active Power per 08 108 10 110 18 118 20 120 B mW POWER a ino Accumulated
41. rary API calls The bottom higher address of 4K is used up by CE The current CLI and M commands code is also residing here which takes up another 9K Narrow Band Option Keeps all common frequently called code Includes but not limited to Interrupt service routines timer APIs Relay APIs Serial O APIs Flash management access to all metering registers Reserved for metering calculations More metering calculations Bank 3 9K 4K The first lower address of 9K is used mostly for calibration accessing registers and the actual library API calls The bottom higher address of 4K is used up by CE The current CLI and M commands code is also residing here which takes up another 9K Narrow Band libraries are not fully tested and will be released in the near future Rev 1 00 17 78M6618 M API Library User Guide UG 6618 029 4 1 Library Initialization and Operation 4 1 1 MAPI Init Purpose Synopsis Parameters Return Codes 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 Void MAPI Init void None None 4 1 2 MAPI SelectMeter future feature Purpose Synopsis Parameters Return Codes The accumulation interval is obtained by setting specific values in the PRE SAMPS SUM CYCLES FIR LEN MUX DIV registers al
42. s Parameters Return Codes Turn CE off When writing to flash the CE must be turned off This API is necessary with MAPI UpdateCE MAPI UpdateMPU Or memcpy rx Calls void MAPI CEOff void None None Rev 1 00 33 78M6618 M API Library User Guide UG 6618 029 4 4 Calibration 4 4 4 MAPI CalSetGet Purpose Set or Get Calibration reference 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 can 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 to get current calibration data 2 If necessary call MAPI CalSetGet TRUE to set new calibration data tolerance values referenced values etc 3 Call MAPI Calibrate to start the calibration If calibration passes continue to step 4 If calibration fails repeat step 1 4 Call MAPI UpdateCE and MAPI UpdateMPU to permanently update the new values in Flash 5 Call MAPI CalSetGet FALSE to make sure the new data is written preserved and correct Synopsis MAPI RC MAPI_CalSetGet IN unsigned char SetData Struct MPU CParms t MAPI CParams Struct MPU CParms t uint8 t C Tcal Type calibration Read Only float C Wcal Wattage calibrati
43. se Synopsis Parameters Read Write relay configuration values Relay configuration is applicable to all channels outlets void MAPI RelayControl IN Bool Operation OUT IN struct Relay Config t Relay Config Where Relay Config t is defined as struct Relay Config t Unsigned Char Relay_CTL Unsigned Integer SeqDlyTime Unsigned Integer DeEnergizedTime Unsigned Integer EnergizedTime Unsigned Char InvertPNonLatch Operation Input parameter TRUE 1 set operation FALSE 0 get operation Relay Config will all be output parameter When Operation TRUE Relay CTL Output parameter This parameter is output only It is set via MAPI RelayControl SeqDlyTime Input parameter Set the new Sequence Delay Time in 10ms units Delay time is time between turning Relays ON close circuit Default value is 10 2100ms DeEngergizedTim Input parameter Time in mseconds 1msecond to delay after open circuit EngergizedTime Input parameter Time in msecond 1msecond to delay after close circuit InvertPolarity Input parameter Bit 1 Polarity 0 non inverted Bit 0 Latch type 0 non latched Notes Sequence Delay Time will be used between turning relays ON Energized Delay Time is used as the delay time to wait immediately after a zero crossing before close circuit DeEnergized Delay Time is used as delay time to wait immediately after a zero crossing before open circuit Re
44. ssere 9 3 1 Program and RAM Memory nn dn oaei ee eiii en ipse E do idus 9 3 2 Build Configuration 2 et A e hacen n aed deut ariaa eder Ro SL e Ee RR RARE Rat Iv D 10 3 2 1 Bank Assignmoents cii eee pee LL Haee ere A MEER deere ne 10 3 2 2 Flash Code Space Assignment sse esee enne 14 3 2 8 Flash Code and Bank Switch Putting It All Together aaa 16 4 MAP Librarles i eee vc cca cca GA pwned ve ctbaw a a A ia 17 4 1 Library Initialization and Operation nennen nnne nnne 18 aaa MAPLIN m iot et tt eit RR ER UE Rs enam ni osea rires 18 4 1 2 MAPI SelectMeter future feature sss 18 4 1 3 MAPIM iuit Ret ide RR a dea SERRE rd se AAA e ai 18 4 1 4 MAPI MeterStatus meme nee ena ee ee ee nee enne atan anakan aman nsn intente 19 4 2 Library Inputs and Outputs ee ee ekeke kekanan ken ekk kakek Kakek anakanak aan aaa 22 4 2 1 MAPI GetSetRegister meneran na ena ena ena ena anakanak anakanak ann aan 22 4 3 Flash Management an me da eaa ence KAA AAA GA A NAN 30 4 3 1 Meme MAUI 30 A32 Memopy xt uera eee eee eere ae ce KA GA 31 4 3 3 Memocpy 20 iuuat eere cte rere ep eer oe ee aeree ee 31 4 3 4 MAPI pdateMPU ierit raptu terr Yap ch eue cec ce net e felis 32 4 3 5 MAPL UpdateCE iere revue etie cepe el lea olt eee rely 32 43 67 iudezenb sale a relearn ale a tee ina ela a OEA 33
45. the CE firmware completes the M MAPI library 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 and the rest of the M API library Refer to the PDU Demo Application document for more information on the application firmware Figure 1 shows a high level partitioning of the firmware architecture The black boxes indicate object code to be provided by Teridian The white box indicates object and source code provided by Teridian UART RS232 or SPI mE Application Serial SPI Host Application Host Controller 78M6618 Figure 1 High Level Host Firmware Interface Architecture Rev 1 00 UG 6618 029 78M6618 M API Library User Guide 3 Build Environment and Software Firmware Configuration The Metrology Application Programming Interface M API is built using Keil Compiler version 8 02 although any Keil version 7 00 or higher is also compatible The M API library is built using specific default configuration as listed in Section 4 Any changes to these default values may require a rebuild of the l
46. ts Cancel Defaults The Bank 2 library 6618B2 MAPIW LIB resides in Code Bank Bank 2 Options for File 6618B2 MAPIW LIB Properties Path C Projects EMC ME61 8 200 Library Si eae en File Type Library file IF Include in Target Build Size 12825 Bytes M Always Build last change Mon Jun 07 09 42 54 2010 RW Generate Assembler SRC File JW Assemble SRC File IF Lirk Publics Only Code Bank Bank 2 Stop on Exit Code Not specified CE6618 COMPENSATION Selec Modules Huc ue co Always Include Custom Arguments Cancel Defaults Rev 1 00 11 78M6618 M API Library User Guide UG 6618 029 The Bank 3 library 6618B3 MAPIW LIB resides in Code Bank Bank 3 Options for File 6618B3_MAPIW LIB Properties Path ZACodeXSPIAMB618 MAP Library GARA File Type Libra fie Iv l Size 61585 Bytes v Alway last change ThuJul2910 07 592010 V Generate Asse A Lu nclude in T arget Build uic emble SRC File ink Publics Only Code Bank Bank 3 Stop on Exit Code CE68618A01 1 CE CE6618A01 1 DAT ACCESS MAPI CMD CALIBRATE IOM P RTC SPI SLAVE Custom Arguments Cancel Defaults In addition to bank assignment to the libraries the application code is also assigned to specific banks as follows with main c resides in the common code bank and the rest of the application source reside in Bank 3 as sho
47. turn Codes None 40 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide 4 5 2 MAPI RelayControl Purpose Turning Relay ON OFF close open circuit on all eight channels Synopsis void MAPI RelayControl IN unsigned char Channels Parameters Channels Input parameter Each bit indicates turning ON 1 or OFF 0 The bit s position represents the specific channel outlet number For example OxO1h Turn relay ON on channel 1 A Turn relays OFF all other channels 0x02h Turn relay ON on channel 2 B Turn relays OFF all other channels 0x04h Turn relay ON on channel 3 C Turn relays OFF all other channels 0x08h Turn relay ON on channel 4 D Turn relays OFF all other channels Ox10h Turn relay ON on channel 5 E Turn relays OFF all other channels Ox20h Turn relay ON on channel 6 F Turn relays OFF all other channels Ox40h Turn relay ON on channel 7 G Turn relays OFF all other channels 0x80h Turn relay ON on channel 8 H Turn relays OFF all other channels Multiple channels can be turned ON with a single call to this API by setting 1 at the bits representing the channels For example Ox81h Turn relay ON on channels 1 amp 8 A amp H Turn relays OFF all others OxFFh Turn relay ON on all channels 0x0Oh Turn relay off of all channels OxOFh Turn relay ON on all 4 lower channels and OFF of all 4 higher channels OxFOh Turn relay ON on all 4 higher channels and OFF of all 4 lower chann
48. updated measurement data Bool MAPI MeterRun void None TRUE 1 New data has been updated FALSE 0 No change from the last update run Rev 1 00 UG 6618 029 78M6618 M API Library User Guide 4 1 4 MAPI MeterStatus Purpose Run this function periodically to detect any error warning Any non zero value returned indicates some failure warning has occurred MPU Output Threshold levels and mask settings for the alarms can be read modified and saved using the MAPI GetSetRegister API call Note Registers 02 03 102 103 also contain meter status for direct access via SPI interface Synopsis void MAPI MeterStatus unsigned long Common Status unsigned long WB Status unsigned long NB Status Parameters Common Status Output parameter A 32 bit word status that indicates statuses as follows Min Temperature exceeded Bit 0 1 0000 0001 Max Temperature exceeded Bit 1 2 1 0000 0002 Min Frequency exceeded Bit 2 1 0000 0004 Max Frequency exceeded Bit 3 2 1 0000 0008 SAG A detected Bit4 1 0000 0010 Under Min VA on A Bit5 1 0000 0020 Over Max Voltage on A Bit 6 1 0000 0040 SAG B detected Bit 7 1 0000 0080 Under Min VB on B Bit 8 1 0000 0100 Over max Voltage on B Bit 9 1 0000 0200 Line Neutral Reversal Bit 10 1 0000 0400 Creep on IA Bit 16 1 0001 0000 Creep on IB Bit 17 1 0002 0000 Creep on IC Bit 18 1 0004 0000 Creep on ID Bit 19 1 0008 0000 Creep on IE
49. urrent Outlet 7 208 IMAX Outlet 7 IG Current Outlet 8 209 IMAX Outlet 8 IH Cost Factor Cost 20E Cost per KWh 20F Cost Unit string Calibration Calibration 21D Calibration Status Configuration 21E Unused Parameters 21F Tolerance on Phase Calibration 220 Calibration Type 221 Calibration Voltage Target 222 Calibration Current Target 223 Calibration Phase Target 224 Tolerance on Voltage Calibration 225 Tolerance on Current Calibration 226 Average Count for Voltage 227 Average Count for Current 228 Max Iterations for Voltage 229 Max Iterations for Current 22A Tolerance on Watts Calibration 22B Average Count for Watts 22C Max Iterations for Watts 22D Calibration WRATE 22E Calibration Temperature 22F Calibration Wattage Target Creep Threshold Voltage VA 230 VA creep Voltage VB 231 VB creep Current Outlet 1 232 Imin IA creep or squelch level Current Outlet 2 233 Imin IB creep or squelch level Current Outlet 3 234 Imin IC creep or squelch level Current Outlet 4 235 Imin ID creep or squelch level Current Outlet 5 236 Imin IE creep or squelch level Current Outlet 6 237 Imin IF creep or squelch level Current Outlet 7 238 Imin IG creep or squelch level Current Outlet 8 239 Imin IH creep or squelch level Frequency 23A VA min for Freq creep 23B 23F Unused 28 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide 4 2 1 4 CE Library Inputs The following inputs can onl
50. value in Watts Default 120W Output parameter SetData FALSE Input parameter SetData TRUE Referenced Voltage calibration value Vrms Default 120V Output parameter SetData FALSE Input parameter SetData TRUE Referenced Current calibration value Arms Default 1A Output parameter SetData FALSE Input parameter SetData TRUE Referenced Phase calibration value in 0 1 C Degrees Default 0 degree Output parameter SetData FALSE Input parameter SetData TRUE Watts Tolerance Watts Default 0 01W or 10mW Output parameter SetData FALSE Input parameter SetData TRUE Voltage Tolerance Vrms Default 10mV Output parameter SetData FALSE Input parameter SetData TRUE Current Tolerance Arms Default 10mA Output parameter SetData FALSE Input parameter SetData TRUE Phase Tolerance degrees Default 0 1 Degree Output parameter SetData FALSE Input parameter SetData TRUE Voltage Average count Default 3 Output parameter SetData FALSE Input parameter SetData TRUE Current Average count Default 3 Output parameter SetData FALSE Input parameter SetData TRUE Watts Average count Default 3 Output parameter SetData FALSE Input parameter SetData TRUE Maximum number of voltage reads to test for pass fail result Default 10 Output parameter SetData FALSE Input parameter SetData TRUE Maximum number of current re
51. wer S Vnus Iams Power Factor PF P S 1 3 Library Parameters This section describes critical constants and variable parameters of the M API library and their recommended usage 1 3 4 Global Symbols The following symbols are fixed constants for the M API v2 01 firmware library Samples 3000 FS 2979 POWERSCALE 9 2454E 07 VRMS MSCALE 6 0813E 05 IRMS MSCALE 1 5203E 05 The following variables are unique to the sensor configuration and represent the real world values mapped to the upper range of the 78M6618 analog front end IMAX 30 Amps for 6 MO Shunt default VMAX 471 5 Volts default 6 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide 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 ims float Val IRMS MSCALE IMAX Vims float Val VRMS _MSCALE VMAX Watts float Val POWERSCALE IMAX VMAX 1000 Frequency integer Val 100 Val library data e g accessable through SPI read When raw measurement data Val is directly accessed via the SPI interface scaling to and from real world or usable values must be done by the host controller using the formulae above 1 3 3 Example Calculation o
52. wn below Select Modules to Always Include JAKK Options for File main c Properties C51 Path C Projects EMC M 6618 200 Application M ain ETA File Type C Source file Y Include in Target Build Size 2461 Bytes Always Build last change Tue Jun 01 16 30 37 2010 Generate Assembler SRC File Assemble SRC File Link Publics Only Code Bank Common Stop on Exit Code Not specified x Select Modules to Always Include Custom Arguments 12 Rev 1 00 UG 6618 029 78M6618 M API Library User Guide The whole CLI group of files is assigned to Bank 3 as shown below Options for Group CLI Properties C51 ABI Stop on Exit Code Not specified M Custom Arguments Path File Type Include in Target Build Size I Always Build last change I Generate Assembler SRC File Assemble SRC File Link Publics Only Code Bank Bank 3 X Select Modules to Always Include Note To find out which file resides in which bank it is best to look at Keil s Mapped file M51 file where is the object code name In the example application the top part of the 6618 CLIMAPIWv2 00 M51 the following is shown bank number is highlighted and reformatting of the text was done for easy reading BL51 BANKED LINKER LOCATER V6 22 INVOKED BY C KEIL C51 BIN BL51 EXE Application files bank
53. y be modified and saved to Flash using API calls no direct SPI access For more information on register descriptions refer to the 6618 PDU S8 URT V1 00 Firmware Description Document CATEGORY CE ADDRESS DESCRIPTION Calibration 10 17 Calibration Gain IA IH Outlet 1 8 18 19 Calibration Gain VA VB Phase Adjust 1A 21 Phase Adjust IA IH CE Configuration 22 CE State Pulse Rate 23 Wrate Quantization Corrections 25 2C Quantization offset Outlet 1 to Outlet 8 35 3C Quantization offset IA IH Outlet 1 8 Temperature Compensation 3D Temperature Gain Adjust SAG Detection 3E SAG Threshold on VA 3F SAG Threshold on VB More Temperature 40 Degree Scale Compensation 41 ppm c 42 ppm c 43 Temperature Calibration Value Rev 1 00 29 78M6618 M API Library User Guide UG 6618 029 4 3 Flash Management 4 3 1 Memocpy rx Purpose Synopsis Parameters Return Codes 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 1024 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 OxFF CE will be disabled during execution of this API After the write this API will validate the write by comparing the Flash content against the RAM content an
Download Pdf Manuals
Related Search