{"id":18688465,"url":"https://github.com/mycontroller-org/esphome_api","last_synced_at":"2025-04-12T05:36:11.172Z","repository":{"id":37958675,"uuid":"369044569","full_name":"mycontroller-org/esphome_api","owner":"mycontroller-org","description":"ESPHome API for GoLang","archived":false,"fork":false,"pushed_at":"2024-09-09T02:50:39.000Z","size":187,"stargazers_count":13,"open_issues_count":0,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T01:01:48.215Z","etag":null,"topics":["esphome","iot"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mycontroller-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2021-05-20T01:24:30.000Z","updated_at":"2025-03-14T09:08:51.000Z","dependencies_parsed_at":"2024-09-09T03:51:18.900Z","dependency_job_id":"1ac7f269-603e-47cc-8a9e-cd7af0362519","html_url":"https://github.com/mycontroller-org/esphome_api","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mycontroller-org%2Fesphome_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mycontroller-org%2Fesphome_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mycontroller-org%2Fesphome_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mycontroller-org%2Fesphome_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mycontroller-org","download_url":"https://codeload.github.com/mycontroller-org/esphome_api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248524421,"owners_count":21118610,"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":["esphome","iot"],"created_at":"2024-11-07T10:36:57.270Z","updated_at":"2025-04-12T05:36:11.084Z","avatar_url":"https://github.com/mycontroller-org.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# esphome_api\n\nA Go library to manage [ESPHome](https://esphome.io/) devices.\n\nThis Go library provides a client implementation for interacting with ESPHome\ndevices using the native ESPHome API. It enables developers to control and\nmonitor ESPHome devices programmatically from Go applications. The library\noffers functionalities for establishing connections, authenticating, sending\ncommands, subscribing to state updates, and receiving device information.\n\n## Installation\n\nTo install the `esphome_api` library, use the following command:\n\n```bash\ngo build -o esphome ./cli/main.go\n```\n\n## Usage\n\n### 1. Import the Library\n\n```go\nimport (\n        \"fmt\"\n        \"log\"\n        \"time\"\n\n        \"github.com/mycontroller-org/esphome_api/pkg/api\"\n        \"github.com/mycontroller-org/esphome_api/pkg/client\"\n        \"google.golang.org/protobuf/proto\"\n)\n```\n\n### 2. Create a Client\n\n```go\n// Replace with your ESPHome device's address and encryption key (if applicable)\naddress := \"esphome.local:6053\"\nencryptionKey := \"YOUR_ENCRYPTION_KEY\"\n\n// Create a new ESPHome API client\nclient, err := client.GetClient(\"my-client-id\", address, encryptionKey, 10*time.Second, handleFunc)\nif err != nil {\n        log.Fatalln(err)\n}\ndefer client.Close()\n```\n\n### 3. Connect and Authenticate (if required)\n\n```go\n// If your device requires authentication, log in with the password\npassword := \"YOUR_PASSWORD\"\nif err := client.Login(password); err != nil {\n        log.Fatalln(err)\n}\n```\n\n### 4. Send Commands and Receive State Updates\n\n```go\n// Example: Subscribe to state updates\nif err := client.SubscribeStates(); err != nil {\n        log.Fatalln(err)\n}\n\n// Example: Send a command to a light entity\nlightKey := uint32(12) // Replace with the key of your light entity\nif err := client.Send(\u0026api.LightCommandRequest{\n        Key:   lightKey,\n        State: true, // Turn the light on\n}); err != nil {\n        log.Fatalln(err)\n}\n```\n\n### 5. Handle Incoming Messages\n\n```go\n// Define a handler function to process incoming messages\nfunc handleFunc(msg proto.Message) {\n        switch msg := msg.(type) {\n        case *api.LightStateResponse:\n                fmt.Printf(\"Light state update: Key=%d, State=%t\\n\", msg.Key, msg.State)\n\n        case *api.BinarySensorStateResponse:\n                fmt.Printf(\"Binary sensor state update: Key=%d, State=%t\\n\", msg.Key, msg.State)\n\n        // Handle other message types as needed\n        default:\n                fmt.Printf(\"Received message of type: %T\\n\", msg)\n        }\n}\n```\n\n## Configuration Example\n\nThe following is a complete configuration example for the `esphomectl` CLI\ntool, which utilizes the `esphome_api` library:\n\n**File: `~/.esphomectl.yaml`**\n\n```yaml\nactive: esphome.local:6053\ndevices:\n    - address: esphome.local:6053\n      password: BASE64/YOUR_ENCODED_PASSWORD\n      encryptionKey: YOUR_ENCRYPTION_KEY\n      timeout: 10s\n      info:\n          name: My ESPHome Device\n          model: NodeMCU\n          macAddress: AC:BC:32:89:0E:A9\n          esphomeVersion: \"1.15.0\"\n          compilationTime: \"2023-10-26T10:00:00\"\n          usesPassword: true\n          hasDeepSleep: false\n          statusOn: 2023-10-26T12:00:00+05:30\n```\n\n**Note:** The password is encoded in Base64 format. You can encode your password using the following command:\n\n```bash\necho -n \"YOUR_PASSWORD\" | base64\n```\n\n## Examples\n\nThe [examples](/examples/) directory contains various examples demonstrating the usage of the `esphome_api` library for different purposes, such as:\n\n-   **camera:** Capture images from an ESPHome camera.\n-   **device_info:** Retrieve device information from an ESPHome device.\n-   **tail_logs:** Subscribe to and display logs from an ESPHome device.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmycontroller-org%2Fesphome_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmycontroller-org%2Fesphome_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmycontroller-org%2Fesphome_api/lists"}