gs2k smartplug application development kit (adk ...€¦ · gs2k smartplug application development...

GS2K SmartPlug Application Development Kit (ADK)

Application Note 80560NT11586A Rev. 2.0 – 2017-10-01

GS2K SmartPlug Application Development Kit (ADK) Application Note

80560NT11586A Rev. 2.0 of 29 2017-10-01

NOTICE

COPYRIGHTS

COMPUTER SOFTWARE COPYRIGHTS

SPECIFICATIONS ARE SUBJECT TO CHANGE WITHOUT NOTICE

While reasonable efforts have been made to assure the accuracy of this document, Telit assumes no liability resulting from any inaccuracies or omissions in this document, or from use of the information obtained herein. The information in this document has been carefully checked and is believed to be reliable. However, no responsibility is assumed for inaccuracies or omissions. Telit reserves the right to make changes to any products described herein and reserves the right to revise this document and to make changes from time to time in content hereof with no obligation to notify any person of revisions or changes. Telit does not assume any liability arising out of the application or use of any product, software, or circuit described herein; neither does it convey license under its patent rights or the rights of others.

It is possible that this publication may contain references to, or information about Telit products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that Telit intends to announce such Telit products, programming, or services in your country.

This instruction manual and the Telit products described in this instruction manual may be, include or describe copyrighted Telit material, such as computer programs stored in semiconductor memories or other media. Laws in the Italy and other countries preserve for Telit and its licensors certain exclusive rights for copyrighted material, including the exclusive right to copy, reproduce in any form, distribute and make derivative works of the copyrighted material. Accordingly, any copyrighted material of Telit and its licensors contained herein or in the Telit products described in this instruction manual may not be copied, reproduced, distributed, merged or modified in any manner without the express written permission of Telit. Furthermore, the purchase of Telit products shall not be deemed to grant either directly or by implication, estoppel, or otherwise, any license under the copyrights, patents or patent applications of Telit, as arises by operation of law in the sale of a product.

The Telit and 3rd Party supplied Software (SW) products described in this instruction manual may include copyrighted Telit and other 3rd Party supplied computer programs stored in semiconductor memories or other media. Laws in the Italy and other countries preserve for Telit and other 3rd Party supplied SW certain exclusive rights for copyrighted computer programs, including the exclusive right to copy or reproduce in any form the copyrighted computer program. Accordingly, any copyrighted Telit or other 3rd Party supplied SW computer programs contained in the Telit products described in this instruction manual may not be copied (reverse engineered) or reproduced in any manner without the express written permission of Telit or the 3rd Party SW supplier. Furthermore, the purchase of Telit products shall not be deemed to grant either directly or by implication, estoppel, or otherwise, any license under the copyrights, patents or patent applications of Telit or other 3rd Party supplied SW, except for the normal non-exclusive, royalty free license to use that arises by operation of law in the sale of a product.


80560NT11586A Rev. 2.0 of 29 2017-10-01

USAGE AND DISCLOSURE RESTRICTIONS

I. License Agreements

II. Copyrighted Materials

III. High Risk Materials

IV. Trademarks

V. Third Party Rights

The software described in this document is the property of Telit and its licensors. It is furnished by express license agreement only and may be used only in accordance with the terms of such an agreement.

Software and documentation are copyrighted materials. Making unauthorized copies is prohibited by law. No part of the software or documentation may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, without prior written permission of Telit

Components, units, or third-party products used in the product described herein are NOT fault-tolerant and are NOT designed, manufactured, or intended for use as on-line control equipment in the following hazardous environments requiring fail-safe controls: the operation of Nuclear Facilities, Aircraft Navigation or Aircraft Communication Systems, Air Traffic Control, Life Support, or Weapons Systems (High Risk Activities"). Telit and its supplier(s) specifically disclaim any expressed or implied warranty of fitness for such High Risk Activities.

TELIT and the Stylized T Logo are registered in Trademark Office. All other product or service names are the property of their respective owners.

The software may include Third Party Right software. In this case, you agree to comply with all terms and conditions imposed on you in respect of such separate software. In addition to Third Party Terms, the disclaimer of warranty and limitation of liability provisions in this License shall apply to the Third Party Right software.

TELIT HEREBY DISCLAIMS ANY AND ALL WARRANTIES EXPRESS OR IMPLIED FROM ANY THIRD PARTIES REGARDING ANY SEPARATE FILES, ANY THIRD PARTY MATERIALS INCLUDED IN THE SOFTWARE, ANY THIRD PARTY MATERIALS FROM WHICH THE SOFTWARE IS DERIVED (COLLECTIVELY “OTHER CODE”), AND THE USE OF ANY OR ALL THE OTHER CODE IN CONNECTION WITH THE SOFTWARE, INCLUDING (WITHOUT LIMITATION) ANY WARRANTIES OF SATISFACTORY QUALITY OR FITNESS FOR A PARTICULAR PURPOSE.

NO THIRD PARTY LICENSORS OF OTHER CODE SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND WHETHER MADE UNDER CONTRACT, TORT OR OTHER LEGAL THEORY, ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE OTHER CODE OR THE EXERCISE OF ANY RIGHTS GRANTED UNDER EITHER OR BOTH THIS LICENSE AND THE LEGAL TERMS APPLICABLE TO ANY SEPARATE FILES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.


80560NT11586A Rev. 2.0 of 29 2017-10-01

APPLICABILITY TABLE

Note: The features described in the present document are provided by the products equipped with the software versions equal or higher than the versions shown in the table. See also the Revision History chapter.

PRODUCT

GS 2100M and GS 2101M modules

SW Version

5.2.1 onwards


80560NT11586A Rev. 2.0 of 29 2017-10-01

Revision History

Version Date Remarks

1.0 October, 2015 First issue

2.0 October, 2017 Updated 6.1 CALIBRATION PROCEDURE


80560NT11586A Rev. 2.0 of 29 2017-10-01

Table of Contents

NOTICE……… ........................................................................................................................... 2

COPYRIGHTS. ........................................................................................................................... 2

COMPUTER SOFTWARE COPYRIGHTS ................................................................................. 2

USAGE AND DISCLOSURE RESTRICTIONS .......................................................................... 3

APPLICABILITY TABLE ........................................................................................................... 4

INTRODUCTION ................................................................................................ 9

1.1 SCOPE .............................................................................................................................. 9 1.2 OVERVIEW ......................................................................................................................... 9 1.3 TERMINOLOGY ............................................................................................................. 10

SPECIFICATIONS ........................................................................................... 11

THEORY OF OPERATION .............................................................................. 12

ARCHITECTURE ............................................................................................. 20

4.1 COMPONENTS .................................................................................................................. 21 4.1.1 Hardware ........................................................................................................ 21 4.1.2 Software ......................................................................................................... 21

EMBEDDED APPLICATION EXECUTION SEQUENCE ................................. 22

5.1 BOOT UP AND INITIALIZATION ............................................................................................ 22 5.2 QUERY ELECTRICAL PARAMETERS .................................................................................... 23 5.3 LOAD CONTROL ............................................................................................................... 23 5.4 RESET ENERGY ............................................................................................................... 23

CALIBRATION ................................................................................................. 24

6.1 CALIBRATION PROCEDURE ............................................................................................... 24 APPENDIX - URIS ................................................................................................................... 27


80560NT11586A Rev. 2.0 of 29 2017-10-01

List of Figures Figure 1: Voltage, Current and Power in Phasor Representation .................................................. 14

Figure 2: Effect of Hann Window with an Ideal sin wave ............................................................... 16

Figure 3: Effect of Hann Window with Voltage Captured on a light Bulb ....................................... 16

Figure 4: Smartplug Application Design ........................................................................................ 20

Figure 5: Calibration Setup ............................................................................................................ 24


80560NT11586A Rev. 2.0 of 29 2017-10-01

List of Tables Table 1: Glossary of Terms ........................................................................................................... 10

Table 2: Hardware Component ..................................................................................................... 21

Table 3: Software Component ....................................................................................................... 21

Table 4: Web interface specification .............................................................................................. 27


80560NT11586A Rev. 2.0 of 29 2017-10-01

Introduction

1.1 SCOPE

This document provides detailed information about the GainSpan GS2000® based Smartplug Application Development Kit (ADK), by describing its theory of operation, software design, functional features and API’s.

This document assumes that the reader is generally familiar with GainSpan products, Internet Protocol (IP) networks, and the operation of 802.11 wireless devices.

1.2 OVERVIEW

Smartplug ADK demonstrates the capability of GS2000 silicon (packaged as GS2100/GS2101 Mxx) to accurately measure the electrical parameters (voltage, current, frequency, Power, Energy & Power factor) without the help of an external metering IC.

This document is strictly compliant with following software and hardware versions.

NOTE: GainSpan SDK is mandatory for any development on Smartplug ADK.


80560NT11586A Rev. 2.0 of 29 2017-10-01

1.3 TERMINOLOGY

Below table lists the different terminologies used in this document.

Table 1: Glossary of Terms

Term Explanation

AP Access Point

API Application Programmer’s Interface

IP Internet Protocol

TCP Transmission Control Protocol

GEPS GainSpan Embedded Platform Software

POST Power On Self Test

EMU Energy Measurement Unit

FFT Fast Fourier Transform

NOTE: The term ‘Task’ also means thread in this document.


80560NT11586A Rev. 2.0 of 29 2017-10-01

Specifications

This section provides specification of electrical parameters of the GainSpan Smartplug ADK:

Measurement of electrical parameters using the following specification:

➢ Power (reported in Watts):

• 220V system: < 3% error for measurement of power ranging from 20W to 3.3kW and 3 - 7% error for measurement of power ranging from 2W – 20W

• 110V system: < 3% error for measurement of power ranging from 10W to 1.65 kW and 3 – 7% error for measurement of power ranging from 1W to 10W

➢ Voltage (reported in Volts):

• < 1.5% error for voltage readings from 90 to 240V ➢ Current (reported in Amperes):

• < 2% error for current readings from 0.1A to 15A

• < 5% error for current readings from 0.01A to 0.1A

➢ Frequency (reported in Hertz):

• Could measure alternating current from 45Hz – 65Hz

➢ Energy (reported in KWH)

➢ Provisioning methods

• Web/Wireless AP

• WPS


80560NT11586A Rev. 2.0 of 29 2017-10-01

Theory of Operation

GEPS include a module called EMU (Energy Measurement Unit), which takes up the complete responsibility of monitoring and measuring the electrical parameters and report, to application* when queried.

* The term ‘application’ in this document, refers to reference/customer applications (for example, Smartplug) which is built on the top of GEPS.

Energy measurement unit utilizes Sigma Delta-ADC (SD-ADC) of GS2000 silicon, which supports 16bit resolution with differential inputs and optional pre-amplification stage. EMU employees two of SD-ADC channels, each for voltage and current respectively.

There are five useful parameters associated with AC power supply – voltage, current, power, power factor, and frequency. Due to the nature of AC, there are many different definitions of voltage and current. Among those definitions, the most commonly used o n e for power supplies is Root-Mean-Square [4], which is the equivalent DC voltage or current across a pure resistor that consumes the same amount of power as the AC counterpart does. Voltage and current are defined in (1) and (2), where T is the period of one cycle of the voltage or current.

T

dttvTVrms0

21 …………………………… (1)

Irms dttiT

T

0

21 …………………………… (2)

Note that there is no restriction on what periodical function v(t) and i(t) can be, as long as

the integrals in (1) and (2) converge.

Power is defined as,

P = dttitvT

T

0

1 ……………. (3)

In case of DC, power is simply the product o f voltage and current as shown in (4), this is

also true for AC using RMS voltage and current when the load is purely resistive.

IVP ……………………. (4)

When the load is not purely resistive or i f i t is nonlinear, a correction factor can be used [3]

as in (5), where F is a real number that i s no more than 1 and usually greater than 0. F is

called Power Factor.

IV rmsrmsFP …………………………………. (5)


80560NT11586A Rev. 2.0 of 29 2017-10-01

Mathematical Models

Decomposing signals to sinusoidal functions

Signals with finite power can be decomposed into linear combinations of sinusoidal functions.

This is also the foundation of Fourier Transform. Instead of analyzing complicated functions, it

is simpler to treat voltage and current as sin waves. If we have a signal s (t), we can

decompose it into Power and correlation between signals

kk

k

k tfats

2cos0

………………….. (6)

Power and Correlation between Signals

Without loss of generality, we can assume our signals to be cosine functions. For any two signals s1 (t) = cos (2πf2t + α) and s2 (t) = cos (2πf2 t + β), we get

.2cos2

12cos

2

11

0

21

0

212

0

1 dttffT

dttffT

tstsT

TTT

………….

(7)

.2cos2

1

0

21 dttffT

T

The second term in (7) approaches to 0 when 1/(f1 + f2 ) T . Whenever f1 = f2, (7) becomes

0 if we set 21 ffkT

, where k = 1, 2, . . . In other words, (7) becomes 0 if the 2

Signals do not have the same frequency.

Now let s1(t) be the voltage, and s2 (t) be the current, it becomes obvious that the power is

0 when voltage and current are not at the same frequency. Note that w h e n f1 = f2, (7)

becomes cos (α − β), which is not a function of time. This means that when the voltage and current are at the same frequency, power is scaled by cos θ where θ is the phase difference between voltage and current. In this particular case,

cosF …………….. (8)

This can be better illustrated in phasor representation of voltage and current as shown in Figure 1. Using current i(t) as the reference, we can decompose voltage into two terms: in-Phase term and orthogonal term. The power is the product between the in-phase voltage and current. The orthogonal voltage does not contribute to power, as cos π/2 = 0.


80560NT11586A Rev. 2.0 of 29 2017-10-01

Figure 1: Voltage, Current and Power in Phasor Representation

Fourier Transform and FFT

Fourier transform expresses the sinusoidal signals in the form of complex functions in

frequency domain. Let us consider a signal in complex form, with amplitude A

tfjj eAets

02 ………………………… (9)

The Fourier transform of this signal at frequency f0 is

jAefS 0 ………………………………… (10)

Consider (7) again and express the signals as

jAefS 01 ………………….. (11)

jBefS 02 ……………… (12)

If S1 is voltage, S2 is current; power is the REAL part of the product

jjj ABeBeAefSfSP2

1

2

1

2

10

*

201 ……………………… (13)

where < (·) is the real part of a complex number and S∗ is the conjugate of S. The multiplication between signals with the conjugate of another s i g n a l is the same as de- composition shown in Figure 1.

To compute the RMS values of voltage and current, we can simply multiply the voltage (or current) with the conjugate of itself, then take the square root.

2

002

1

2

1AfVfVVrms …………………………………… (14)

2

002

1

2

1BfIfII rms ………………………….. (15)


80560NT11586A Rev. 2.0 of 29 2017-10-01

In the case that the signals are not pure single tone, the RMS values can be computed as

defined in (1) and (2). However, in frequency domain, DC component is simply the Fourier

transform a t f = 0. Therefore, DC contribution can be excluded if we exclude f = 0 from

our computations of RMS values and power, which gives us more accurate results unaffected

by DC offset in the system. To compute the RMS values in frequency domain, the

multiplications should be integrated over the whole band excluding DC.

dffVfVVrms

02

1………………………… (16)

dffIfII rms

02

1………………………….. (17)

Where 0+ is a small positive number larger than 0.

Fast Fourier Transform is an algorithm that computes Discrete Fourier Transform in a very

efficient manner. The output of FFT is at discrete frequency bins. For N-point complex input,

the frequency domain output is from 0 to sfNN 1 ; for N-point real input, the frequency

domain output is from 0 to sfN

N2 . The 0th frequency bin corresponds to DC in the input;

excluding 0th bin (also 1st bin for some margin) from computations removes DC from the sample

block. For FFT outputs with real inputs, (16) and (17) become

k

N

k

krms fVfVV

2

22

1………………………………… (18)

k

N

k

krms fIfII

2

22

1……………………………. (19)

Using FFT results, power factor is simply

rmsrms IV

PF

………………………. (20)

FFT assumes that t h e signal is repetitive, if the sample block does not cover exact integer

multiples of cycles of the signal, there will be distortion in the frequency domain outputs. To

alleviate the problem, window functions [5] can be used. A very effective window function

is Hann window. The effect of Hann window is shown in Figure 2 and Figure 3. It is clear that

without using Hann window, the spectrum produced by FFT is drastically different than

theoretical results when an ideal signal is used, and the spectrum of the captured data without

Hann window is confusing and misleading. Hann window function is defined in (21).

12cos1

2

1

N

kkw ………………………………… (21)

Where 0 ≤ k ≤ N − 1 and the length of the window is N.

In FFT outputs, each bin is centered at a known frequency, that is


80560NT11586A Rev. 2.0 of 29 2017-10-01

sfN

kkf …………………………….. (22)

Where, f (k) is the frequency of k-th bin, N is the length of FFT and fs are the sampling

frequency. Even with help from Hann window, the energy of the signal will spread over 2 or more bins. Depending on the required accuracy of frequency measurements, either the bin number with the highest energy or a weighted combination o f the bin numbers can be used to report the frequency

Figure 2: Effect of Hann Window with an Ideal sin wave

Figure 3: Effect of Hann Window with Voltage Captured on a light Bulb


80560NT11586A Rev. 2.0 of 29 2017-10-01

Power Measurement Algorithms

In order to take the measurements, Voltage and current are sampled at 3600Hz simultaneously i n 1024-sample block. Hann window is applied to both b l o c k s first. Then Real 1024-point FFT is applied to the blocks, we obtain voltage and current spectrum in complex forms

Since inputs are real, only up to 512th bin is used to save computations. 0 and 1st bins are

also discarded to remove DC. So, bin number 2 to 512 is used in the following computations.

Define the magnitude of kth bin signal as

22kSkSkSkSkM

……………………………(23)

Where < {·} takes the real part of a complex number and = {·} takes the imaginary part of a complex number.

We make some assumptions here to form our algorithms:

The voltage is close to a pure sinusoidal signal that h a s no harmonic contents. If there is

harmonics in our capture, we assume that they are coming from our system in circuity or ADC.

Therefore, only signal at the fundamental frequency is considered.

1. The energy spread over no more than ± 3 bins from the center f requency of the

signal. It suffices to sum up the magnitude ac r oss the 7 bins from −3 to +3 from

the signal.

2. Hann window applied to the sample block introduces a loss in energy (magnitude), this

is a constant scaling factor that can be obtained from measurements and simulations.

This loss does not affect signal to noise ratio in the capture.

In the following descriptions, the index of the data array is always from 0 to 512 in FFT

output. We denote the FFT result of voltage signal in kth bin as V (k), and current signal as

I (k).

1. Compute the magnitude of voltage as defined in (23) from index 6 to 75.

2. Find the index kv corresponding to the maximum of the magnitude f rom index 11 (40Hz)

to 20 (70Hz). The narrow range of search is because there is no need to cover a frequency range wider than 40 to 70Hz for voltage signals.

3. Compute the magnitude of the voltage signal as

3

3

v

v

k

kl

v kMM …………………………….. (24)

RMS voltage is the square root of the magnitude

vvrms MCV …………………………………… (25)

Where Cv is the correction factor to the scaling introduced by circuits and window function

4. Compute the magnitude of the current signal as


80560NT11586A Rev. 2.0 of 29 2017-10-01

512

2l

i kMM ………………………………………. (26)

The different range of summation i s to capture all of the harmonics created by the load. RMS

current is the square root of the magnitude

Where Ci is the correction factor to the scaling introduced by circuits and window function

iirms MCI …………………………………. (27)

5. Compute the power at the voltage frequency as

3

3

v

v

k

kl

kIkVP …………………………….. (28)

The narrow range of summation is because of the assumption that voltage is a pure tone at

its fundamental frequency so that harmonics in current are not contributing to power. For

the same reason as in the cases of voltage and current measurements, this computed value

of power needs to be corrected before sending to the user, we have the “corrected” power

as

Pc = Cv Ci P (29)

6. Power factor is computed as

iv MM

PF ……………………………….. (30)

7. The frequency can be simply computed as a weighted average over the 7 bins

3

3

1 v

v

k

kl

s

v

kkMN

f

MFreq ………………………………… (31)

While this is not the most accurate method, it is the simplest with reasonable accuracy

8. The consumed energy by the load is the power integrated over time. Therefore,

Nn

n

c

s

Nn

n

c

s

Pf

LP

f

LE

00 360000010003600

1 ……………………………. (32)

Where the accumulation is from the starting point to current time in number of sample blocks

in the accumulation. L is the length of sampling block we process; it is 1024 in our current

implementation. fs is the sampling frequency, which is 3600Hz in our current

implementation. The commonly used unit for energy measurement is KWH, so the

accumulated resu l t is scaled down by 3600 × 1000. Note the scaling is after the

accumulation i n (32), this is intentional to minimize round off error in calculations. When the


80560NT11586A Rev. 2.0 of 29 2017-10-01

load current is low, it has been observed some fluctuation in current, power and power factor

readings, which is normal as the fluctuation is caused by noise in the measurements. The

accumulation in (32) smooths out the fluctuation automatically, and will provide steady results

after sufficient accumulation time.


80560NT11586A Rev. 2.0 of 29 2017-10-01

Architecture

The GainSpan Smartplug ADK architecture consists of following components and the working mechanism is as described below:

Figure 4: Smartplug Application Design

Smartplug application kick starts the EMU module in a separate thread (task) with relevant configurations as captured below. Once started, application fetches the electrical parameters using the query API explained in section #Query electrical parameters.

• Sampling frequency: 3600Hz

o Frequency of AC expected around the globe is between 45 to 65 Hz, hence

sampling at 3600Hz should fetch us even the farthest harmonics as well.

• Configure SD-ADC channel 1 for current and 2 for voltage.

• Pre-amplify the current wave form by 24bB (for accurately measuring the smaller current

components as well).

• Configure the GPIO on which relay is connected for controlling the load (for example

light bulb).

• Voltage and current scaling factors, which are derived during the calibration procedure.

o These values are saved in file system (non-volatile part of the flash).

• Configure upper and lower threshold value for voltage, current and frequency.

o So that application need not constantly monitor the values, rather EMU will inform

upon threshold crossing.

• Ping-Pong buffers to save the sampled values.

o Why Ping-Pong Buffers: Since electrical parameters need to be monitored

continuously, sampling shall happen in the background while processing the

previous set of samples.


80560NT11586A Rev. 2.0 of 29 2017-10-01

Since EMU employees 1024 FFT, Smartplug application provides ping-pong buffers to hold only 1024 samples (each sample is of 16bits), thereby forcing EMU to process the samples every ~284ms (1024 samples @3600Hz) and complete the operation before next set comes in. This brings in the requirement of executing EMU in a separate thread, so that the processing is always guaranteed within the stipulated time.

4.1 COMPONENTS

4.1.1 Hardware GainSpan Smartplug ADK consists of following hardware components.

Table 2: Hardware Component

Component Description

GainSpan Wi-Fi Module GS2011M module reads and send sensor data over Wi-Fi.

LEDs LED1-Limited AP mode, LED2 Client mode, LED4-Power ON.

Jumper or connector J1 USB Connector

4.1.2 Software GainSpan Smartplug ADK uses the following software components.

Table 3: Software Component

Component Description

NCM (Network Connection Manager)

Manages Wi-Fi association and DHCP client/server.

File system Store or retrieve configuration files, web pages, and so on.

mDNS (Multicast DNS) For announcing the services offered

HTTPD Web server

EMU (Energy measuring unit) Measure electrical parameters


80560NT11586A Rev. 2.0 of 29 2017-10-01

Embedded Application Execution Sequence

This section describes the complete application flow of Smartplug ADK in detail.

5.1 BOOT UP AND INITIALIZATION

The boot up and initialization for Smartplug ADK is as follows:

NOTE: Usage of all the following reference EMU API’s are demonstrated in ‘app_emc.c’ file.

1. ‘AppMainCtx_ThreadEntry’ triggers ‘AppEmu_Init’, which creates the thread and initializes

the EMU module in GEPS.

2. ‘AppMainCtx_ThreadEntry’ reads the configuration from file system (AppSp_readConf/

AppSp_writeConf/ AppSp_checkConf) and kick starts the EMU module ‘AppEmu_Start’.

3. Application also registers a call back function (AppEmu_Callback) which will be invoked by

EMU upon events like threshold crossing, processing error, and so on. All the error codes

are captured in ‘GSN_EMU_STATUS_MSG_T’ structure (captured below for quick

reference).

typedef enum GSN_EMU_STATUS_MSG

{

GSN_EMU_STATUS_MSG_COMMUNICATION_FAILURE = 1,

GSN_EMU_STATUS_MSG_VOLTAGE_UPPER_THRESHOLD_CROSSED = 2,

GSN_EMU_STATUS_MSG_VOLTAGE_LOWER_THRESHOLD_CROSSED = 4,

GSN_EMU_STATUS_MSG_CURRENT_UPPER_THRESHOLD_CROSSED = 8,

GSN_EMU_STATUS_MSG_CURRENT_LOWER_THRESHOLD_CROSSED = 16,

GSN_EMU_STATUS_MSG_FREQ_UPPER_THRESHOLD_CROSSED = 32,

GSN_EMU_STATUS_MSG_FREQ_LOWER_THRESHOLD_CROSSED = 64,

GSN_EMU_STATUS_MSG_REQUESTINPROGRESS = 128,

GSN_EMU_STATUS_MSG_REQUESTCOMPLETED = 256,

GSN_EMU_STATUS_MSG_COMPUTATION_FAILURE = 512,

GSN_EMU_STATUS_MSG_VOLTAGE_COMPUTATION_FAILURE = 1024,

GSN_EMU_STATUS_MSG_CURRENT_COMPUTATION_FAILURE = 2048,

GSN_EMU_STATUS_MSG_PF_COMPUTATION_FAILURE = 4096,

} GSN_EMU_STATUS_MSG_T;


80560NT11586A Rev. 2.0 of 29 2017-10-01

5.2 QUERY ELECTRICAL PARAMETERS

‘AppEmu_GetValues’ demonstrate the querying of electrical parameters from EMU module.

Following is the reference structure where values will be copied.

typedef struct GSN_EMU_ELECTRIC_PARAMS

{

float vrms;

float irms;

float activePower;

float powerfactor;

float frequency;

float accumulateEnergy;

BOOL loadState; //on or off

} GSN_EMU_ELECTRIC_PARAMS_T;

5.3 LOAD CONTROL

1. ‘AppEmu_SetLoad’ demonstrates to switch ON/OFF the load.

2. ‘AppEmu_GetLoadStatus’ demonstrates the querying of load status from EMU.

Smartplug application allows controlling load (for example, light bulb) from external source either through web-interface (refer web-interface section for more details) or through a physical switch (connected to GPIO35). Application toggles the state of load (OFF to ON or vice versa) whenever switch is pressed. This handling is demonstrated in ‘AppEmu_LoadControl’, ‘AppEmu_LoadButtonCB’ and ‘AppEmu_LoadToggleNotify’.

5.4 RESET ENERGY

‘AppEmu_ResetEnergy’ demonstrates the resetting of energy.


80560NT11586A Rev. 2.0 of 29 2017-10-01

Calibration

Voltage and current scaling factors are the output of calibration. Once these values are derived, it is saved in the file system (non-volatile memory) for all successive usages. Calibration is mandatory for every device. The following figure shows the calibration setup.

Figure 5: Calibration Setup

The equipment’s required to perform calibration are as follows:

• Script which is capable of exchanging information with GS2000 (over http) and performing basic math functions.

• Load (for example, light bulb)

• Voltage/current meter (used for accurately measuring the voltage and current of the load)

• For example: Digital Bench Voltage Current Hz Power & Power Factor Meter Tester Alert PF9901

• Smartplug board

6.1 Calibration Procedure

Configure the Perl script “SP_Calibration_Tool.pl” present in location “\ADK\smartplug\Embedded\smartplug\tools” to carry out the calibration procedure. Pre-requisites for executing calibration script:

1. Download and run setup-x86.exe, to install a Cygwin package. 2. Install the Perl Package.

• CURL 3. Open the Cygwin terminal and navigate to “\ADK\smartplug\Embedded\smartplug\tool”. 4. Run the script from the Cygwin Terminal. 5. Enter the following details in the script.

1. MAC Address. 2. Voltage. 3. Current.

6. After a successful calibration, following message appears.


80560NT11586A Rev. 2.0 of 29 2017-10-01

7. Enter the following command to get more information about the script. $./SP_Calibration_Tool.pl –h

Internally, script performs the following step as part of Calibration procedure:

1. Power up the Smartplug board, smartplug device will start computing the electrical parameters with default calibration constants defined in the code. It also starts a web server providing an access to the external world.

1. Connect the load to Smartplug board. 2. Configure the system to calibration mode

• HTTP Method: GET on http://192.168.240.1/gainspan/profile/smartplug?mode=calib

• HTTP Body: NA

• What is calibration mode: In this mode, EMU (energy measurement unit) is restarted with voltage and current scaling factors set to unity (1).

3. Turn on the load

• POST on http://192.168.240.1/gainspan/profile/smartplug

• HTTP Body: <smartplug><load><state>on</state></load></smartplug> 4. Retrieve the electrical parameters from Smartplug

• HTTP Method: GET on http://192.168.240.1/gainspan/profile/smartplug

• HTTP Response: (The values in the following example shows ‘0.000’ as its for reference) <smartplug><version>0.8.1</version><type>SDADC</type><pm><mode>normal</mode><volts>0.000</volts><current>0.000</current><freq>0.000</freq><power>0.000</power><energy>0.000</energy></pm><load><state>off</state></load></smartplug>

5. Compute the calibration constants based on the values retrieved from Smartplug and values obtained from Voltage/current meter.

http://192.168.240.1/gainspan/profile/smartplug?mode=calib

http://192.168.240.1/gainspan/profile/smartplug

http://192.168.240.1/gainspan/profile/smartplug


80560NT11586A Rev. 2.0 of 29 2017-10-01

6. Apply the constants back to Smartplug. This will overwrite the default constants, exit the calibration mode, and restart the EMU in normal mode. These constants are stored in non-volatile memory for subsequent boot ups.

• HTTP Method: POST on http://192.168.240.1/gainspan/profile/smartplug/calib_params

• HTTP Body: <calib_params><volt_sf>7000</volt_sf><curr_sf>11000</curr_sf></calib_params>

• HTTP Response: <status>ok</status>

NOTE: Get on http://192.168.240.1/gainspan/profile/smartplug/calib_params will return the latest constant used.

7. Retrieve the electrical parameters from Smartplug (refer step: ‘e’) with accurate values.

http://192.168.240.1/gainspan/profile/smartplug/calib_params

http://192.168.240.1/gainspan/profile/smartplug/calib_params


80560NT11586A Rev. 2.0 of 29 2017-10-01

APPENDIX - URIS

Following are the various URI’s exposed by web server started by SmartPlug:

Table 4: Web interface specification

URI Description Format

GET: /gainspan/profile/smartplug Get electrical values from SmartPlug

<smartplug>

<version>x.x.x</version>

<type>SDADC</type>

<pm>

<mode>normal/calib</mode>

<volts>xxxxxxx.xxx</volts>

<current>xxxxxxx.xxx</current>

<freq>xxxxxxx.xxx</freq>

<power>xxxxxxx.xxx</power>

<energy>xxxxxxx.xxx</energy>

</pm>

<load>

<state>on/off</state>

</load>

</smartplug>

POST: /gainspan/profile/smartplug

Control the state of load

<smartplug>

<load>

<state>on/off</state>

</load>

</smartplug>

Response:

<status>ok</status>

POST: Reset energy <smartplug>


80560NT11586A Rev. 2.0 of 29 2017-10-01

/gainspan/profile/smartplug <pm>

<energy>0</energy>

</pm>

</smartplug>

Response:

<status>ok</status>

POST:

/gainspan/profile/smartplug?mode=calib

Configure Smartplug to calibration mode

Response:

<status>ok</status>

POST:

/gainspan/profile/smartplug?mode=normal

Configure Smartplug to normal mode

Response:

<status>ok</status>

POST:

/gainspan/profile/smartplug/calib_params

Send calibration parameters derived after calibration procedure

<calib_params>

<volt_sf>xxxxxx</volt_sf>

<curr_sf>xxxxxx</curr_sf>

</calib_params>

Response: <status>ok</status>

GET:

/gainspan/profile/smartplug/calib_params

Retrieve calibration from Smartplug

<calib_params>

<volt_sf>xxxxxx</volt_sf>

<curr_sf>xxxxxx</curr_sf>

</calib_params>





gs2k smartplug application development kit (adk ...€¦ · gs2k smartplug application development...

Documents