xevion/go-ha
1
0
Fork 0
mirror of https://github.com/Xevion/go-ha.git synced 2025-12-15 08:12:00 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: normalize & make basic corrections to documentation

Browse Source
This commit is contained in:
Xevion
2025-08-01 21:19:47 -05:00
parent e13fd6ab5b
commit 292879a8a9
28 changed files with 132 additions and 229 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
internal/connect/connection.go
View File

@@ -1,7 +1,3 @@
// Package websocket is used to interact with the Home Assistant
// websocket API. All HA interaction is done via websocket
// except for cases explicitly called out in http package
// documentation.
package connect
import (
@@ -20,13 +16,13 @@ import (
var ErrInvalidToken = errors.New("invalid authentication token")
// HAConnection is a wrapper around a websocket connection that provides a mutex for thread safety.
// HAConnection is a wrapper around a WebSocket connection that provides a mutex for thread safety.
type HAConnection struct {
Conn *websocket.Conn // Note: this is not thread safe except for Close() and WriteControl()
mutex sync.Mutex
}
// WriteMessage writes a message to the websocket connection.
// WriteMessage writes a message to the WebSocket connection.
func (w *HAConnection) WriteMessage(msg any) error {
w.mutex.Lock()
defer w.mutex.Unlock()
@@ -34,7 +30,7 @@ func (w *HAConnection) WriteMessage(msg any) error {
return w.Conn.WriteJSON(msg)
}
// ReadMessageRaw reads a raw message from the websocket connection.
// ReadMessageRaw reads a raw message from the WebSocket connection.
func ReadMessageRaw(conn *websocket.Conn) ([]byte, error) {
_, msg, err := conn.ReadMessage()
if err != nil {
@@ -43,7 +39,7 @@ func ReadMessageRaw(conn *websocket.Conn) ([]byte, error) {
return msg, nil
}
// ReadMessage reads a message from the websocket connection and unmarshals it into the given type.
// ReadMessage reads a message from the WebSocket connection and unmarshals it into the given type.
func ReadMessage[T any](conn *websocket.Conn) (T, error) {
var result T
_, msg, err := conn.ReadMessage()
@@ -59,14 +55,14 @@ func ReadMessage[T any](conn *websocket.Conn) (T, error) {
return result, nil
}
// ConnectionFromUri creates a new websocket connection from the given base URL and authentication token.
// ConnectionFromUri creates a new WebSocket connection from the given base URL and authentication token.
func ConnectionFromUri(baseUrl *url.URL, token string) (*HAConnection, context.Context, context.CancelFunc, error) {
// Build the websocket URL
// Build the WebSocket URL
urlWebsockets := *baseUrl
urlWebsockets.Path = "/api/websocket"
scheme, err := internal.GetEquivalentWebsocketScheme(baseUrl.Scheme)
if err != nil {
return nil, nil, nil, fmt.Errorf("failed to build websocket URL: %w", err)
return nil, nil, nil, fmt.Errorf("failed to build WebSocket URL: %w", err)
}
urlWebsockets.Scheme = scheme
@@ -74,11 +70,11 @@ func ConnectionFromUri(baseUrl *url.URL, token string) (*HAConnection, context.C
connCtx, connCtxCancel := context.WithTimeout(context.Background(), time.Second*3)
defer connCtxCancel() // Always cancel the connection context when we're done
// Init websocket connection
// Init WebSocket connection
dialer := websocket.DefaultDialer
conn, _, err := dialer.DialContext(connCtx, urlWebsockets.String(), nil)
if err != nil {
slog.Error("Failed to connect to websocket. Check URI\n", "url", urlWebsockets)
slog.Error("Failed to connect to WebSocket. Check URI\n", "url", urlWebsockets)
return nil, nil, nil, err
}
@@ -87,7 +83,7 @@ func ConnectionFromUri(baseUrl *url.URL, token string) (*HAConnection, context.C
MsgType string `json:"type"`
}](conn)
if err != nil {
slog.Error("Unknown error creating websocket client\n")
slog.Error("Unknown error creating WebSocket client\n")
return nil, nil, nil, err
} else if msg.MsgType != "auth_required" {
slog.Error("Expected auth_required message, got", "msgType", msg.MsgType)
@@ -97,7 +93,7 @@ func ConnectionFromUri(baseUrl *url.URL, token string) (*HAConnection, context.C
// Send auth message
err = SendAuthMessage(conn, connCtx, token)
if err != nil {
slog.Error("Unknown error creating websocket client\n")
slog.Error("Unknown error creating WebSocket client\n")
return nil, nil, nil, err
}
@@ -114,7 +110,7 @@ func ConnectionFromUri(baseUrl *url.URL, token string) (*HAConnection, context.C
return &HAConnection{Conn: conn}, appCtx, appCtxCancel, nil
}
// SendAuthMessage sends an auth message to the websocket connection.
// SendAuthMessage sends an auth message to the WebSocket connection.
func SendAuthMessage(conn *websocket.Conn, ctx context.Context, token string) error {
type AuthMessage struct {
MsgType string `json:"type"`
@@ -174,7 +170,7 @@ func SubscribeToEventType(eventType string, conn *HAConnection, ctx context.Cont
err := conn.WriteMessage(e)
// TODO: Handle errors better
if err != nil {
wrappedErr := fmt.Errorf("error writing to websocket: %w", err)
wrappedErr := fmt.Errorf("error writing to WebSocket: %w", err)
slog.Error(wrappedErr.Error())
panic(wrappedErr)
}

8
internal/connect/listen.go
View File

@@ -7,7 +7,7 @@ import (
"github.com/gorilla/websocket"
)
// BaseMessage is the base message type for all messages sent by the websocket server.
// BaseMessage is the base message type for all messages sent by the WebSocket server.
type BaseMessage struct {
Type string `json:"type"`
Id int64 `json:"id"`
@@ -21,14 +21,14 @@ type ChannelMessage struct {
Raw []byte
}
// ListenWebsocket reads messages from the websocket connection and sends them to the channel.
// ListenWebsocket reads messages from the WebSocket connection and sends them to the channel.
// It will close the channel if it encounters an error, or if the channel is full, and return.
// It ignores errors in deserialization.
func ListenWebsocket(conn *websocket.Conn, c chan ChannelMessage) {
for {
raw, err := ReadMessageRaw(conn)
if err != nil {
slog.Error("Error reading from websocket", "err", err)
slog.Error("Error reading from WebSocket", "err", err)
close(c)
break
}
@@ -60,7 +60,7 @@ func ListenWebsocket(conn *websocket.Conn, c chan ChannelMessage) {
// Message sent successfully
default:
// Channel is full or closed, break out of loop
slog.Warn("Websocket message channel is full or closed, stopping listener",
slog.Warn("WebSocket message channel is full or closed, stopping listener",
"channel_capacity", cap(c),
"channel_length", len(c))
close(c)

5
internal/http.go
View File

@@ -1,6 +1,3 @@
// http is used to interact with the home assistant
// REST API. Currently only used to retrieve state for
// a single entity_id
package internal
import (
@@ -44,7 +41,7 @@ func NewHttpClient(ctx context.Context, baseUrl *url.URL, token string) *HttpCli
}
}
// getRequest returns a new request
// getRequest returns a new request.
func (c *HttpClient) getRequest() *resty.Request {
return c.baseRequest.Clone(c.client.Context())
}

5
internal/misc.go
View File

@@ -21,8 +21,7 @@ var (
id atomic.Int64 // default value is 0
)
// NextId returns a unique integer (for the given process), often used for providing a uniquely identifiable
// id for a request. This function is thread-safe.
// NextId returns a unique integer (for the given process), often used for providing a uniquely identifiable ID for a request. This function is thread-safe.
func NextId() int64 {
return id.Add(1)
}
@@ -32,7 +31,7 @@ func GetFunctionName(i interface{}) string {
return runtime.FuncForPC(reflect.ValueOf(i).Pointer()).Name()
}
// GetEquivalentWebsocketScheme returns the equivalent websocket scheme for the given scheme.
// GetEquivalentWebsocketScheme returns the equivalent WebSocket scheme for the given scheme.
// If the scheme is http or https, it returns ws or wss respectively.
// If the scheme is ws or wss, it returns the same scheme.
// If the scheme is not any of the above, it returns an error.

6
internal/parse.go
View File

@@ -8,11 +8,11 @@ import (
"github.com/dromara/carbon/v2"
)
// Parses a HH:MM string.
// ParseTime parses a HH:MM string.
func ParseTime(s string) *carbon.Carbon {
t, err := time.Parse("15:04", s)
if err != nil {
parsingErr := fmt.Errorf("failed to parse time string \"%s\"; format must be HH:MM.: %w", s, err)
parsingErr := fmt.Errorf("failed to parse time string \"%s\"; format must be HH:MM: %w", s, err)
slog.Error(parsingErr.Error())
panic(parsingErr)
}
@@ -22,7 +22,7 @@ func ParseTime(s string) *carbon.Carbon {
func ParseDuration(s string) time.Duration {
d, err := time.ParseDuration(s)
if err != nil {
parsingErr := fmt.Errorf("couldn't parse string duration: \"%s\" see https://pkg.go.dev/time#ParseDuration for valid time units: %w", s, err)
parsingErr := fmt.Errorf("couldn't parse string duration: \"%s\"; see https://pkg.go.dev/time#ParseDuration for valid time units: %w", s, err)
slog.Error(parsingErr.Error())
panic(parsingErr)
}

28
internal/services/alarm_control_panel.go
View File

@@ -8,9 +8,7 @@ type AlarmControlPanel struct {
conn *connect.HAConnection
}
// Send the alarm the command for arm away.
// Takes an entityId and an optional
// map that is translated into service_data.
// Send the alarm the command for arm away. Takes an entityId and an optional map that is translated into service_data.
func (acp AlarmControlPanel) ArmAway(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "alarm_control_panel"
@@ -22,9 +20,7 @@ func (acp AlarmControlPanel) ArmAway(entityId string, serviceData ...map[string]
return acp.conn.WriteMessage(req)
}
// Send the alarm the command for arm away.
// Takes an entityId and an optional
// map that is translated into service_data.
// Send the alarm the command for arm away. Takes an entityId and an optional map that is translated into service_data.
func (acp AlarmControlPanel) ArmWithCustomBypass(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "alarm_control_panel"
@@ -36,9 +32,7 @@ func (acp AlarmControlPanel) ArmWithCustomBypass(entityId string, serviceData ..
return acp.conn.WriteMessage(req)
}
// Send the alarm the command for arm home.
// Takes an entityId and an optional
// map that is translated into service_data.
// Send the alarm the command for arm home. Takes an entityId and an optional map that is translated into service_data.
func (acp AlarmControlPanel) ArmHome(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "alarm_control_panel"
@@ -50,9 +44,7 @@ func (acp AlarmControlPanel) ArmHome(entityId string, serviceData ...map[string]
return acp.conn.WriteMessage(req)
}
// Send the alarm the command for arm night.
// Takes an entityId and an optional
// map that is translated into service_data.
// Send the alarm the command for arm night. Takes an entityId and an optional map that is translated into service_data.
func (acp AlarmControlPanel) ArmNight(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "alarm_control_panel"
@@ -64,9 +56,7 @@ func (acp AlarmControlPanel) ArmNight(entityId string, serviceData ...map[string
return acp.conn.WriteMessage(req)
}
// Send the alarm the command for arm vacation.
// Takes an entityId and an optional
// map that is translated into service_data.
// Send the alarm the command for arm vacation. Takes an entityId and an optional map that is translated into service_data.
func (acp AlarmControlPanel) ArmVacation(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "alarm_control_panel"
@@ -78,9 +68,7 @@ func (acp AlarmControlPanel) ArmVacation(entityId string, serviceData ...map[str
return acp.conn.WriteMessage(req)
}
// Send the alarm the command for disarm.
// Takes an entityId and an optional
// map that is translated into service_data.
// Send the alarm the command for disarm. Takes an entityId and an optional map that is translated into service_data.
func (acp AlarmControlPanel) Disarm(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "alarm_control_panel"
@@ -92,9 +80,7 @@ func (acp AlarmControlPanel) Disarm(entityId string, serviceData ...map[string]a
return acp.conn.WriteMessage(req)
}
// Send the alarm the command for trigger.
// Takes an entityId and an optional
// map that is translated into service_data.
// Send the alarm the command for trigger. Takes an entityId and an optional map that is translated into service_data.
func (acp AlarmControlPanel) Trigger(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "alarm_control_panel"

6
internal/services/cover.go
View File

@@ -44,8 +44,7 @@ func (c Cover) OpenTilt(entityId string) error {
return c.conn.WriteMessage(req)
}
// Move to specific position all or specified cover. Takes an entityId and an optional
// map that is translated into service_data.
// Move to specific position all or specified cover. Takes an entityId and an optional map that is translated into service_data.
func (c Cover) SetPosition(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "cover"
@@ -57,8 +56,7 @@ func (c Cover) SetPosition(entityId string, serviceData ...map[string]any) error
return c.conn.WriteMessage(req)
}
// Move to specific position all or specified cover tilt. Takes an entityId and an optional
// map that is translated into service_data.
// Move to specific position all or specified cover tilt. Takes an entityId and an optional map that is translated into service_data.
func (c Cover) SetTiltPosition(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "cover"

3
internal/services/event.go
View File

@@ -17,8 +17,7 @@ type FireEventRequest struct {
EventData map[string]any `json:"event_data,omitempty"`
}
// Fire an event. Takes an event type and an optional map that is sent
// as `event_data`.
// Fire an event. Takes an event type and an optional map that is sent as `event_data`.
func (e Event) Fire(eventType string, eventData ...map[string]any) error {
req := FireEventRequest{
Id: internal.NextId(),

7
internal/services/home_assistant.go
View File

@@ -8,8 +8,7 @@ type HomeAssistant struct {
conn *connect.HAConnection
}
// TurnOn a Home Assistant entity. Takes an entityId and an optional
// map that is translated into service_data.
// TurnOn a Home Assistant entity. Takes an entityId and an optional map that is translated into service_data.
func (ha *HomeAssistant) TurnOn(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "homeassistant"
@@ -21,8 +20,7 @@ func (ha *HomeAssistant) TurnOn(entityId string, serviceData ...map[string]any)
return ha.conn.WriteMessage(req)
}
// Toggle a Home Assistant entity. Takes an entityId and an optional
// map that is translated into service_data.
// Toggle a Home Assistant entity. Takes an entityId and an optional map that is translated into service_data.
func (ha *HomeAssistant) Toggle(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "homeassistant"
@@ -34,6 +32,7 @@ func (ha *HomeAssistant) Toggle(entityId string, serviceData ...map[string]any)
return ha.conn.WriteMessage(req)
}
// TurnOff turns off a Home Assistant entity.
func (ha *HomeAssistant) TurnOff(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "homeassistant"

3
internal/services/input_boolean.go
View File

@@ -8,6 +8,7 @@ type InputBoolean struct {
conn *connect.HAConnection
}
// TurnOn turns on an input boolean entity.
func (ib InputBoolean) TurnOn(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "input_boolean"
@@ -16,6 +17,7 @@ func (ib InputBoolean) TurnOn(entityId string) error {
return ib.conn.WriteMessage(req)
}
// Toggle toggles an input boolean entity.
func (ib InputBoolean) Toggle(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "input_boolean"
@@ -24,6 +26,7 @@ func (ib InputBoolean) Toggle(entityId string) error {
return ib.conn.WriteMessage(req)
}
// TurnOff turns off an input boolean entity.
func (ib InputBoolean) TurnOff(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "input_boolean"

1
internal/services/input_button.go
View File

@@ -8,6 +8,7 @@ type InputButton struct {
conn *connect.HAConnection
}
// Press presses an input button entity.
func (ib InputButton) Press(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "input_button"

1
internal/services/input_text.go
View File

@@ -8,6 +8,7 @@ type InputText struct {
conn *connect.HAConnection
}
// Set sets the value of an input text entity.
func (ib InputText) Set(entityId string, value string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "input_text"

7
internal/services/light.go
View File

@@ -8,8 +8,7 @@ type Light struct {
conn *connect.HAConnection
}
// TurnOn a light entity. Takes an entityId and an optional
// map that is translated into service_data.
// TurnOn a light entity. Takes an entityId and an optional map that is translated into service_data.
func (l Light) TurnOn(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "light"
@@ -21,8 +20,7 @@ func (l Light) TurnOn(entityId string, serviceData ...map[string]any) error {
return l.conn.WriteMessage(req)
}
// Toggle a light entity. Takes an entityId and an optional
// map that is translated into service_data.
// Toggle a light entity. Takes an entityId and an optional map that is translated into service_data.
func (l Light) Toggle(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "light"
@@ -34,6 +32,7 @@ func (l Light) Toggle(entityId string, serviceData ...map[string]any) error {
return l.conn.WriteMessage(req)
}
// TurnOff turns off a light entity.
func (l Light) TurnOff(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "light"

6
internal/services/lock.go
View File

@@ -8,8 +8,7 @@ type Lock struct {
conn *connect.HAConnection
}
// Lock a lock entity. Takes an entityId and an optional
// map that is translated into service_data.
// Lock a lock entity. Takes an entityId and an optional map that is translated into service_data.
func (l Lock) Lock(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "lock"
@@ -21,8 +20,7 @@ func (l Lock) Lock(entityId string, serviceData ...map[string]any) error {
return l.conn.WriteMessage(req)
}
// Unlock a lock entity. Takes an entityId and an optional
// map that is translated into service_data.
// Unlock a lock entity. Takes an entityId and an optional map that is translated into service_data.
func (l Lock) Unlock(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "lock"

75
internal/services/media_player.go
View File

@@ -8,8 +8,7 @@ type MediaPlayer struct {
conn *connect.HAConnection
}
// Send the media player the command to clear players playlist.
// Takes an entityId.
// Send the media player the command to clear players playlist. Takes an entityId.
func (mp MediaPlayer) ClearPlaylist(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -18,9 +17,7 @@ func (mp MediaPlayer) ClearPlaylist(entityId string) error {
return mp.conn.WriteMessage(req)
}
// Group players together. Only works on platforms with support for player groups.
// Takes an entityId and an optional
// map that is translated into service_data.
// Group players together. Only works on platforms with support for player groups. Takes an entityId and an optional map that is translated into service_data.
func (mp MediaPlayer) Join(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -32,8 +29,7 @@ func (mp MediaPlayer) Join(entityId string, serviceData ...map[string]any) error
return mp.conn.WriteMessage(req)
}
// Send the media player the command for next track.
// Takes an entityId.
// Send the media player the command for next track. Takes an entityId.
func (mp MediaPlayer) Next(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -42,8 +38,7 @@ func (mp MediaPlayer) Next(entityId string) error {
return mp.conn.WriteMessage(req)
}
// Send the media player the command for pause.
// Takes an entityId.
// Send the media player the command for pause. Takes an entityId.
func (mp MediaPlayer) Pause(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -52,8 +47,7 @@ func (mp MediaPlayer) Pause(entityId string) error {
return mp.conn.WriteMessage(req)
}
// Send the media player the command for play.
// Takes an entityId.
// Send the media player the command for play. Takes an entityId.
func (mp MediaPlayer) Play(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -62,8 +56,7 @@ func (mp MediaPlayer) Play(entityId string) error {
return mp.conn.WriteMessage(req)
}
// Toggle media player play/pause state.
// Takes an entityId.
// Toggle media player play/pause state. Takes an entityId.
func (mp MediaPlayer) PlayPause(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -72,8 +65,7 @@ func (mp MediaPlayer) PlayPause(entityId string) error {
return mp.conn.WriteMessage(req)
}
// Send the media player the command for previous track.
// Takes an entityId.
// Send the media player the command for previous track. Takes an entityId.
func (mp MediaPlayer) Previous(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -82,9 +74,7 @@ func (mp MediaPlayer) Previous(entityId string) error {
return mp.conn.WriteMessage(req)
}
// Send the media player the command to seek in current playing media.
// Takes an entityId and an optional
// map that is translated into service_data.
// Send the media player the command to seek in current playing media. Takes an entityId and an optional map that is translated into service_data.
func (mp MediaPlayer) Seek(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -96,8 +86,7 @@ func (mp MediaPlayer) Seek(entityId string, serviceData ...map[string]any) error
return mp.conn.WriteMessage(req)
}
// Send the media player the stop command.
// Takes an entityId.
// Send the media player the stop command. Takes an entityId.
func (mp MediaPlayer) Stop(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -106,9 +95,7 @@ func (mp MediaPlayer) Stop(entityId string) error {
return mp.conn.WriteMessage(req)
}
// Send the media player the command for playing media.
// Takes an entityId and an optional
// map that is translated into service_data.
// Send the media player the command to play a media. Takes an entityId and an optional map that is translated into service_data.
func (mp MediaPlayer) PlayMedia(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -120,8 +107,7 @@ func (mp MediaPlayer) PlayMedia(entityId string, serviceData ...map[string]any)
return mp.conn.WriteMessage(req)
}
// Set repeat mode. Takes an entityId and an optional
// map that is translated into service_data.
// Set repeat mode. Takes an entityId and an optional map that is translated into service_data.
func (mp MediaPlayer) RepeatSet(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -133,9 +119,7 @@ func (mp MediaPlayer) RepeatSet(entityId string, serviceData ...map[string]any)
return mp.conn.WriteMessage(req)
}
// Send the media player the command to change sound mode.
// Takes an entityId and an optional
// map that is translated into service_data.
// Select a sound mode. Takes an entityId and an optional map that is translated into service_data.
func (mp MediaPlayer) SelectSoundMode(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -147,9 +131,7 @@ func (mp MediaPlayer) SelectSoundMode(entityId string, serviceData ...map[string
return mp.conn.WriteMessage(req)
}
// Send the media player the command to change input source.
// Takes an entityId and an optional
// map that is translated into service_data.
// Select a source. Takes an entityId and an optional map that is translated into service_data.
func (mp MediaPlayer) SelectSource(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -161,9 +143,7 @@ func (mp MediaPlayer) SelectSource(entityId string, serviceData ...map[string]an
return mp.conn.WriteMessage(req)
}
// Set shuffling state.
// Takes an entityId and an optional
// map that is translated into service_data.
// Toggle shuffle state. Takes an entityId and an optional map that is translated into service_data.
func (mp MediaPlayer) Shuffle(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -175,8 +155,7 @@ func (mp MediaPlayer) Shuffle(entityId string, serviceData ...map[string]any) er
return mp.conn.WriteMessage(req)
}
// Toggles a media player power state.
// Takes an entityId.
// Toggle a media player on/off. Takes an entityId.
func (mp MediaPlayer) Toggle(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -185,8 +164,7 @@ func (mp MediaPlayer) Toggle(entityId string) error {
return mp.conn.WriteMessage(req)
}
// Turn a media player power off.
// Takes an entityId.
// Turn off a media player. Takes an entityId.
func (mp MediaPlayer) TurnOff(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -195,8 +173,7 @@ func (mp MediaPlayer) TurnOff(entityId string) error {
return mp.conn.WriteMessage(req)
}
// Turn a media player power on.
// Takes an entityId.
// Turn on a media player. Takes an entityId.
func (mp MediaPlayer) TurnOn(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -205,9 +182,7 @@ func (mp MediaPlayer) TurnOn(entityId string) error {
return mp.conn.WriteMessage(req)
}
// Unjoin the player from a group. Only works on
// platforms with support for player groups.
// Takes an entityId.
// Separate a player from a group. Only works on platforms with support for player groups. Takes an entityId.
func (mp MediaPlayer) Unjoin(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -216,8 +191,7 @@ func (mp MediaPlayer) Unjoin(entityId string) error {
return mp.conn.WriteMessage(req)
}
// Turn a media player volume down.
// Takes an entityId.
// Send the media player the command for volume down. Takes an entityId.
func (mp MediaPlayer) VolumeDown(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -226,9 +200,7 @@ func (mp MediaPlayer) VolumeDown(entityId string) error {
return mp.conn.WriteMessage(req)
}
// Mute a media player's volume.
// Takes an entityId and an optional
// map that is translated into service_data.
// Mute a media player. Takes an entityId and an optional map that is translated into service_data.
func (mp MediaPlayer) VolumeMute(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -240,9 +212,7 @@ func (mp MediaPlayer) VolumeMute(entityId string, serviceData ...map[string]any)
return mp.conn.WriteMessage(req)
}
// Set a media player's volume level.
// Takes an entityId and an optional
// map that is translated into service_data.
// Set volume level. Takes an entityId and an optional map that is translated into service_data.
func (mp MediaPlayer) VolumeSet(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"
@@ -254,8 +224,7 @@ func (mp MediaPlayer) VolumeSet(entityId string, serviceData ...map[string]any)
return mp.conn.WriteMessage(req)
}
// Turn a media player volume up.
// Takes an entityId.
// Send the media player the command for volume up. Takes an entityId.
func (mp MediaPlayer) VolumeUp(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "media_player"

6
internal/services/scene.go
View File

@@ -20,8 +20,7 @@ func (s Scene) Apply(serviceData ...map[string]any) error {
return s.conn.WriteMessage(req)
}
// Create a scene entity. Takes an entityId and an optional
// map that is translated into service_data.
// Create a scene entity. Takes an entityId and an optional map that is translated into service_data.
func (s Scene) Create(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "scene"
@@ -42,8 +41,7 @@ func (s Scene) Reload() error {
return s.conn.WriteMessage(req)
}
// TurnOn a scene entity. Takes an entityId and an optional
// map that is translated into service_data.
// TurnOn a scene entity. Takes an entityId and an optional map that is translated into service_data.
func (s Scene) TurnOn(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "scene"

3
internal/services/switch.go
View File

@@ -8,6 +8,7 @@ type Switch struct {
conn *connect.HAConnection
}
// TurnOn turns on a switch entity.
func (s Switch) TurnOn(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "switch"
@@ -16,6 +17,7 @@ func (s Switch) TurnOn(entityId string) error {
return s.conn.WriteMessage(req)
}
// Toggle toggles a switch entity.
func (s Switch) Toggle(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "switch"
@@ -24,6 +26,7 @@ func (s Switch) Toggle(entityId string) error {
return s.conn.WriteMessage(req)
}
// TurnOff turns off a switch entity.
func (s Switch) TurnOff(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "switch"

8
internal/services/tts.go
View File

@@ -17,9 +17,7 @@ func (tts TTS) ClearCache() error {
return tts.conn.WriteMessage(req)
}
// Say something using text-to-speech on a media player with cloud.
// Takes an entityId and an optional
// map that is translated into service_data.
// Say something using text-to-speech on a media player with cloud. Takes an entityId and an optional map that is translated into service_data.
func (tts TTS) CloudSay(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "tts"
@@ -31,9 +29,7 @@ func (tts TTS) CloudSay(entityId string, serviceData ...map[string]any) error {
return tts.conn.WriteMessage(req)
}
// Say something using text-to-speech on a media player with google_translate.
// Takes an entityId and an optional
// map that is translated into service_data.
// Say something using text-to-speech on a media player with google_translate. Takes an entityId and an optional map that is translated into service_data.
func (tts TTS) GoogleTranslateSay(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "tts"

33
internal/services/vacuum.go
View File

@@ -8,8 +8,7 @@ type Vacuum struct {
conn *connect.HAConnection
}
// Tell the vacuum cleaner to do a spot clean-up.
// Takes an entityId.
// Tell the vacuum cleaner to do a spot clean-up. Takes an entityId.
func (v Vacuum) CleanSpot(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "vacuum"
@@ -18,8 +17,7 @@ func (v Vacuum) CleanSpot(entityId string) error {
return v.conn.WriteMessage(req)
}
// Locate the vacuum cleaner robot.
// Takes an entityId.
// Locate the vacuum cleaner robot. Takes an entityId.
func (v Vacuum) Locate(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "vacuum"
@@ -28,8 +26,7 @@ func (v Vacuum) Locate(entityId string) error {
return v.conn.WriteMessage(req)
}
// Pause the cleaning task.
// Takes an entityId.
// Pause the cleaning task. Takes an entityId.
func (v Vacuum) Pause(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "vacuum"
@@ -38,8 +35,7 @@ func (v Vacuum) Pause(entityId string) error {
return v.conn.WriteMessage(req)
}
// Tell the vacuum cleaner to return to its dock.
// Takes an entityId.
// Tell the vacuum cleaner to return to its dock. Takes an entityId.
func (v Vacuum) ReturnToBase(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "vacuum"
@@ -48,8 +44,7 @@ func (v Vacuum) ReturnToBase(entityId string) error {
return v.conn.WriteMessage(req)
}
// Send a raw command to the vacuum cleaner. Takes an entityId and an optional
// map that is translated into service_data.
// Send a raw command to the vacuum cleaner. Takes an entityId and an optional map that is translated into service_data.
func (v Vacuum) SendCommand(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "vacuum"
@@ -61,8 +56,7 @@ func (v Vacuum) SendCommand(entityId string, serviceData ...map[string]any) erro
return v.conn.WriteMessage(req)
}
// Set the fan speed of the vacuum cleaner. Takes an entityId and an optional
// map that is translated into service_data.
// Set the fan speed of the vacuum cleaner. Takes an entityId and an optional map that is translated into service_data.
func (v Vacuum) SetFanSpeed(entityId string, serviceData ...map[string]any) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "vacuum"
@@ -75,8 +69,7 @@ func (v Vacuum) SetFanSpeed(entityId string, serviceData ...map[string]any) erro
return v.conn.WriteMessage(req)
}
// Start or resume the cleaning task.
// Takes an entityId.
// Start or resume the cleaning task. Takes an entityId.
func (v Vacuum) Start(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "vacuum"
@@ -85,8 +78,7 @@ func (v Vacuum) Start(entityId string) error {
return v.conn.WriteMessage(req)
}
// Start, pause, or resume the cleaning task.
// Takes an entityId.
// Start, pause, or resume the cleaning task. Takes an entityId.
func (v Vacuum) StartPause(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "vacuum"
@@ -95,8 +87,7 @@ func (v Vacuum) StartPause(entityId string) error {
return v.conn.WriteMessage(req)
}
// Stop the current cleaning task.
// Takes an entityId.
// Stop the current cleaning task. Takes an entityId.
func (v Vacuum) Stop(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "vacuum"
@@ -105,8 +96,7 @@ func (v Vacuum) Stop(entityId string) error {
return v.conn.WriteMessage(req)
}
// Stop the current cleaning task and return to home.
// Takes an entityId.
// Stop the current cleaning task and return to home. Takes an entityId.
func (v Vacuum) TurnOff(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "vacuum"
@@ -115,8 +105,7 @@ func (v Vacuum) TurnOff(entityId string) error {
return v.conn.WriteMessage(req)
}
// Start a new cleaning task.
// Takes an entityId.
// Start a new cleaning task. Takes an entityId.
func (v Vacuum) TurnOn(entityId string) error {
req := NewBaseServiceRequest(entityId)
req.Domain = "vacuum"