homeassistant

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 15, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

README

Home Assistant API Client

This package provides a client for the Home Assistant API, which is used to interact with the Home Assistant home automation system.

References:

Documentation

Overview

homeassistant implements an API client for Home Assistant API https://developers.home-assistant.io/docs/api/rest/

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewTools

func NewTools(endPoint, apiKey string, opts ...client.ClientOpt) ([]tool.Tool, error)

NewTools returns Home Assistant tools for use with LLM agents.

Types

type CallResponse

type CallResponse struct {
	ChangedStates   []*State       `json:"changed_states"`
	ServiceResponse map[string]any `json:"service_response"`
}

CallResponse is returned when calling a service with return_response=true.

type CallServiceRequest

type CallServiceRequest struct {
	Domain  string         `json:"domain" jsonschema:"The service domain (e.g. light, switch, climate, media_player)."`
	Service string         `json:"service" jsonschema:"The service to call (e.g. turn_on, turn_off, toggle, set_temperature)."`
	Data    map[string]any `json:"data,omitempty" jsonschema:"Service data including entity_id and any service-specific fields."`
}

CallServiceRequest calls a Home Assistant service.

type Client

type Client struct {
	*client.Client
}

func New

func New(endPoint, apiKey string, opts ...client.ClientOpt) (*Client, error)

func (*Client) Call

func (c *Client) Call(ctx context.Context, domain, service string, serviceData map[string]any) ([]*State, error)

Call a service for an entity. The serviceData map is sent as the JSON request body and typically includes "entity_id" plus any service-specific fields. Returns a list of states that changed while the service was being executed.

func (*Client) CallWithResponse

func (c *Client) CallWithResponse(ctx context.Context, domain, service string, serviceData map[string]any) (*CallResponse, error)

CallWithResponse calls a service and returns both changed states and service response data. Use this for services that support returning response data (e.g. weather.get_forecasts).

func (*Client) Config

func (c *Client) Config(ctx context.Context) (*Config, error)

Config returns the current server configuration.

func (*Client) DeleteState

func (c *Client) DeleteState(ctx context.Context, entityId string) error

DeleteState removes an entity from Home Assistant.

func (*Client) Domains

func (c *Client) Domains(ctx context.Context) ([]*Domain, error)

Domains returns all domains and their associated service objects

func (*Client) Events

func (c *Client) Events(ctx context.Context) ([]Event, error)

Events returns all the events and number of listeners

func (*Client) FireEvent

func (c *Client) FireEvent(ctx context.Context, eventType string, eventData map[string]any) (string, error)

FireEvent fires an event with the given type. Optional event data can be passed as a map. Returns a confirmation message.

func (*Client) Health

func (c *Client) Health(ctx context.Context) (string, error)

Health returns "API Running" if the Home Assistant API is reachable

func (*Client) Services

func (c *Client) Services(ctx context.Context, domain string) ([]*Service, error)

Return callable services for a domain

func (*Client) SetState

func (c *Client) SetState(ctx context.Context, entityId, state string, attributes map[string]any) (*State, error)

SetState creates or updates the state of an entity. The state string is required; attributes is optional. Returns the resulting state object. Note: This sets the representation within Home Assistant — it does not communicate with the actual device. Use Call() to actuate a device.

func (*Client) State

func (c *Client) State(ctx context.Context, EntityId string) (*State, error)

State returns a state for a specific entity

func (*Client) States

func (c *Client) States(ctx context.Context) ([]*State, error)

States returns all the entities and their state

func (*Client) Template

func (c *Client) Template(ctx context.Context, template string) (string, error)

Template renders a Home Assistant Jinja2 template and returns the result as plain text. See https://www.home-assistant.io/docs/configuration/templating

type Config

type Config struct {
	Components    []string       `json:"components"`
	ConfigDir     string         `json:"config_dir"`
	Elevation     float64        `json:"elevation"`
	Latitude      float64        `json:"latitude"`
	Longitude     float64        `json:"longitude"`
	LocationName  string         `json:"location_name"`
	TimeZone      string         `json:"time_zone"`
	UnitSystem    map[string]any `json:"unit_system"`
	Version       string         `json:"version"`
	ExternalDirs  []string       `json:"whitelist_external_dirs,omitempty"`
	AllowlistDirs []string       `json:"allowlist_external_dirs,omitempty"`
	AllowlistURLs []string       `json:"allowlist_external_urls,omitempty"`
	Currency      string         `json:"currency,omitempty"`
	Country       string         `json:"country,omitempty"`
	Language      string         `json:"language,omitempty"`
	SafeMode      bool           `json:"safe_mode,omitempty"`
	State         string         `json:"state,omitempty"`
	InternalURL   string         `json:"internal_url,omitempty"`
	ExternalURL   string         `json:"external_url,omitempty"`
	RecoveryMode  bool           `json:"recovery_mode,omitempty"`
}

Config represents the Home Assistant server configuration.

func (Config) String

func (v Config) String() string

type Domain

type Domain struct {
	Domain   string              `json:"domain"`
	Services map[string]*Service `json:"services,omitempty"`
}

func (Domain) String

func (v Domain) String() string

type Event

type Event struct {
	Event     string `json:"event"`
	Listeners uint   `json:"listener_count"`
}

type Field

type Field struct {
	Required bool                `json:"required,omitempty"`
	Example  any                 `json:"example,omitempty"`
	Selector map[string]Selector `json:"selector,omitempty"`
}

func (Field) String

func (v Field) String() string

type FireEventRequest

type FireEventRequest struct {
	EventType string         `json:"event_type" jsonschema:"The event type to fire (e.g. my_custom_event)."`
	EventData map[string]any `json:"event_data,omitempty" jsonschema:"Optional data to include with the event."`
}

FireEventRequest fires a custom event on the event bus.

type GetServicesRequest

type GetServicesRequest struct {
	Domain string `json:"domain" jsonschema:"The domain to list services for (e.g. light, switch, climate)."`
}

GetServicesRequest lists available services for a domain.

type GetStateRequest

type GetStateRequest struct {
	EntityId string `json:"entity_id" jsonschema:"The entity ID to query (e.g. light.living_room)."`
}

GetStateRequest returns a single entity's state.

type GetStatesRequest

type GetStatesRequest struct {
	Domain string `` /* 134-byte string literal not displayed */
}

GetStatesRequest filters the list of entity states.

type RenderTemplateRequest

type RenderTemplateRequest struct {
	Template string `json:"template" jsonschema:"The Jinja2 template string to render (e.g. '{{ states(\"sensor.temperature\") }}')."`
}

RenderTemplateRequest renders a Jinja2 template.

type Selector

type Selector struct {
	Text              string  `json:"text,omitempty"`
	Mode              string  `json:"mode,omitempty"`
	Min               float32 `json:"min,omitempty"`
	Max               float32 `json:"max,omitempty"`
	UnitOfMeasurement string  `json:"unit_of_measurement,omitempty"`
}

type Service

type Service struct {
	Call        string           `json:"call,omitempty"`
	Name        string           `json:"name,omitempty"`
	Description string           `json:"description,omitempty,wrap"`
	Fields      map[string]Field `json:"fields,omitempty,wrap"`
}

func (Service) String

func (v Service) String() string

type SetStateRequest

type SetStateRequest struct {
	EntityId   string         `json:"entity_id" jsonschema:"The entity ID to set (e.g. sensor.my_sensor)."`
	State      string         `json:"state" jsonschema:"The state value to set."`
	Attributes map[string]any `json:"attributes,omitempty" jsonschema:"Optional attributes such as unit_of_measurement, friendly_name, etc."`
}

SetStateRequest creates or updates an entity's state representation.

type State

type State struct {
	Entity       string         `json:"entity_id,width:40"`
	LastChanged  time.Time      `json:"last_changed,omitempty"`
	LastReported time.Time      `json:"last_reported,omitempty"`
	LastUpdated  time.Time      `json:"last_updated,omitempty"`
	State        string         `json:"state"`
	Attributes   map[string]any `json:"attributes"`
	Context      struct {
		Id       string `json:"id,omitempty"`
		ParentId string `json:"parent_id,omitempty"`
		UserId   string `json:"user_id,omitempty"`
	} `json:"context"`
}

func (State) Class

func (s State) Class() string

Class determines how the state should be interpreted, or will return "" if it's unknown

func (State) Domain

func (s State) Domain() string

Domain is used to determine the services which can be called on the entity

func (State) Name

func (s State) Name() string

Name is the friendly name of the entity

func (State) String

func (s State) String() string

func (State) UnitOfMeasurement

func (s State) UnitOfMeasurement() string

UnitOfMeasurement provides the unit of measurement for the state, or "" if there is no unit of measurement

func (State) Value

func (s State) Value() string

Value is the current state of the entity, or empty if the state is unavailable

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL