nrgpy.cloud_api package
Contents
nrgpy.cloud_api package#
Submodules#
nrgpy.cloud_api.auth module#
- class nrgpy.cloud_api.auth.cloud_api(client_id='', client_secret='')[source]#
Bases:
object
Parent class for NRG Cloud API functionality
nrgpy simplifies usage of the NRG Cloud APIs. See the documentation for the cloud_api.sites, .export, and .convert modules for more information.
For non-nrgpy implementations, the following Usage information may be helpful.
The base url for the NRG Cloud APIs is
https://cloud-api.nrgsystems.com/nrgcloudcustomerapi/
Use client ID and secret to obtain a bearer token at the /token endpoint. This token is good for 24 hours.
You will be limited to creating 10 tokens per day, though normally one token should suffice, so please cache. nrgpy’s cloud_api modules will automatically manage bearer tokens, refreshing only when necessary.
Endpoints:
- /token
for accessing bearer token. Client ID and Secret required.
- /sites
Get list of sites. Bearer token required
- /convert
Convert RLD file to TXT. Bearer token required
- /export
Export TXT or RLD files for a given date range. NEC files may be used to format TXT outputs. Bearer token required.
- load_token(filename='C:/Users/ndb\\.nrgpy\\.cloud_token')[source]#
read session token from pickle file
- maintain_session_token(filename='C:/Users/ndb\\.nrgpy\\.cloud_token')[source]#
maintain a current/valid session token for data service api
- request_session_token()[source]#
Generates a new session token for convert service api
Requires an active account with NRG Cloud. To sign up for a free account, go to:
Client ID and Secret can be accessed here:
https://cloud.nrgsystems.com/data-manager/api-setup
- Parameters
- client_idstr
obtained from NRG Systems
- client_secretstr
- Returns
- session_tokenstr
valid for 24 hour
- session_start_timedatetime
start time of 24 hour countdown
nrgpy.cloud_api.convert module#
- class nrgpy.cloud_api.convert.cloud_convert(rld_dir='', out_dir='', filename='', site_filter='', filter2='', start_date='1970-01-01', end_date='2150-12-31', client_id='', client_secret='', export_type='measurements', nec_file='', unzip=True, progress_bar=True, **kwargs)[source]#
Bases:
nrgpy.cloud_api.auth.cloud_api
Uses NRG hosted web-based API to convert RLD and RWD files to text format To sign up for the service, go to https://cloud.nrgsystems.com/.
Note that the site must exist in the NRG Cloud platform, and you must have Contributor or Administrator level access to the site to use these features.
- Parameters
- rld_dirstr (path-like)
path to rld file directory
- out_dirstr (path-like)
path to save text export files
- filenamestr
provide for single file conversion
- site_filterstr, optional
text filter for limiting file set
- filter2str, optional
another text filter…
- start_datestr, optional
text start date to filter on “YYYY-mm-dd”
- end_datestr, optional
text end date to filter on “YYYY-mm-dd”
- client_idstr
provided by NRG Systems
- client_secretstr
provided by NRG Systems
- nec_filestr, optional
path to NEC file for custom export formatting
- export_typestr
[measurements], diagnostic, events, communication
Examples
Convert a single raw data file to Text with NRG Convert API
>>> import nrgpy >>> filename = "/home/user/data/sympro/000123/000123_2019-05-23_19.00_003672.rld >>> client_id = "go to https://cloud.nrgsystems.com/data-manager/api-setup for access" >>> client_secret = "go to https://cloud.nrgsystems.com/data-manager/api-setup for access" >>> converter = nrgpy.cloud_convert( file_filter=file_filter, filename=filename, client_id=client_id, client_secret=client_secret, )
Convert a folder of raw data files to Text with NRG Convert API
>>> import nrgpy >>> file_filter = "000175" >>> rld_directory = "rlds" >>> txt_dir = "/home/user/data/sympro/000123/txt/" >>> client_id = "go to https://cloud.nrgsystems.com/data-manager/api-setup for access" >>> client_secret = "go to https://cloud.nrgsystems.com/data-manager/api-setup for access" >>> converter = nrgpy.cloud_convert( file_filter=file_filter, rld_dir=rld_directory, out_dir=txt_dir, client_id=client_id, client_secret=client_secret, start_date="2020-01-01", end_date="2020-01-31", ) >>> converter.process()
nrgpy.cloud_api.export module#
- class nrgpy.cloud_api.export.cloud_export(out_dir='', site_id='', site_number='', logger_sn='', start_date='2014-01-01', end_date='2030-12-31', file_format='txt', client_id='', client_secret='', nec_file='', export_type='measurements', interval='', unzip=True, **kwargs)[source]#
Bases:
nrgpy.cloud_api.auth.cloud_api
Uses NRG hosted web-based API to download data in text format To sign up for the service, go to https://cloud.nrgsystems.com
Note that the site must exist in the NRG Cloud platform, and you must have Contributor or Administrator level access to the site to use these features.
Use the Site Number or NRG Cloud Site ID to choose the site.
- Parameters
- out_dirstr (path-like)
path to save exported data
- site_idint
NRG Cloud site identifier (NOT the site number)
- site_numberint
site number
- logger_snstr or int
serial number of data logger (like, 820612345)
- start_datestr
“YYYY-MM-DD HH:MM:SS” format, if just date it will return the whole day times are in logger local time
- end_datestr
“YYYY-MM-DD HH:MM:SS” format, if just date it will return the whole day times are in logger local time
- file_formatstr
[‘txt’], ‘rld’ - whether tab-delimited text or binary output
- client_idstr
available in the NRG Cloud portal
- client_secretstr
available in the NRG Cloud portal
- nec_filestr, optional
path to NEC file for custom export formatting
- export_typestr
[‘measurements’], ‘diagnostic’, ‘events’, ‘communication’
- intervalstr, optional
‘oneMinute’, ‘twoMinute’, ‘fiveMinute’, ‘tenMinute’, ‘fifteenMinute’, ‘thirtyMinute’, ‘Hour’, ‘Day’ must be a multiple of the logger’s statistical interval
- unzipbool
(True) whether to extract the .txt data file from the .zip file
- Returns
- object
export object, including API response
Examples
Download 15 days of data with an NEC file applied, and read data
>>> import nrgpy >>> >>> client_id = "go to https://cloud.nrgsystems.com for access" >>> client_secret = "go to https://cloud.nrgsystems.com for access" >>> save_dir = '/path/to/exported/data' >>> >>> exporter = nrgpy.cloud_export( client_id=client_id, client_secret=client_secret, out_dir=save_dir, nec_file='12vbat.nec', site_id=245, start_date="2021-05-01", end_date="2021-05-15", ) >>> exporter.export() >>> # read result >>> reader = nrgpy.sympro_txt_read(exporter.export_filepath) >>> reader.format_site_data() >>> if reader: >>> print(f"Site number : {reader.site_number}") >>> print(f"Site description : {reader.site_description}") >>> reader.interval_check = nrgpy.check_intervals(reader.data) >>> else: >>> print("unable to get reader")
nrgpy.cloud_api.jobs module#
- class nrgpy.cloud_api.jobs.export_job(out_dir='', site_id='', site_number='', logger_sn='', start_date='2014-01-01', end_date='2023-12-31', file_format='txt', client_id='', client_secret='', nec_file='', export_type='measurements', interval='', unzip=True, **kwargs)[source]#
Bases:
nrgpy.cloud_api.export.cloud_export
Uses NRG hosted web-based API to download data in text format as an export job To sign up for the service, go to https://cloud.nrgsystems.com
Note that the site must exist in the NRG Cloud platform, and you must have Contributor or Administrator level access to the site to use these features.
Use for creating exports of any size. Extends nrgpy.cloud_export class
- Parameters
- out_dirstr (path-like)
path to save exported data
- site_idint
NRG Cloud site identifier (NOT the site number)
- site_numberint
site number
- logger_snstr or int
serial number of data logger (like, 820612345)
- start_datestr
“YYYY-MM-DD HH:MM:SS” format, if just date it will return the whole day times are in logger local time
- end_datestr
“YYYY-MM-DD HH:MM:SS” format, if just date it will return the whole day times are in logger local time
- client_idstr
available in the NRG Cloud portal
- client_secretstr
available in the NRG Cloud portal
- nec_filestr, optional
path to NEC file for custom export formatting
- export_typestr
[‘measurements’], ‘diagnostic’, ‘events’, ‘communication’
- file_formatstr
[‘txt’], ‘rld’ - whether tab-delimited text or binary output
- intervalstr, optional
‘oneMinute’, ‘twoMinute’, ‘fiveMinute’, ‘tenMinute’, ‘fifteenMinute’, ‘thirtyMinute’, ‘Hour’, ‘Day’ must be a multiple of the logger’s statistical interval. if not specified, will use “native” interval (usually oneMinute for solar, tenMinute for wind)
- unzipbool
(True) whether to extract the .txt data file from the .zip file
- Returns
- object
export object, including API response
Examples
Download 15 days of data with an NEC file applied, and read data
>>> import nrgpy >>> >>> client_id = "go to https://cloud.nrgsystems.com for access" >>> client_secret = "go to https://cloud.nrgsystems.com for access" >>> save_dir = '/path/to/exported/data' >>> >>> exporter = nrgpy.export_job( client_id=client_id, client_secret=client_secret, out_dir=save_dir, nec_file='12vbat.nec', site_number=3456, start_date="2021-04-01", end_date="2022-03-31", file_format="txt", # <--- can be "rld" for raw data files unzip=True, ) >>> >>> exporter.create_export_job() >>> exporter.monitor_export_job(download=True) >>> # read resulting files >>> reader = nrgpy.sympro_txt_read(exporter.export_filepath) >>> reader.format_site_data() >>> if reader: >>> print(f"Site number : {reader.site_number}") >>> print(f"Site description : {reader.site_description}") >>> reader.interval_check = nrgpy.check_intervals(reader.data) >>> else: >>> print("unable to get reader")
nrgpy.cloud_api.sites module#
- class nrgpy.cloud_api.sites.cloud_sites(client_id, client_secret)[source]#
Bases:
nrgpy.cloud_api.auth.cloud_api
Returns sites that user has access to.
- Parameters
- client_idstr
available in the NRG Cloud portal
- client_secretstr
available in the NRG Cloud portal
- Returns
- object
sites_list : list sites_df : pandas dataframe