Beruflich Dokumente
Kultur Dokumente
Automation
QuickStart Guide
LastUpdatedfor4.0.5.1
Contents
AboutthisGuide...........................................................................................................................................1
Introduction..................................................................................................................................................2
Installation....................................................................................................................................................2
InterfaceDefinition.......................................................................................................................................2
Usage.............................................................................................................................................................6
Approach1:.NET......................................................................................................................................6
Approach2:COM......................................................................................................................................7
1.
RegistertheassemblyandgenerateaTLBfile.............................................................................7
2.
RegistertheassemblywiththeGAC.............................................................................................7
3.
ImporttheTLBfileandinitializetheCOMobjects.......................................................................8
Overview...................................................................................................................................................9
SampleImplementations........................................................................................................................11
C#Samples..........................................................................................................................................11
C++Samples........................................................................................................................................11
Introduction
OnecanstartorstopmultiplePowerToolapplications,connecttovariousPowerMonitordevices,set
triggercodes,startandstopsampleruns,orsaveandloadfilesviaprogrammaticcontrol,muchlikean
interactiveusercandosittingathisorherconsole.
Thisdocumentassumesthatthereaderhasatleastsomefamiliaritywithprogrammingconceptsin
general,andCOMorthe.NETFrameworkinparticular.
Installation
First,installthePowerToolapplicationviaourstandardinstaller.Typically,youwillhavealreadydone
thatifyouhavegottentothispoint.TheAutomationsampleimplementationscanbefoundinthe
DeveloperExamplessubdirectorywhereyouinstalledtheMonsoonPowerToolapplications.
Executablesandsourcecodearebothdistributedfortheseexamples.AVisualStudiosolutionfileis
present,asareindividualprojectfilesforeachexample.Besuretoreadourusagenotesbeforebuilding
thesamples.Yournextstepswillvarydependingonwhetheryouareaccessingthelibraryvia.NET
awarelanguageslikeC#orviaCOMawarelanguageslikeC++.
Note,ifyouarebuildingthesolutionasawhole,youwillneedtofollowthestepsforCOMand.NETor
theC++exampleswillnotbuild.IfyouareonlybuildingspecificC#sampleprojects,thenyoucanskip
theCOMspecificsteps.
Interface Definition
Subjecttochange.Currentasof4.0.5.0.Note,theinterfacechangedin4.0.5.0!
[
Guid("B134840E-1BE3-4789-B04E-DBAD3BEE8E79"),
InterfaceType(ComInterfaceType.InterfaceIsDual),
ComVisible(true),
]
public interface IAutomation
{
#region IAutomation Properties
// Whether the PowerTool application is open
bool ApplicationIsOpen { get; }
// Whether a Power Monitor device is connected
bool DeviceIsConnected { get; }
// Whether a sample is currently running
bool SampleIsRunning { get; }
// Serial number of the connected device
ushort DeviceSerialNumber { get; }
// Whether the application has any data captured or loaded from file
bool HasData { get; }
PowerTool.AutomationQuickStartGuide
PowerTool.AutomationQuickStartGuide
PowerTool.AutomationQuickStartGuide
bool overwriteFile,
bool createDirectory);
// File name
// Overwrite file?
// Create directory?
// 0..(TotalSampleCount-1)
// 0..(TotalSampleCount-1)
// File name
// 1,10,100,1000,10000 the
//modulus used to determine
//which samples to export
// Overwrite file?
// Create directory?
// Sample retrieval
bool GetSample( ulong sampleIndex,
out Sample sample);
// 0..(TotalSampleCount-1)
// A Sample structure
// 0..(TotalSampleCount-1)
// Number of samples desired
// Array of Sample structures
PowerTool.AutomationQuickStartGuide
Usage
Approach 1: .NET
.Net4.5isspecificallyrequiredforversion4.0.5.0.
Asof4.0.5.0,allincludedprojectsarebuiltunderVisualStudio2015.IfyouwishtobuildunderVisual
Studio2012andareonlyusingC#,disabletheCPPClientproject.Otherwise,youmustsetyour
PlatformToolsettoVisualStudio2012fortheCPPClientprojectoryouwillhavebuilderrorswhenyou
buildfromtheSolutionasawhole.
.Net4.0isspecificallyrequiredforversion4.0.4.11.
.NET3.5isspecificallyrequiredforversions4.0.4.04.0.4.10.
Assumingthatyouarewritingyourcodeina.NETcompatiblelanguage,suchasC#,yousimplyneedto
fixthereferencetoPowerTool.exeinyourprojecttopointtowhereveritwasinstalledonyour
computer.
ThesimplestwaytodothisisremovePowerTool.exefromyourprojectreferences,andthenreaddit.
PowerTool.AutomationQuickStartGuide
Noadditionalassemblyregistrationorstepsarenecessary.Ifyoudidregisteranearlierassemblyinthe
GAC,.NETwillpullthatassemblyfirst,andyoumustunregisterittocompileagainstthenewassembly.
Approach 2: COM
Alternatively,ifyouwanttodoittheoldfashionedway(COMstyle)withalanguagesuchasC++,follow
thefollowingsteps.YouwillneedtoredothesestepsanytimethereisanewversionofthePowerTool
executableoraninterfacechange.
Note,COMsupportrequiresversion4.0.4.9orlaterofthePowerToolapplication.Alsonotethatthe
COMAPIisnotasfullfeaturedasthe.NETAPIanddoesnotexposeallofthesamefunctionality.
Asof4.0.5.0,allincludedprojectsarebuiltunderVisualStudio2013.IfyouwishtobuildunderVisual
Studio2012,youmustsetyourPlatformToolsettoVisualStudio2012fortheCPPClientprojectoryouwill
havebuilderrors.
1. Register the assembly and generate a TLB file.
Thissteprequiresthatyouhaveinstalledthefree.NET3.5(orhigher)SDKfromMicrosoft.
Openacommandpromptasanadministratorandchangetothe.NETdirectorywhereregasmis
installed(forexample:c:\Windows\Microsoft.NET\Framework\v4.0.30319).Runthefollowing
command:
RegAsm.exe[pathtopowertool.exe]/tlb:PowerTool.tlb
Forexample,withthedefaultPowerToolinstalllocation,youwouldrun
RegAsm.exeC:\ProgramFiles(x86)\MonsoonSolutionsInc\PowerMonitor\PowerTool.exe
/tlb:PowerTool.tlb
Theabovecommand,oncecompletedsuccessfully,registersthePowerTool.exeapplicationasthe
serverforthePowerTool.Automationobjectandgeneratesthetlbfileyouwillneedtoimportinyour
code.
Youshouldseeanoutputalongthelinesof:
Typesregisteredsuccessfully
Assemblyexportedto'c:\ProgramFiles(x86)\MonsoonSolutionsInc\PowerMonitor\PowerTool.tlb',andthetype
librarywasregisteredsuccessfully
IfyouneedtouninstalltheassemblyfromtheGAC,youcanissuethecommand:
gacutil/uPowerTool
Registeryournewassembly:
gacutil/iC:\ProgramFiles(x86)\MonsoonSolutionsInc\PowerMonitor\PowerTool.exe
Youshouldseeanoutputalongthelinesof:
Assemblysuccessfullyaddedtothecache.
YoucanquerytheGACtoseethePowerToolassemblyisinstalledwiththefollowingcommand.Make
surethePowerToolassemblyversionshownistheoneyouexpect.
gacutil/lPowerTool
IMPORTANT!Fixthispathtomatchyourcurrentlocation!
#import"C:\ProgramFiles(x86)\MonsoonSolutionsInc\PowerMonitor\PowerTool.tlb"
Specifythenamespace
usingnamespacePowerTool;
InitializetheCOMlibrary
::CoInitialize(NULL);
Getthepowertoolinstance
IAutomation*pAutomation=NULL;
CComPtr<IAutomation>autoPtr;
HRESULThr=autoPtr.CoCreateInstance(_T("PowerTool.Automation"));
Dowhateveryouwanttodoherewiththeinterface.
PowerTool.AutomationQuickStartGuide
Cleanup
if(pAutomation)
pAutomation>Release();
CoUninitialize();
Overview
ThefollowingsamplecallsarewritteninC#.Toseeacompleteimplementation,lookatoursamples.
Startoutwith:
PowerTool.AutomationmyPowerTool=newPowerTool.Automation();
Ifyougetanonnullresult,youarenowinprogrammaticcontrolofthePowerTool.Youcanopenmore
thanonePowerToolifyouwish.Eachisrepresentedinyourspacebytheobjectyouinstantiated,as
above.
So,nowthatyouhaveaPowerToolinstance,whatcanyoudowithit?Youmightstartoutbyrunningit:
boolpowerToolRunning=myPowerTool.OpenApplication(false,30);
The30specifiesthenumberofwaitintervalswerewillingtowaitfortheapptostartup.Thedefault
intervalis1000milliseconds,sointheabovecall,wesaidwerewillingtowait30intervals,or30
seconds.ThefalsetellsitnottoreaditsINIfile,welltakethedefaults.
OncethePowerToolappisrunning,itmightbeconvenienttoknowwhatPowerMonitordevicesare
attachedtothehostcomputer:
ushort[]serialNumbers=newushort[1];
//justtemporarygetsreplacedshortly
uintdeviceCount=myPowerTool.EnumerateDevices(outserialNumbers);
IftherearenoPowerMonitors,theEnumerateDevicescallreturnszero,andnullsouttheoutputarray.
Otherwise,itgivesusanewarrayofserialnumbers,andreturnsthecountofdevices.
Ifweseeadevicewelike,wecanconnecttoitbyspecifyingitsserialnumber.So,say
EnumerateDevices()reportedbackatleastonedevice.Wecanthenissuethefollowingcalltoconnect
tothefirstdevice:
booldeviceConnected=myPowerTool.ConnectDevice(serialNumbers[0]);
Nowthatwereconnected,thedeviceisoursandwillstaythatwayuntilwedisconnect,orsomeone
pullstheplug.
Howaboutwetakesomesamples?
PowerTool.AutomationQuickStartGuide
myPowerTool.Visible=true;
//Letswatchitrun
myPowerTool.MainOutputVoltageSetting=3.7;
//Ourdevicelikes3.7volts
myPowerTool.EnableMainOutputVoltage=true;
//Giveitthejuice
boolstarted=myPowerTool.StartSampling(10);
//Sametimingrulesasabove
//
//Wedootherstuffwhilesamplingoccursonabackgroundthread,andthen
//
boolstopped=myPowerTool.StopSampling(10);
//Stopsamplingsametimingrules
myPowerTool.EnableMainOutputVoltage=false;
//Leavethedevicepoweredoff
Okay,nowwehavesampledatasittinginPowerToolsworkingmemory.Exactly5,000datapointsfor
eachsecondthatthesamplewasrunning.Whatdowedowiththisdata?Well,wecouldsaveitina
file
booldataSaved=myPowerTool.SaveFile(C:\\MyFolder\\MyFile.pt4,true,true);
Thetruevaluesmerelytellittooverwriteanylikenamedfileitmayfindinthatfolder,andtocreate
thefolderifitdoesntalreadyexist.
Nowthatourdataissaved,letscleanup
myPowerTool.DisconnectDevice();
myPowerTool.CloseApplication(false,true);
myPowerTool=null;
//Disconnect
//DontwriteINIfile,waitforclosure
//Disposeoftheinterface
Theaboveisintendedasasimplereferenceandisnotacompleteguide.Seethesample
implementationsthatareincludedforadditionalexamples.
PowerTool.AutomationQuickStartGuide
10
Sample Implementations
AVisualStudioSolutionfileisprovidedforyourconvenience.DeveloperTools.slncontainstheprojects
referencedbelow.
C# Samples
IMPORTANTNOTE:Tobuildanyoftheseprojects,changetheprojectreferencetoPowerTool.exeto
reflectitsinstalledlocationonyoursystem.
ConsoleExamples
Severalsimpleexamplesareprovidedtodemonstratedifferentcapabilities.
SimpleSamplingExampleshowshowtoconnecttoadevice,sample,accessrealtimesamplingdata,
andexportdatatoCSVandPT4files.
IterativeCallingExampletakesthefunctionalityofSimpleSamplingExample,butrunsititeratively,
showinghowtoproperlyshutdownandstartupyourconnectionseachtime.
ResetExampleshowshowtousethenewto4.0.5.0ResetPowerToolmethodtocyclethepowertothe
connectedPowerMonitordevice.
IniTriggerExampleshowshowtousetheAutomationinterfacetoworkwithtriggercodesininifiles.
PT4Readershowshowtoreadinapt4filetoextractthestoreddata.
PT5Readershowshowtoreadinapt5filetoextractthestoreddata.
RecalibrateExampleshowshowtoprogrammaticallyrecalibratethePowerMonitor.
WindowsApplicationExample
AsampleapplicationAutoDemoisincluded,bothasanexecutableandwithfullsourcecode.It
containsafullfeaturedWindowsGUIappthatdemonstratesamoreinvolvedimplementationofthe
PowerTool.Automationinterface.
Whenyouruntheexecutable,clickOPENtoconnecttoanavailablePowerTooldevice.Thiswillrefresh
thelistofdevicesavailabletoconnectviatheAutoDemoapplication.Makesureyourdesireddeviceis
selected,andthenclickCONNECTtoactivatecontrolofthePowerToolinstanceviatheAutoDemo
application.
C++ Samples
IMPORTANTNOTE:BesureyouhavefullyfollowedthedirectionslistedforusingCOM,beforeusing
thesesamples.Also,besuretoeditthepathtoyourTLBfileinyourcode.
ConsoleExample
PowerTool.AutomationQuickStartGuide
11
AsimpleapplicationCPPClientisincluded,bothasanexecutableandwithfullsourcecode.Itcontains
aconsoleapplicationthatusestheCOMinterface.ItdemonstratesconnectingtothePowerTool
applicationandtoaspecificPowerMonitordevice,takingashortsample,andwritingtheoutputtoa
pt4file.
PowerTool.AutomationQuickStartGuide
12