Introducing INDOOR ANALYTICS, a REST service integrating HVAC engineering libraries: Hvac|Engine for the physics of humid air and thermodynamic processes and Unitility Spring module for physical quantity types and conversion and automatic serialization / deserialization in web components.
This service is dedicated to HVAC and Mechanical engineers, providing accurate calculations of air properties with humidity
content (Psychrometrics) and thermodynamic processes within the typical parameters scope for HVAC industry applications.
This is not "yet another psychrometrics calculator." The entire engineering library ecosystem I have created and utilized within this project is the result of years of development. Every temperature-dependent property is calculated based on equations available in standards, literature, or formulas derived by myself - not assumed as constant. Core libraries used in this project were developed also based on industry-recognized standards such as ASHRAE Fundamentals, ensuring precise and accurate results for applications where accuracy is paramount.
IMPORTANT: This repository is created for presentation purposes; it has a reduced scope intended to present the architecture and application design. A more advanced version of this application is being developed independently in a private repository for commercialization at a later stage.
AUTHOR: Piotr Jazdzyk, MSc Eng
LINKEDIN: https://www.linkedin.com/in/pjazdzyk
- Tech & dependencies
- Current version
- Architecture
- Functionality
- REST API
5.1 Api versioning
5.2 Physical properties of air
5.3 Heating process
5.4 Cooling process
5.5 Mixing process
5.6 Error response
5.7 SwaggerUI - Planned features
- Attribution and citation
- Acknowledgments
- Reference sources
Indoor-analytics is developed using the following technologies:
Core:
CI/CD:
Engineering:
Indoor-Analytics is designed as monolith in hexagonal architecture. Why hexagonal? For practice and training, and because I like it. Project is modular with separated API and CORE Maven modules. API module is composed of port interfaces to be implemented by Rest Controllers in CORE infrastructure. CORE also includes domain package, framework-less which can be easily extracted to any other project and framework.
Status: pre-release
Version: 0.0.1-alpha
At the current state of development, Indoor-Analytics is available offline and has not yet been published. For testing purposes, you can run it locally or in a Docker environment (simply launch 'build_image.bat') to build your image and start your container, exposing port 8090. A fully described SwaggerUI is provided for testing the REST API. The frontend is currently in preparation; once ready for testing, it will be published on a cloud provider along with the REST API. Current application capabilities can be described as below:
Dry air properties:
- relative humidity,
- kinematic and dynamic viscosity,
- thermal conductivity,
- specific enthalpy,
- specific heat,
- density,
- thermal diffusivity,
- Prandtl number,
Moist air properties:
- vapour saturation pressure,
- dew point temperature, wet bulb temperature,
- relative humidity,
- humidity ratio and maximum humidity ratio,
- kinematic and dynamic viscosity,
- thermal conductivity,
- specific enthalpy of humid air with water mist and ice mist components,
- specific heat,
- density,
- thermal diffusivity,
- Prandtl number,
Air heating:
- heating process for input heating power,
- heating process for target outlet air temperature,
- heating process for target outlet air relative humidity,
Air cooling:
- real cooling process with condensate discharge process for input cooling power,
- real cooling process with condensate discharge process for target outlet temperature,
- real cooling process with condensate discharge process for target outlet relative humidity,
Air stream mixing:
- simple mixing of two flows with humidity content,
- mixing of multiple flows with humidity content,
NOTE: It is planned that properties of both dry and humid air, along with a sample heating process, will be provided free of charge. However, access to the rest of the thermodynamic processes will be limited to a few uses per month for unregistered users. For registered users, additional usage will be available for a small fee. The REST API will be accessible to registered users with limited calls per month in the free-tier plan. A greater number of calls will incur a small fee to cover hosting and cloud provider expenses.
Indoor-analytics REST Api is dedicated for developers who would like to use capabilities of this service for developing their own HVAC software systems.
Versioning is not planned for simplicity and to avoid maintain of multiple apis and versions at the same time. However, if you will need it for any reason contact me.
Endpoints available for users are listed below. Parameters written in bold font are required, rest are optional. If not
specified - default values will be assumed:
- pressure: "101325.0Pa"
- relative-humidity: "0.0%"
- humidity ratio: "0.0kg/kg"
- imperial-units: "false"
Physical quantities must be specified as String type with value and associated quantity unit, for an example: "20.5C"
as 20.5 degrees of Celsius. For list of supported units, see the Unitility user guide.
Imperial-units determines the unit system used in the response. For the input in query param or request objects you can use
any unit you want from the supported units pool (both imperial and SI).
| LP | PATH | MTHD | QUERY PARAMS |
|---|---|---|---|
| 1 | /properties/dry-air |
GET | temperature pressure imperial-units |
| 2 | /properties/humid-air |
GET | temperature pressure humidity-ratio relative-humidity imperial-units |
| 3 | /properties/humid-air/from-wet-bulb |
GET | wet-bulb-temperature pressure relative-humidity imperial-units |
| 4 | /properties/humid-air/from-dew-point |
GET | dew-point-temperature pressure relative-humidity imperial-units |
| 5 | /properties/humid-air/from-enthalpy |
GET | specific-enthalpy pressure humidity-ratio imperial-units |
| 6 | /properties/humid-air/from-humidity |
GET | humidity-ratio relative-humidity pressure imperial-units |
Humid air response example in SI units: humid_air_response_SI.json
Dry air response example in imperial units: dry_air_response_imperial.json
Process of heating ias available in 3 different modes: from input power, for target temperature or for target relative humidity. More details on heating process can be found in HVAC|Engine library user guide, section 3.1 Heating.
| LP | PATH | MTHD | REQUEST BODY EXAMPLE | QUERY PARAMS |
|---|---|---|---|---|
| 1 | /processes/heating/input-power |
POST | request-body-example | imperial-units |
| 2 | /processes/heating/target-temperature |
POST | request-body-example | imperial-units |
| 3 | /processes/heating/target-relative-humidity |
POST | request-body-example | imperial-units |
As previously explained, setting query param imperial-units to true, will provide calculation result in a predefined set
of imperial units.
Heating response example in SI units: heating_response_SI.json
Heating response example in imperial units: heating_response_imperial.json
Process of cooling ias available in 3 different modes: from input power, for target temperature or for target relative humidity. More details on heating process can be found in HVAC|Engine library user guide, section 3.2 Cooling.
| LP | PATH | MTHD | REQUEST BODY EXAMPLE | QUERY PARAMS |
|---|---|---|---|---|
| 1 | /processes/cooling/input-power |
POST | request-body-example | imperial-units |
| 2 | /processes/cooling/target-temperature |
POST | request-body-example | imperial-units |
| 3 | /processes/cooling/target-relative-humidity |
POST | request-body-example | imperial-units |
Important: Please keep in mind that input cooling power mus be specified with negative sign. And consequently, cooling power
in the resulting response will also be provided as negative value. Response contains also detailed data on water condensate
discharge.
Cooling response example in SI units: cooling_response_SI.json
Cooling response example in imperial units: cooling_response_imperial.json
Process of mixing ias available in 2 different modes: mixing of two humid air flows and mixing of multiple humid air flows, up to 20. More details on heating process can be found in HVAC|Engine library user guide, section 3.3 Mixing.
| LP | PATH | MTHD | REQUEST BODY EXAMPLE | QUERY PARAMS |
|---|---|---|---|---|
| 1 | /processes/mixing |
POST | request-body-example | imperial-units |
| 2 | /processes/mixing/multiple |
POST | request-body-example | imperial-units |
Mixing response example in SI units: mixing_response_SI.json
Mixing response example in imperial units: mixing_response_imperial.json
In case of validation errors or domain exceptions response will result in HTTP code of 400 (Bad Request). InvalidResponse will be created and returned to user, with following structure:
{
"serviceName": "Indoor Analytics",
"cause": "UnitSystemParseException",
"message": "Unsupported unit symbol: {xyz}. Target class: TemperatureUnits",
"timestamp": "2024-02-10T14:39:11.8551038Z"
}Exception stack trace should never be returned to the user. If this happens, please let me know as soon as possible.
Swagger url will be provided here after first version of service will be uploaded to cloud provider for testing.
- steam humidification process,
- water spray humidification process,
- heat recovery process,
- process execution engine - so you could send a process list and engine will execute one after another, taking output air of the previous process as an input to another process, to simulate multi-stage change of air state as in real HVAC device.
- tables generator of physical properties in CSV or EXCEL,
- GUI to make engineers life easier,
- User registration, payment gate
Is there any feature you urgently need for your engineering application? Let me know what is needed and I see what I can do.
Please be informed that any reference to this project must be appropriately cited to include the author's attribution. Additionally, it should be noted that while samples may have been shared publicly for educational purposes, the project as a whole is designated for commercial utilization. Unauthorized commercial usage is strictly prohibited. All rights are reserved by the author.
Tech shield with version tag for manual adjustment (you can indicate which version you actually use):
[](https://github.com/pjazdzyk/indoor-analytics)I extend my heartfelt gratitude to the Silesian University of Technology for imparting
invaluable knowledge to me.
In the JavaDoc, you'll find linked references to specific papers and technical literature listed below.
- [1] - ASHRAE FUNDAMENTALS 2002, CHAPTER 6 "Psychrometrics"
- [2] - Buck, Arden L. "New Equations for Computing Vapour Pressure and Enhancement Factor". Journal of Applied Meteorology and Climatology (December 1981).
- [3] - Buck Research Instruments L.L.C. "MODEL CR-1A HYGROMETER WITH AUTO FILL OPERATING MANUAL" (May 2012).
- [4] - Morvay Z.K, Gvozdenac D.D. "Fundamentals for analysis and calculation of energy and environmental performance". Applied Industrial Energy And Environmental Management.
- [5] - Lipska B. "Projektowanie Wentylacji i Klimatyzacji. Podstawy uzdatniania powietrza" Wydawnictwo Politechniki Śląskiej (Gliwice 2014).
- [6] - https://www.engineeringtoolbox.com
- [7] - Stull R. "Wet-Bulb Temperature from Relative Humidity and Air Temperature". Manuscript received 14 July 2011, in final form 28 August 2011
- [8] - Tsilingiris P.T "Thermophysical and transport properties of humid air at temperature range between 0 and 100oC". Elsevier, Science Direct (September 2007)
- [9] - E.W. Lemmon, R.T. Jacobsen, S.G. Penoncello, D. Friend. Thermodynamic Properties of Air and Mixtures of Nitrogen, Argon, and Oxygen from 60 to 2000 K at Pressures to 2000 MPa. J. Phys. Chem. Ref. Data, Vol. 29, No. 3, (2000)
- [11] - F.E. Jones, G.L. Harris. ITS-90 Density of water formulation for volumetric standards' calibration. Journal of Research of the National Institute of Standards and Technology (1992)
- [12] - Water specific heat tables: https://www.engineeringtoolbox.com/specific-heat-capacity-water-d_660.html