Package: comap
This is a wrapper around ComAp API, that allows easy automation ofWebSupervisortasks, such as downloading and analyzing data.
The instructions for testing and examples are available onComAp-API repositoryThere are two modules available:a simpler synchronous modulecomap.apiand asynchronous modulecomap.api_asyncThe async module is recommended for use in production.The modules provide easy access to the ComAp API. For more details about the returned values, check theComAp API Developer PortalFor a better understanding, look at the examples on theComAp-API repositorycomap.apiThis module contains two classes:Identity- serves to authenticate to ComAp Cloud and obtain the token
used in the individual APIs.WSV- set of APIs to communicate with the WebSupervisor PROClass: Identity(key: str)UseComAp-Key,client_idandsecretto obtain theBearer Token, that is needed to authenticate to the WSV API.Example:fromcomapimportapiCLIENT_ID=...# get the id from the a repositorySECRET=...# get the secret from a key repositoryCOMAP_KEY=...# get the key from a key repository# Use the ComAp Cloud Identity API to get the Bearer tokenidentity=api.Identity(COMAP_KEY)token=identity.authenticate(CLIENT_ID,SECRET)Returns{'token_type':'Bearer','expires_in':3599,'ext_expires_in':3599,'access_token':'eyJ0e***redacted***1Z_roeA'}Get theComAp-Keyin yourProfile, the other two values will be available on the Customer portal.Until then, you can generate them from the API documentation using the "Try it" feature:Create Application Registration- this will return theclient_id.Create Application Secret- this will return the secretThese values are valid for 2 years. If you need new values,Delete Application Registrationand create new ones.authenticate(self, client_id: str, secret: str) ‑> dict | NoneAuthenticate and return bearer token dictionary.ParameterTypeValueclient_idstrFrom ComAp customer portalOr generated on API Documentation test portal using Create application registration APIsecretstrFrom ComAp customer portalOr generated on API Documentation test portal using Create application secret APIReturnsThe bearer access tokendictorNoneif failed.{
    'token_type': `str`,
    'expires_in': `number`,
    'ext_expires_in': `number`,
    'access_token': `str` # this is the Bearer access token
}Class: WSV(login_id: str, key: str, token: str)ComAp Cloud WSV API wrapper.
Thelogin_idis your user name (each identity can have multiple WSV user names).Thekeyis the ComAp Key from yourProfile(the same key as for the identity).Thetokenis the bearer token obtained from theIdentityauthenticatemethod.Example:fromcomapimportapi# ...# Obtain the Bearer token from the example aboveLOGIN_ID=...# user nameiftokenisnotNone:# Create WSV instance to call APIswsv=api.WSV(LOGIN_ID,COMAP_KEY,token['access_token'])# Call API to get the list of controller unitsunits=wsv.units()forunitinunits:print(f'{unit["unitGuid"]}:{unit["name"]}')Returnsgenset55e9*********redacted*********** : unit1 name
genset84f8*********redacted*********** : unit2 name
genset38ed*********redacted*********** : unit3 nameunits() -> listGet alistof units with their unitGuidReturns[{'name':`str`,'unitGuid':`str`,'url':`str`}]values(unit_guid: str, value_guids: str | None = None) ‑> listGet alistof values. It is recommended to specify a comma-separated list ofvalueGuidsto filter the result.
You can import VALUE_GUID fromcomap.constantsto get GUIDs for the most common values. Or call the method without GUID to get all values available in the controller, including their GUIDs.ParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationvalue_guidsstr, optionallist of the value guids separated by comma(get it by calling this function with no parameter orget_value_guid)Returns:[{'name':`str`,'valueGuid':`str`,'value':`str`,'unit':`str`,'highLimit':`number`,'lowLimit':`number`,'decimalPlaces':`number`,'timeStamp':`datetime`}]info(unitGuid: str) -> listGet information about the unitParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationReturn{'name':'str','unitGuid':'str','ownerLoginId':'str','applicationType':'str','timezone':'str','connection':{'enabled':boolean,'airGateId':'str','ipAddress':'str','port':number,'controllerAddress':number},'position':{'positionType':'str','latitude':number,'longitude':number}}comments(unitGuid: str) -> listGet comments entered in the WebSupervisor (these can be used for maintenance tasks)ParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationReturns[{"id":`number`,"auhtor":`str`,"date":`datetime`,"text":`str`,"active":`Boolean`}]history(unit_guid: str, value_guids: str | None = None) ‑> listGet the history of a value.ParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV application_fromstr, optionalhistory start date in formatMM/DD/YYYY_to:str, optionalhistory end date in formatMM/DD/YYYYvalue_guidslist, optionallist of the value guids separated by comma(get it by callingvaluesorget_value_guid)Returns[{'value':`str`,'validFrom':`datetime`,'validTo':`datetime`}]files(unitGuid: str) -> listGet thelistof files stored on the controllerParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationReturns:[{'fileName':`str`,'fileType':`str`,'generated':`datetime`}]download(unit_guid: str, file_name: str, path: str = '') ‑> boolDownload a file from the controller to the current directory (or the directory specified inpath). You can list the files using thefilesmethod.ParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationfile_namestrList names by callingfilespathstr, optionalLocal directory to save the file (current directory if not specified)Returns:bool: Was the download succesful?command(unit_guid: str, command: str, mode: str | None = None) ‑> dict | NoneThis allows controlling the genset. The available commands arestart,stop,faultReset,changeMcb(toggle mains circuit breaker),changeGcb(toggle genset circuit breaker) andchangeMode.
ForchangeModeenter themodeparameter e.g. tomanorautoParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationcommandstrsee the API documentation for all possible valuesmodestr, optionalsee the API documentation for all possible valuesReturnsAPI response in theJSONformatget_unit_guid(name: str) ‑> str | None`Find a genset by name. Return is unitGuidParameterTypeValuenamestrgenset nameget_value_guid(unit_guid: str, name: str) ‑> str | NoneFind a value by name. Return valueGuidParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationnamestrvalue namecomap.api_asyncSame ascomap.api, but uses a HTTPS pool session handler (for exampleunits(session), orvalues(session,unitGuid,valueGuids=None)Check the example of use inasync exampleThis module contains two classes:Identity- serves to authenticate to ComAp Cloud and obtain the token
used in the individual APIs.WSV- set of APIs to communicate with the WebSupervisor PROClass: Identity(session: aiohttp.ClientSession, key: str)UseComAp-Key,client_idandsecretto obtain theBearer Token, that is needed to authenticate to the WSV API. It uses an HTTPS pool session handlersession.Example:fromcomapimportapi_asyncimportaiohttpCLIENT_ID=...# get the id from the a repositorySECRET=...# get the secret from a key repositoryCOMAP_KEY=...# get the key from a key repositoryasyncdefauthenticate()->str:asyncwithaiohttp.ClientSession()assession:identity=api_async.Identity(session,COMAP_KEY)token=awaitidentity.authenticate(CLIENT_ID,SECRET)returntokenasyncio.run(authenticate())Returns{'token_type':'Bearer','expires_in':3599,'ext_expires_in':3599,'access_token':'eyJ0e***redacted***1Z_roeA'}Get theComAp-Keyin yourProfile, the other two values will be available on the Customer portal.Until then, you can generate them from the API documentation using the "Try it" feature:Create Application Registration- this will return theclient_id.Create Application Secret- this will return the secretThese values are valid for 2 years. If you need new values,Delete Application Registrationand create new ones.authenticate(self, client_id: str, secret: str) ‑> dict | NoneAuthenticate and return bearer token dictionary.ParameterTypeValueclient_idstrFrom ComAp customer portalOr generated on API Documentation test portal using Create application registration APIsecretstrFrom ComAp customer portalOr generated on API Documentation test portal using Create application secret APIReturnsThe bearer access tokendictorNoneif failed.{
    'token_type': `str`,
    'expires_in': `number`,
    'ext_expires_in': `number`,
    'access_token': `str` # this is the Bearer access token
}Class: WSV(session: aiohttp.ClientSession, login_id: str, key: str, token: str)ComAp Cloud WSV API wrapper.sessionis the HTTPS pool handler.login_idis your user name (each identity can have multiple WSV user names).keyis the ComAp Key from yourProfile(the same key as for the identity).tokenis the bearer token obtained from theIdentityauthenticatemethod.Example:fromcomapimportapi_asyncimportaiohttpCLIENT_ID=...# get the id from the a repositorySECRET=...# get the secret from a key repositoryCOMAP_KEY=...# get the key from a key repositoryLOGIN_ID=...# user nameasyncdefmain()->None:asyncwithaiohttp.ClientSession()assession:# Use the ComAp Cloud Identity API to get the Bearer tokenidentity=api_async.Identity(session,COMAP_KEY)token=awaitidentity.authenticate(CLIENT_ID,SECRET)iftokenisnotNone:# Create WSV instance to call APIswsv=api_async.WSV(session,LOGIN_ID,COMAP_KEY,token['access_token'])# Call API to get the list of controller unitsunits=awaitwsv.units()forunitinunits:print(f'{unit["unitGuid"]}:{unit["name"]}')asyncio.run(main())Returnsgenset55e9*********redacted*********** : unit1 name
genset84f8*********redacted*********** : unit2 name
genset38ed*********redacted*********** : unit3 nameunits() -> listGet alistof units with their unitGuidReturns[{'name':`str`,'unitGuid':`str`,'url':`str`}]values(unit_guid: str, value_guids: str | None = None) ‑> listGet alistof values. It is recommended to specify a comma-separated list ofvalueGuidsto filter the result.
You can import VALUE_GUID fromcomap.constantsto get GUIDs for the most common values. Or call the method without GUID to get all values available in the controller, including their GUIDs.ParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationvalue_guidsstr, optionallist of the value guids separated by comma(get it by calling this function with no parameter orget_value_guid)Returns:[{'name':`str`,'valueGuid':`str`,'value':`str`,'unit':`str`,'highLimit':`number`,'lowLimit':`number`,'decimalPlaces':`number`,'timeStamp':`datetime`}]info(unitGuid: str) -> listGet information about the unitParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationReturn{'name':'str','unitGuid':'str','ownerLoginId':'str','applicationType':'str','timezone':'str','connection':{'enabled':boolean,'airGateId':'str','ipAddress':'str','port':number,'controllerAddress':number},'position':{'positionType':'str','latitude':number,'longitude':number}}comments(unitGuid: str) -> listGet comments entered in the WebSupervisor (these can be used for maintenance tasks)ParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationReturns[{"id":`number`,"auhtor":`str`,"date":`datetime`,"text":`str`,"active":`Boolean`}]history(unit_guid: str, value_guids: str | None = None) ‑> listGet the history of a value.ParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV application_fromstr, optionalhistory start date in formatMM/DD/YYYY_to:str, optionalhistory end date in formatMM/DD/YYYYvalue_guidslist, optionallist of the value guids separated by comma(get it by callingvaluesorget_value_guid)Returns[{'value':`str`,'validFrom':`datetime`,'validTo':`datetime`}]files(unitGuid: str) -> listGet thelistof files stored on the controllerParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationReturns:[{'fileName':`str`,'fileType':`str`,'generated':`datetime`}]download(unit_guid: str, file_name: str, path: str = '') ‑> boolDownload a file from the controller to the current directory (or the directory specified inpath). You can list the files using thefilesmethod.ParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationfile_namestrList names by callingfilespathstr, optionalLocal directory to save the file (current directory if not specified)Returns:bool: Was the download succesful?command(unit_guid: str, command: str, mode: str | None = None) ‑> dict | NoneThis allows controlling the genset. The available commands arestart,stop,faultReset,changeMcb(toggle mains circuit breaker),changeGcb(toggle genset circuit breaker) andchangeMode.
ForchangeModeenter themodeparameter e.g. tomanorautoParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationcommandstrsee the API documentation for all possible valuesmodestr, optionalsee the API documentation for all possible valuesReturnsAPI response in theJSONformatget_unit_guid(name: str) ‑> str | None`Find a genset by name. Return is unitGuidParameterTypeValuenamestrgenset nameget_value_guid(unit_guid: str, name: str) ‑> str | NoneFind a value by name. Return valueGuidParameterTypeValueunit_guidstrthe genset ID (from theunitsAPI, or in WSV applicationnamestrvalue name