{"openapi":"3.0.0","info":{"title":"ABAC API Collection (v0.0.3)","description":"Postman collection for the Ammonia Based Aeration Control (ABAC) software for use with the xGateway. ABAC uses an on-line measurement of ammonium in aeration basins to dynamically adjust the dissolved oxygen (DO) setpoint when at loads below the design values and temperatures to recover energy, while ensuring effluent ammonia limits are continuously achieved. The ABAC software is further described in detail in the Functional Description Narrative (FDN) document located in its Confluence page. ","contact":{},"version":"0.0.3"},"servers":[{"url":"{baseUrl}/xcpc/abac","variables":{"baseUrl":{"default":"http://172.16.0.1","description":"IP address for xGateway."}}}],"paths":{"/config":{"post":{"tags":["ABAC Configuration"],"summary":"Post the main configuration specifications for the ABAC algorithm at the site.","operationId":"Set:MainConfig","parameters":[{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/UID"},{"name":"plant-elevation","in":"header","description":"Elevation of the plant above sea level.","required":true,"style":"simple","schema":{"type":"number","example":"100.0"}},{"name":"blower-motor-efficiency","in":"header","description":"Efficiency of the blower motor, between 0.0 and 1.0.","required":true,"style":"simple","schema":{"type":"number","example":"0.7"}},{"name":"power-cost","in":"header","description":"Cost of a kW-hr, in US $/kW-hr.","required":true,"style":"simple","schema":{"type":"number","example":"0.075"}},{"name":"groups","in":"header","description":"Object with group details.","required":true,"style":"simple","schema":{"type":"array","items":{"$ref":"#/components/schemas/Group"}}}],"requestBody":{"description":"JSON object containing configuration information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MainConfig"}}},"required":true},"responses":{"200":{"$ref":"#/components/responses/SuccessPost"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/ServerError"}},"deprecated":false},"get":{"tags":["ABAC Configuration"],"summary":"Get the main configuration specifications for the ABAC algorithm at the site.","operationId":"Get:Main-Config","parameters":[{"name":"Content-Type","in":"header","description":"","required":true,"style":"simple","schema":{"type":"string","example":"application/json"}}],"responses":{"200":{"description":"Returns main configuration specifications.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MainConfig"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/root/active-layout":{"get":{"tags":["ABAC Management"],"summary":"Get the active layout for ABAC.","operationId":"Get:ABAC-ActiveLayout","parameters":[],"responses":{"200":{"$ref":"#/components/responses/SuccessGet"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/cu/{CU-ID}/input":{"post":{"tags":["Control Units (CU)"],"summary":"Set input measured parameters for CU.","operationId":"Set:Input:InputMeasuredParameters","parameters":[{"$ref":"#/components/parameters/CU_ID"}],"requestBody":{"description":"JSON object containing input measured parameter information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InputMeasuredParameters"}}}},"responses":{"200":{"$ref":"#/components/responses/SuccessPost"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/ServerError"}},"deprecated":false},"get":{"tags":["Control Units (CU)"],"summary":"Get input measured parameters for CU.","operationId":"Get:Input:InputMeasuredParameters","parameters":[{"name":"Content-Type","in":"header","description":"","required":true,"style":"simple","schema":{"type":"string","example":"application/json"}},{"$ref":"#/components/parameters/CU_ID"}],"responses":{"200":{"description":"Successful request.","content":{"object":{"schema":{"$ref":"#/components/schemas/InputMeasuredParameters"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/cu/{CU-ID}/output":{"get":{"tags":["Control Units (CU)"],"summary":"Get output parameters for CU.","operationId":"Get:Output:Parameters","parameters":[{"$ref":"#/components/parameters/CU_ID"}],"responses":{"200":{"description":"Successful request.","content":{"object":{"schema":{"$ref":"#/components/schemas/OutputParameters"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/cu/{CU-ID}/internal-calculation":{"get":{"tags":["Control Units (CU)"],"summary":"Get ABAC internal calculations, used for testing.","operationId":"Get:Internal-Calculations(forTesting)","parameters":[{"$ref":"#/components/parameters/CU_ID"}],"responses":{"200":{"description":"Successful request.","content":{"object":{"schema":{"$ref":"#/components/schemas/InternalCalculations"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/cu/{CU-ID}/config-dynamic":{"post":{"tags":["Control Units (CU)"],"summary":"Set dynamic configuration parameters for CU.","operationId":"Set:Input:ConfigParameters","parameters":[{"$ref":"#/components/parameters/CU_ID"}],"requestBody":{"description":"JSON object containing dynamic configuration parameter information.","content":{"object":{"schema":{"$ref":"#/components/schemas/InputConfigParams"}}}},"responses":{"200":{"$ref":"#/components/responses/SuccessPost"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/ServerError"}},"deprecated":false},"get":{"tags":["Control Units (CU)"],"summary":"Get input configuration parameters for CU.","operationId":"Get:Input:ConfigParameters","parameters":[{"name":"Content-Type","in":"header","description":"","required":true,"style":"simple","schema":{"type":"string","example":"application/json"}},{"$ref":"#/components/parameters/CU_ID"}],"responses":{"200":{"description":"Successful request.","content":{"object":{"schema":{"$ref":"#/components/schemas/InputConfigParams"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/cu/{CU-ID}/alarm":{"get":{"tags":["Control Units (CU)"],"summary":"Get output alarms for CU.","operationId":"Get:Output:Alarms","parameters":[{"$ref":"#/components/parameters/CU_ID"}],"responses":{"200":{"description":"","content":{"object":{"schema":{"$ref":"#/components/schemas/OutputAlarmTags"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}}},"components":{"schemas":{"MainConfig":{"title":"Main Configuration","required":["name","uid","plant-elevation","blower-motor-efficiency","power-cost","groups"],"type":"object","maxProperties":7,"additionalProperties":{"$ref":"#/components/schemas/InternalSWConfig"},"properties":{"name":{"type":"string"},"uid":{"type":"string"},"plant-elevation":{"type":"number"},"blower-motor-efficiency":{"type":"number"},"power-cost":{"type":"number"},"groups":{"$ref":"#/components/schemas/Group"}},"example":{"name":"Muncie,IN","uid":"14-8231A","plant-elevation":100,"blower-motor-efficiency":1,"power-cost":30,"groups":[{"name":"group-a","average-basin-depth":10,"cu":[{"name":"cu-a-1","nh4-setpoint":2,"nh4-deadband":1,"nh4-control":1,"allowable-nh4-variance":25,"min-do-setpoint":0,"max-do-setpoint":10,"fixed-do-setpoint":5,"fixed-do-concentration":3,"pid-configuration":{"type":"rockswell-pide","equation-type":"independent","engineering-unit-scaling":{"pv-max-100-span":10,"pv-min-0-span":0,"cv-max-100-output":"auto","cv-min-0-output":"auto"},"gain-parameter":{"kp":0.3492,"ki":0.02543,"kd":0}}}]}]}},"InternalSWConfig":{"title":"Internal Software Configuration","type":"object","required":["alarm-no-data-rcv-threshold-sec","temperature-unit","length-unit"],"properties":{"alarm-no-data-rcv-threshold-sec":{"type":"number","minimum":0},"temperature-unit":{"type":"string","enum":["°C","°F"]},"length-unit":{"type":"string","enum":["m","ft"]}}},"Group":{"title":"Group","description":"Object with group details.","required":["name","average-basin-depth","cu"],"type":"object","minItems":1,"maxItems":4,"properties":{"name":{"type":"string"},"average-basin-depth":{"type":"number"},"cu":{"$ref":"#/components/schemas/CU"}},"example":{"name":"group-a","average-basin-depth":10,"cu":[{"name":"cu-a-1","nh4-setpoint":2,"nh4-deadband":1,"nh4-control":1,"allowable-nh4-variance":25,"min-do-setpoint":0,"max-do-setpoint":10,"fixed-do-setpoint":5,"fixed-do-concentration":3,"pid-configuration":{"type":"rockswell-pide","equation-type":"independent","engineering-unit-scaling":{"pv-max-100-span":10,"pv-min-0-span":0,"cv-max-100-output":"auto","cv-min-0-output":"auto"},"gain-parameter":{"kp":0.3492,"ki":0.02543,"kd":0}}}]}},"CU":{"title":"Control Unit","description":"Object with CU details.","required":["name","nh4-setpoint","nh4-deadband","nh4-control","allowable-nh4-variance","min-do-setpoint","max-do-setpoint","fixed-do-setpoint","fixed-do-concentration","pid-configuration"],"type":"object","minItems":1,"maxItems":12,"properties":{"name":{"type":"string"},"nh4-setpoint":{"type":"number"},"nh4-deadband":{"type":"number"},"nh4-control":{"type":"number"},"allowable-nh4-variance":{"type":"number"},"min-do-setpoint":{"type":"number"},"max-do-setpoint":{"type":"number"},"fixed-do-setpoint":{"type":"number"},"fixed-do-concentration":{"type":"number"},"pid-configuration":{"$ref":"#/components/schemas/PIDConfiguration"}},"example":{"name":"cu-a-1","nh4-setpoint":2,"nh4-deadband":1,"nh4-control":1,"allowable-nh4-variance":25,"min-do-setpoint":0,"max-do-setpoint":10,"fixed-do-setpoint":5,"fixed-do-concentration":3,"pid-configuration":{"type":"rockswell-pide","equation-type":"independent","engineering-unit-scaling":{"pv-max-100-span":10,"pv-min-0-span":0,"cv-max-100-output":"auto","cv-min-0-output":"auto"},"gain-parameter":{"kp":0.3492,"ki":0.02543,"kd":0}}}},"PIDConfiguration":{"title":"PID Configuration","required":["type","equation-type","engineering-unit-scaling","gain-parameter"],"type":"object","properties":{"type":{"type":"string"},"equation-type":{"type":"string"},"engineering-unit-scaling":{"$ref":"#/components/schemas/EngineeringUnitScaling"},"gain-parameter":{"$ref":"#/components/schemas/GainParameter"}},"example":{"type":"rockswell-pide","equation-type":"independent","engineering-unit-scaling":{"pv-max-100-span":10,"pv-min-0-span":0,"cv-max-100-output":"auto","cv-min-0-output":"auto"},"gain-parameter":{"kp":0.3492,"ki":0.02543,"kd":0}}},"EngineeringUnitScaling":{"title":"Engineering Unit Scaling","required":["pv-max-100-span","pv-min-0-span","cv-max-100-output","cv-min-0-output"],"type":"object","properties":{"pv-max-100-span":{"oneOf":[{"type":"number"},{"type":"string"}]},"pv-min-0-span":{"oneOf":[{"type":"number"},{"type":"string"}]},"cv-max-100-output":{"oneOf":[{"type":"number"},{"type":"string"}]},"cv-min-0-output":{"oneOf":[{"type":"number"},{"type":"string"}]}},"example":{"pv-max-100-span":10,"pv-min-0-span":0,"cv-max-100-output":"auto","cv-min-0-output":"auto"}},"GainParameter":{"title":"Gain Parameter","required":["kp","ki","kd"],"type":"object","properties":{"kp":{"type":"number"},"ki":{"type":"number"},"kd":{"type":"number"}},"example":{"kp":0.3492,"ki":0.02543,"kd":0}},"InputMeasuredParameters":{"title":"Measured Parameters","required":["tags"],"type":"object","properties":{"tags":{"$ref":"#/components/schemas/MeasuredValueTags"}},"example":{"tags":{"measured-nh4":{"value":30,"status":"signal:ok"},"measured-temperature":{"value":3,"status":"signal:ok"},"measured-airflow":{"value":52,"status":"signal:ok"},"measured-do":{"value":10,"status":"signal:ok"}}}},"MeasuredValueTags":{"title":"Measured Value Tags","required":["measured-nh4","measured-temperature","measured-airflow","measured-do"],"type":"object","properties":{"measured-nh4":{"$ref":"#/components/schemas/MeasuredNH4"},"measured-temperature":{"$ref":"#/components/schemas/MeasuredTemperature"},"measured-airflow":{"$ref":"#/components/schemas/MeasuredAirflow"},"measured-do":{"$ref":"#/components/schemas/MeasuredDO"}},"example":{"measured-nh4":{"value":30,"status":"signal:ok"},"measured-temperature":{"value":3,"status":"signal:ok"},"measured-airflow":{"value":52,"status":"signal:ok"},"measured-do":{"value":10,"status":"signal:ok"}}},"MeasuredNH4":{"title":"Measured NH4","required":["value","status"],"type":"object","properties":{"value":{"type":"number"},"status":{"type":"string"}},"example":{"value":30,"status":"signal:ok"}},"MeasuredTemperature":{"title":"Measured Temperature","required":["value","status"],"type":"object","properties":{"value":{"type":"number"},"status":{"type":"string"}},"example":{"value":3,"status":"signal:ok"}},"MeasuredAirflow":{"title":"Measured Airflow","required":["value","status"],"type":"object","properties":{"value":{"type":"number"},"status":{"type":"string"}},"example":{"value":52,"status":"signal:ok"}},"MeasuredDO":{"title":"Measured DO","required":["value","status"],"type":"object","properties":{"value":{"type":"number"},"status":{"type":"string"}},"example":{"value":10,"status":"signal:ok"}},"InputConfigParams":{"title":"Input Configuration Parameters","required":["name","nh4-setpoint","nh4-control","kp","kd","ki","min-do-setpoint","max-do-setpoint","fixed-do-setpoint"],"type":"object","properties":{"name":{"type":"string"},"nh4-setpoint":{"type":"number"},"nh4-control":{"type":"number"},"kp":{"type":"number"},"kd":{"type":"number"},"ki":{"type":"number"},"min-do-setpoint":{"type":"number"},"max-do-setpoint":{"type":"number"},"fixed-do-setpoint":{"type":"number"}},"example":{"nh4-setpoint":2,"nh4-control":1,"pid-kp":0.3492,"pid-kd":0,"pid-ki":0.02543,"min-do-setpoint":0,"max-do-setpoint":10,"fixed-do-setpoint":5}},"InternalCalculations":{"title":"Internal Calculations","required":["raw-pid-output","cv-max-100-output","cv-min-0-output"],"type":"object","properties":{"raw-pid-output":{"type":"number"},"cv-max-100-output":{"type":"string"},"cv-min-0-output":{"type":"string"}},"example":{"raw-pid-output":0.5,"cv-max-100-output":"auto","cv-min-0-output":"auto"}},"OutputParameters":{"title":"Output Parameters","required":["do-setpoint"],"type":"object","properties":{"do-setpoint":{"type":"number"}},"example":{"do-setpoint":1.0}},"AlarmNH4":{"title":"Output NH4 Alarm","type":"boolean","example":0},"AlarmTemperature":{"title":"Output Temperature Alarm","type":"boolean","example":0},"AlarmAirflow":{"title":"Output Airflow Alarm","type":"boolean","example":0},"AlarmDO":{"title":"Output DO Alarm","type":"boolean","example":0},"OutputAlarmTags":{"title":"Output Alarms","required":["alarm-nh4","alarm-temperature","alarm-airflow","alarm-DO"],"type":"object","properties":{"alarm-nh4":{"$ref":"#/components/schemas/AlarmNH4"},"alarm-temperature":{"$ref":"#/components/schemas/AlarmTemperature"},"alarm-airflow":{"$ref":"#/components/schemas/AlarmAirflow"},"alarm-DO":{"$ref":"#/components/schemas/AlarmDO"}}}},"parameters":{"name":{"name":"name","in":"header","required":true,"description":"Name of site or project.","schema":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[^;<>~`=()\\\"]*$","example":"Muncie, IN"}},"UID":{"name":"UID","in":"header","required":true,"description":"ID.","schema":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[^;<>~`=()\\\"]*$","example":"14-8231A"}},"CU_ID":{"name":"CU-ID","in":"path","required":true,"description":"CU identifier.","schema":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[^;<>~`=()\\\"]*$","example":"cu-a-1"}}},"responses":{"SuccessPost":{"description":"Successfully executed request."},"SuccessGet":{"description":"Successful request."},"BadRequest":{"description":"Bad request.","headers":{}},"AuthError":{"description":"Authentication error.","headers":{}},"ServerError":{"description":"Internal server error.","headers":{}}}},"tags":[{"name":"ABAC Configuration"},{"name":"ABAC Management"},{"name":"Control Units (CU)"}]}