{"id":15007092,"url":"https://github.com/bbartling/easy-aso","last_synced_at":"2025-10-15T09:23:18.884Z","repository":{"id":222328010,"uuid":"756910013","full_name":"bbartling/easy-aso","owner":"bbartling","description":"This is a framework for Automated Supervisory Optimization (ASO) with built-in BACnet methods.","archived":false,"fork":false,"pushed_at":"2024-10-22T15:55:07.000Z","size":6947,"stargazers_count":13,"open_issues_count":6,"forks_count":0,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2025-02-02T08:11:16.384Z","etag":null,"topics":["ashrae","autonomous","autonomous-systems","bacnet","bacnet-client","bacnet-ip","building-automation","hvac","hvac-control","linux","linux-app","optimization","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbartling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-13T14:48:09.000Z","updated_at":"2024-12-02T14:05:06.000Z","dependencies_parsed_at":"2024-02-13T16:48:28.497Z","dependency_job_id":"64540d4c-04f6-4449-aa2b-2da4878c7e15","html_url":"https://github.com/bbartling/easy-aso","commit_stats":null,"previous_names":["bbartling/freebas"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbartling%2Feasy-aso","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbartling%2Feasy-aso/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbartling%2Feasy-aso/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbartling%2Feasy-aso/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbartling","download_url":"https://codeload.github.com/bbartling/easy-aso/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238955875,"owners_count":19558456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ashrae","autonomous","autonomous-systems","bacnet","bacnet-client","bacnet-ip","building-automation","hvac","hvac-control","linux","linux-app","optimization","python"],"created_at":"2024-09-24T19:03:21.093Z","updated_at":"2025-10-15T09:23:18.870Z","avatar_url":"https://github.com/bbartling.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Easy ASO 🤖🕹️⚡\n\nWelcome to Easy ASO, the ultimate command tool for Automated Supervisory Optimization (ASO) of BACnet systems in EMIS applications. \nBuilt on a seamless Python asyncio framework, Easy ASO comes with a fully integrated BACnet asyncio stack for convenience, making BACnet—the default protocol in the HVAC industry—effortless to use. \nOther protocols can also be implemented during the development process, offering flexibility and extensibility.\n\n\n## The Skeleton of ASO 🦾🎮🏢\nControl BACnet systems on a simple `on_start`, `on_step`, and `on_stop` structure:\n\n```python\nclass CustomHvacAso(EasyASO):\n    async def on_start(self):\n        print(\"Custom ASO is deploying! Lets do something!\")\n\n    async def on_step(self):\n\t# BACnet read request\n        sensor = await self.bacnet_read(\"192.168.0.122\", \"analog-input,1\")\n\n        # Custom step logic - BACnet write request\n        override_valve = sensor + 5.0\n        await self.bacnet_write(\"192.168.0.122\", \"analog-output,2\", override_valve)\n\n        print(\"Executing step actions... The system is being optimized!\")\n        await asyncio.sleep(60)\n\n    async def on_stop(self):\n        # Custom stop logic - BACnet release request\n        await self.bacnet_write(\"192.168.0.122\", \"analog-output,2\", 'null')\n        print(\"Executing stop actions... The system is released back to normal!\")\n```\n\n**⚠️👷🚧🏗️ WARNING** - This repo is new and under construction, so some features are not fully developed yet but stay tuned!  \n\n## BACnet Services Supported 💼\n\n- [x] Read\n- [x] Write\n- [ ] Read Multiple\n- [ ] Write Multiple\n- [ ] Whois\n- [ ] Read Priority Array\n- [ ] Anything else? 🤔\n\n## Exploring Remote BACnet Sites with `tester.py` 🔍\n\nThe `tester.py` script, located in the scripts directory, provides a utility for exploring a remote BACnet site via the bacpypes3 console.  \nThis tool is designed to assist in the setup and configuration of the `easy-aso` project, streamlining the integration process.  \n\nFor detailed information and instructions on using the `Tester.py` script, please refer to the `setup_scripts` directory [README](https://github.com/bbartling/easy-aso/tree/develop/setup_scripts) for more information.\n\n- [x] Read Property (`read_property`)\n- [x] Write Property (`write_property`)\n- [x] Read Property Multiple (`read_property_multiple`)\n- [x] Read Priority Array (`read_property` with `priority-array`)\n- [x] Device Discovery (`who-is`)\n- [x] Object Discovery (`who-has`)\n- [x] Read All Points (`do_point_discovery`)\n- [x] Router Discovery (`who_is_router_to_network`)\n\n## Writeups 💡\n\nWhy can't a BAS be free?  \n* https://www.linkedin.com/pulse/can-building-automation-free-ben-bartling-mtvwc/\n\nCan ASO be easy?  \n* https://www.linkedin.com/pulse/can-aso-easy-ben-bartling-eftlc/?trackingId=deyXF1fr00wbx2sLt0mSDQ%3D%3D\n\nCan ASO be used to aid Fault Detection and Diagnostics (FDD)?\n* https://www.linkedin.com/pulse/can-aso-used-aid-fault-detection-diagnostics-fdd-ben-bartling-mb8lc/\n\n## In Progress 🛠️\n- [x] Overhaul app code with bacpypes3\n- [x] Test basic functionality with a fake BACnet app\n- [x] Create unit tests for BACnet server and client with docker containers\n- [ ] Publish the project as a Python library on PyPI\n\n## Future 🚀\n- Make tutorials for ASO based on an [LBNL reference](https://transformingbuildingcontrols.lbl.gov/) for:\n  - Electrical load shed example\n  - Classic BAS Supervisory control to share data globally via BACnet priority\n  - AHU duct static pressure and temperature setpoint trim and respond (T\u0026R)\n  - AHU demand control ventilation based on G36 and ventilation calcs\n  - VAV box system occupied-standby with occupancy integration to HVAC\n  - Overnight building flush\n  - Overnight BACnet override release bot\n  - Heat pump system cold weather staggered start for electrical power management\n  - Electrical load shift\n  - Identify rogue zones in an HVAC system\n  - Self-commissioning AHU system bots\n  - How to run Python scripts long-term in a Docker container\n\n\n## Schematics 🔧:\n\n`easy-aso` is designed to be a fully discoverable BACnet server that can seamlessly integrate into any existing building automation system (BAS). \nThe core of this integration relies on a discoverable BACnet `binary-value` point named `optimization-enabled`. \nThis point allows building operators to maintain full control over the Automated Systems Optimization (ASO) processes. \nIf, at any time, an operator needs to disable an ASO instance, the `optimization-enabled` point provides a direct means to turn off the optimization for any part of the HVAC system. \nThis feature is crucial for maintaining operational flexibility and preventing unwanted system behavior. \n\nIn the event of an issue, such as undesired system behavior or an operator decision to revert control, this BACnet point can be incorporated directly into the logic of `easy-aso`. \nThis ensures that any overrides the script may have applied are released safely and promptly. \nFor a clearer understanding of how this callback is integrated into the ASO design of `easy-aso`, refer to the example Python files that demonstrate its practical implementation.\n\nBy default, `easy-aso` is deployed within a secure, internal network (behind a firewall), where it can operate efficiently with existing IoT.  \n![Schematic of Python script deployment](https://raw.githubusercontent.com/bbartling/easy-aso/develop/new_building.png)\n\nHowever, `easy-aso` is also fully compatible with traditional operational technology (OT) systems that do not have internet access, supporting more traditional building environments that rely solely on local control.  \n![Schematic of Python script deployment traditional](https://raw.githubusercontent.com/bbartling/easy-aso/develop/traditional_building.png)\n\nFlexibility is at the heart of `easy-aso`. In a Python asyncio environment, it is easy to extend and build around, enabling the potential for cloud-based integrations. \nThis presents an intriguing solution for a Master Systems Integrator (MSI) looking to completely revamp their existing edge environment and start fresh with a modernized approach.\n![Schematic of Python script deployment as iot](https://raw.githubusercontent.com/bbartling/easy-aso/develop/easy_aso_as_iot.png)\n\n## Getting Started with easy-aso 🚀\n\nFollow the instructions below to set up the `easy-aso` project on your local Linux machine.  \nUntil the project is available on PyPI, you can install it locally by following these steps.  \n\nAfter the scripts are thoroughly tested and commissioned, they can be run long-term in a Docker container.  \nSee the sub-directory `docker_setup` for more information.\n\n### Step 1: Clone the Repository 📂\nFirst, clone the `easy-aso` repository to your local machine:\n```bash\ngit clone https://github.com/bbartling/easy-aso\n```\n\n### Step 2: Install the Package Locally 🖥️\nNavigate into the project directory and install it using `pip`. This will make the `easy-aso` package available in your Python environment.\n```bash\ncd easy-aso\npip install .\n```\n\n### Step 3: Try out a few sample Py files 🧪\n* Check out the `examples` directory for [sample applications](https://github.com/bbartling/easy-aso/tree/develop/examples).\n* Review the `easy-aso` API documentation [README](https://github.com/bbartling/easy-aso/tree/develop/tests) for method call specifics when creating apps.\n* Run a [fake BACnet app](https://github.com/bbartling/easy-aso/tree/develop/setup_scripts) and try out code such as `tester.py` in a sandbox environment. Note that both require two Linux devices — I use an Ubuntu VM and a Raspberry Pi for the fake BACnet device, which acts as another BACnet device on the LAN.\n\n## Cybersecurity Disclaimer 🔐\n\nEasy ASO is designed as an operations technology (OT) application with no built-in cloud connectivity, but it is fully capable of anything programmed in Python. Any implementation of cloud connectivity for this app is the responsibility of the user. It is crucial to understand the cybersecurity implications of sending bi-directional signals to building systems.\n\n**Security Best Practices**:  \n- Ensure the safety of your systems by following recommended cybersecurity best practices, including network, VPN, and VM access hardening, secure configurations, and routine security checks. 🛡️\n- Work closely with the IT team when enabling cloud connectivity to ensure it complies with your organization's security policies. 🔒\n- Involve IT in all stages of the project and address any issues related to the implementation of easy-aso.  \n- Safeguard building control systems by utilizing access controls, encryption, and secure communication protocols to prevent unauthorized access. 🔐\n- Act in the capacity of an ICS security specialist on behalf of your client, and promptly report any vulnerabilities or issues you discover.  \n- Develop an incident response plan to ensure the project is prepared for any potential security breaches, enabling swift and effective action from the incident response team should an issue arise during the implementation of easy-aso. 🔧\n\n## Contributing 🛠️\n\nPRs, git issues, and discussions are highly encouraged!  \nPlease reference the [README](https://github.com/bbartling/easy-aso/tree/develop/tests) for more information.\n\n## License 📄\n\n【MIT License】  \nCopyright 2024 Ben Bartling\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbartling%2Feasy-aso","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbartling%2Feasy-aso","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbartling%2Feasy-aso/lists"}