{"id":18949055,"url":"https://github.com/bbartling/ot-lan-rest-server","last_synced_at":"2025-04-15T23:31:06.840Z","repository":{"id":227518288,"uuid":"767695645","full_name":"bbartling/ot-lan-rest-server","owner":"bbartling","description":"Exploration on making a Python based BACnet gRPC server with bacpypes3 to be used as a microservice","archived":false,"fork":false,"pushed_at":"2024-10-15T13:03:04.000Z","size":481,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2024-11-08T13:15:30.173Z","etag":null,"topics":["bacnet","bacnet-ip","building-automation","hvac","hvac-iot","iot","server"],"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-03-05T18:29:09.000Z","updated_at":"2024-10-16T19:47:54.000Z","dependencies_parsed_at":"2024-03-13T18:56:45.560Z","dependency_job_id":"8fa9176c-19ba-4a30-9cbb-1d03f035d389","html_url":"https://github.com/bbartling/ot-lan-rest-server","commit_stats":null,"previous_names":["bbartling/bacnetrpcserverexperiments","bbartling/bacpypes3rcpserver","bbartling/ot-lan-rest-server"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbartling%2Fot-lan-rest-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbartling%2Fot-lan-rest-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbartling%2Fot-lan-rest-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbartling%2Fot-lan-rest-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbartling","download_url":"https://codeload.github.com/bbartling/ot-lan-rest-server/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223688647,"owners_count":17186299,"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":["bacnet","bacnet-ip","building-automation","hvac","hvac-iot","iot","server"],"created_at":"2024-11-08T13:15:33.843Z","updated_at":"2024-11-08T13:15:37.000Z","avatar_url":"https://github.com/bbartling.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ot-lan-rest-server\n\n\nThis is a dedicated rest API or RPC-like Linux web app server that can interact with control systems on a local operations technology network (LAN) or intranet inside a building. Supports tls and Basic Auth through the Python Fast API web framework and all BACnet features are handled by the bacpypes3 Python BACnet stack. FastAPI supports Swagger UI out-of-the-box (see tutorials below), which this app fully leverages. This feature can be incredibly useful for poking and prodding an unknown BACnet system within a building. For convenience, IoT edge devices can request data from the app at regular intervals via REST API without the need to delve into any BACnet stack setup.\n\n## Setup Python packages use virtual environment if desired.\n```bash\npython -m pip install bacpypes3 ifaddr fastapi uvicorn\n\n```\n\n#### Example args to run app on http with setting custom `host` and `port`.\n```bash\npython app/main.py --host 0.0.0.0 --port 8080\n```\n\n#### Example args to run app on http with setting Basic Auth username for the app of `myusername` and password of `mypassword`. Default app username and pass is `admin` and `secret` which should be changed for security purposes.\n\n```bash\npython app/main.py --basic-auth-username=myusername --basic-auth-password=mypassword\n```\n\nIf running your app on **http without the tls arg** log into swagger UI on `http` something like:\n* http://xxx.xxx.xxx.xxx:8000/docs\n\nElse if running your app on **https with tls arg** log into swagger UI on `https` something like:\n* https://xxx.xxx.xxx.xxx:8000/docs\n\n## Optional TLS support\nTo ecprypte http web app TCP traffic only, not BACnet which runs on UDP... Generate certs with running the bash script inside the `scripts` directory. Step through the Q/A process for generating the self signed certs about inputing country code, organization, and contact info.\n\n```bash\n./scripts/generate_certs.sh\n```\n\n#### Example arg to run app with transport layer security (TLS)\n* Step through the Q/A to setup your certs with openssl however you want.\n```bash\npython app/main.py --tls\n```\n\n\n\u003cdetails\u003e\n  \u003csummary\u003eTutorial for the Fast API Swagger UI\u003c/summary\u003e\n\nIf you are using credentials on your app with args like `--basic-auth-username=myusername --basic-auth-password=mypassword` on the command line to start the app, proceed to then enter your credentials in green `Authorize` button in the Swagger UI upper right corner else skip this step.\n\nWhen the app starts successfully dial into the built in Swagger UI feature of Fast API which can be used to test various BACnet commands.\n\n![Alt text](/images/swagger_home.JPG)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWhois Tutorial via Swagger UI\u003c/summary\u003e\n\nTest if the BACnet device responds to a `whois` for the devices BACnet instance ID.\n![Alt text](/images/who_is.JPG)\n\nIf successful should return:\n```bash\n[\n  {\n    \"i-am-device-identifier\": \"device,201201\",\n    \"max-apdu-length-accepted\": 286,\n    \"segmentation-supported\": \"no-segmentation\",\n    \"vendor-id\": 11\n  }\n]\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eRead Prop Tutorial via Swagger UI\u003c/summary\u003e\n\nRead request to device `201201 analog-value 301 present-value` which is a temperature sensor.\n\n![Alt text](/images/read_prop_pv1.JPG)\n\nIf successful should return:\n```bash\n{\n  \"success\": true,\n  \"message\": \"BACnet read request successfully invoked\",\n  \"data\": {\n    \"device_instance\": 201201,\n    \"object_identifier\": \"analog-input,2\",\n    \"property_identifier\": \"present-value\",\n    \"read_result\": 69.42999267578125\n  }\n}\n\n```\n\nRead property of a different property_identifier which can be unique to the BACnet device. See bacpypes3 repo basetypes.py for more info:\nhttps://github.com/JoelBender/BACpypes3/blob/main/bacpypes3/basetypes.py\n\n![Alt text](/images/read_prop.JPG)\n\nIf successful should return:\n```bash\n{\n  \"success\": true,\n  \"message\": \"BACnet read request successfully invoked\",\n  \"data\": {\n    \"device_instance\": 201201,\n    \"object_identifier\": \"analog-input,2\",\n    \"property_identifier\": \"out-of-service\",\n    \"read_result\": false\n  }\n}\n\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWrite Prop Tutorial via Swagger UI\u003c/summary\u003e\n\nWrite request to device `201201 analog-value 301 present-value` for a value of `10` on BACnet priority `10`.\n![Alt text](/images/write_req1.JPG)\n\nIf successful should return:\n```bash\n{\n  \"success\": true,\n  \"message\": \"BACnet write request successfully invoked\",\n  \"data\": {\n    \"device_instance\": 201201,\n    \"object_identifier\": \"analog-value,301\",\n    \"property_identifier\": \"present-value\",\n    \"written_value\": 10,\n    \"priority\": 10\n  }\n}\n```\n\nRelease an override by passing in the value of `null`. \n\n![Alt text](/images/write_req2.JPG)\n\nIf successful should return:\n```bash\n{\n  \"success\": true,\n  \"message\": \"BACnet write request successfully invoked\",\n  \"data\": {\n    \"device_instance\": 201201,\n    \"object_identifier\": \"analog-value,301\",\n    \"property_identifier\": \"present-value\",\n    \"written_value\": \"null\",\n    \"priority\": 10\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eRead Multiple Tutorial via Swagger UI\u003c/summary\u003e\n\nA BACnet Read Multiple to device `201201` on a post request would look like this.\n![Alt text](/images/rpm.JPG)\n\nWith json data in the body with multiple `object_identifier` and `property_identifier`:\n```\n{\n  \"device_instance\": 201201,\n  \"requests\": [\n    {\n      \"object_identifier\": \"analog-input,2\",\n      \"property_identifier\": \"present-value\"\n    },\n    {\n      \"object_identifier\": \"analog-input,2\",\n      \"property_identifier\": \"units\"\n    },\n    {\n      \"object_identifier\": \"analog-input,2\",\n      \"property_identifier\": \"description\"\n    },\n    {\n      \"object_identifier\": \"analog-value,301\",\n      \"property_identifier\": \"present-value\"\n    },\n    {\n      \"object_identifier\": \"analog-input,301\",\n      \"property_identifier\": \"units\"\n    },\n    {\n      \"object_identifier\": \"analog-value,301\",\n      \"property_identifier\": \"description\"\n    }\n  ]\n}\n```\n\nIf successful should return this below. Note that is a property isnt defined inside your BACnet device it will\ncome back as `error` but if the property does exist it will return a `value`.\n```bash\n{\n  \"success\": true,\n  \"message\": \"BACnet rpm successfully invoked\",\n  \"data\": {\n    \"device_instance\": 201201,\n    \"requests\": [\n      {\n        \"object_identifier\": \"analog-input,2\",\n        \"property_identifier\": \"present-value\",\n        \"value\": \"67.7199935913086\"\n      },\n      {\n        \"object_identifier\": \"analog-input,2\",\n        \"property_identifier\": \"units\",\n        \"value\": \"degrees-fahrenheit\"\n      },\n      {\n        \"object_identifier\": \"analog-input,2\",\n        \"property_identifier\": \"description\",\n        \"error\": \"property, unknown-property\"\n      },\n      {\n        \"object_identifier\": \"analog-value,301\",\n        \"property_identifier\": \"present-value\",\n        \"value\": \"nan\"\n      },\n      {\n        \"object_identifier\": \"analog-input,301\",\n        \"property_identifier\": \"units\",\n        \"error\": \"object, unknown-object\"\n      },\n      {\n        \"object_identifier\": \"analog-value,301\",\n        \"property_identifier\": \"description\",\n        \"error\": \"property, unknown-property\"\n      }\n    ]\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eBACnet Whois across a range of instance ID's Tutorial via Swagger UI\u003c/summary\u003e\n\nA global BACnet `Whois` between range of instance ID's.\n![Alt text](/images/who_is_range.JPG)\n\nWith json data in the body:\n```\n{\n  \"start_instance\": 1,\n  \"end_instance\": 300000\n}\n```\n\n\nIf successful, the response will include known devices, such as the two on my test bench. Please note that this command is intended only for setup purposes of IoT or Building Automation Systems (BAS). It should not be used at short intervals, as it can cause significant disruptions on BACnet systems and potentially cause some devices to go offline. Use this command with caution. If it must be used regularly for security or device health checks, it should not be executed more frequently than once per hour. In BAS contracting, this command is primarily used during the setup phase to gather device configurations for a building automation system.\n```bash\n[\n  {\n    \"i-am-device-identifier\": \"device,201201\",\n    \"max-apdu-length-accepted\": 286,\n    \"segmentation-supported\": \"no-segmentation\",\n    \"vendor-id\": 11\n  },\n  {\n    \"i-am-device-identifier\": \"device,201202\",\n    \"max-apdu-length-accepted\": 286,\n    \"segmentation-supported\": \"no-segmentation\",\n    \"vendor-id\": 11\n  }\n]\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eDevice Point Discovery Tutorial via Swagger UI\u003c/summary\u003e\n\nTest for a BACnet point discovery process of a BACnet device by instance ID.\n![Alt text](/images/point_discovery.JPG)\n\nIf successful, the operation should return all the device objects or points as shown below. Please note that this process may take a while depending on the device, the number of configured points, and the network. Additionally, if the BACnet device supports a BACnet service called object-list, the operation will be faster. If object-list is not supported, the application will read one point at a time, resulting in a longer processing time. However, the response will remain consistent regardless of the method used.\n\n```bash\n{\n  \"success\": true,\n  \"message\": \"Point discovery successful\",\n  \"data\": {\n    \"device_instance_id\": 201201,\n    \"point_object_details\": [\n      {\n        \"identifier\": \"analog-input 1\",\n        \"description\": \"tempUoOne10k\"\n      },\n      {\n        \"identifier\": \"analog-input 2\",\n        \"description\": \"tempUoTwoBalco\"\n      },\n      {\n        \"identifier\": \"analog-input 3\",\n        \"description\": \"tempUoThreeBalco\"\n      },\n      {\n        \"identifier\": \"analog-input 17\",\n        \"description\": \"S-LK\"\n      },\n      {\n        \"identifier\": \"analog-value 806\",\n        \"description\": \"RmDiff\"\n      },\n      {\n        \"identifier\": \"analog-value 301\",\n        \"description\": \"Oat\"\n      },\n      {\n        \"identifier\": \"analog-value 302\",\n        \"description\": \"RmTmpSpt\"\n      },\n      {\n        \"identifier\": \"analog-value 300\",\n        \"description\": \"RmTmp\"\n      },\n      {\n        \"identifier\": \"binary-output 1\",\n        \"description\": \"UhCmd\"\n      },\n      {\n        \"identifier\": \"binary-value 806\",\n        \"description\": \"GlblHtgDsbl\"\n      },\n      {\n        \"identifier\": \"device 201201\",\n        \"description\": \"TEST1\"\n      },\n      {\n        \"identifier\": \"file 1\",\n        \"description\": \"Firmware\"\n      },\n      {\n        \"identifier\": \"file 32\",\n        \"description\": \"Application Database\"\n      },\n      {\n        \"identifier\": \"multi-state-value 10101\",\n        \"description\": \"tempUoOne10k:Type\"\n      },\n      {\n        \"identifier\": \"analog-value 10106\",\n        \"description\": \"tempUoOne10k:Filter\"\n      },\n      {\n        \"identifier\": \"analog-value 10107\",\n        \"description\": \"tempUoOne10k:Offset\"\n      },\n      {\n        \"identifier\": \"multi-state-value 10201\",\n        \"description\": \"tempUoTwoBalco:Type\"\n      },\n      {\n        \"identifier\": \"analog-value 10206\",\n        \"description\": \"tempUoTwoBalco:Filter\"\n      },\n      {\n        \"identifier\": \"analog-value 10207\",\n        \"description\": \"tempUoTwoBalco:Offset\"\n      },\n      {\n        \"identifier\": \"multi-state-value 10301\",\n        \"description\": \"tempUoThreeBalco:Type\"\n      },\n      {\n        \"identifier\": \"analog-value 10306\",\n        \"description\": \"tempUoThreeBalco:Filter\"\n      },\n      {\n        \"identifier\": \"analog-value 10307\",\n        \"description\": \"tempUoThreeBalco:Offset\"\n      },\n      {\n        \"identifier\": \"binary-value 12501\",\n        \"description\": \"UhCmd:Action\"\n      },\n      {\n        \"identifier\": \"analog-value 13313\",\n        \"description\": \"S-LK:TempCal\"\n      },\n      {\n        \"identifier\": \"analog-value 13332\",\n        \"description\": \"S-LK:OvrdTm\"\n      },\n      {\n        \"identifier\": \"binary-value 13353\",\n        \"description\": \"S-LK:PbOcc\"\n      },\n      {\n        \"identifier\": \"analog-value 13354\",\n        \"description\": \"S-LK:OvrTimer\"\n      }\n    ]\n  }\n}\n```\n\n\u003c/details\u003e\n\n\nProject goals:\n - [x] who-is request\n - [x] read property request\n - [x] write property request\n - [x] read multiple property request\n - [x] who-is across a range of instance ID's\n - [x] device point discovery\n - [ ] who-is router-to-network\n - [ ] read point proirity array\n - [ ] make a BACnet device toml config file\n - [x] create unit tests for Fast API Pydantic models\n - [x] add pydantic model validation for server requests\n - [ ] read range for BACnet devices that support trend log data\n - [ ] add ModBus support which would be used to read a utility meter only\n \n## License\nMIT License\n\nCopyright (c) 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\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\nADDITIONAL CYBERSECURITY NOTICE: Users are encouraged to apply the highest level of cybersecurity, OT, IoT, and IT measures when using this software. The authors and copyright holders disclaim any liability for cybersecurity breaches, mechanical equipment damage, financial damage, or loss of life arising from the use of the Software. Users assume full responsibility for ensuring the secure deployment and operation of the Software in their environments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbartling%2Fot-lan-rest-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbartling%2Fot-lan-rest-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbartling%2Fot-lan-rest-server/lists"}