From 68bac8859f56e4e87a73ee16a4d62095be37a7a8 Mon Sep 17 00:00:00 2001 From: Elara Musayelyan Date: Fri, 22 Oct 2021 21:01:18 -0700 Subject: [PATCH] Add doc comments to api package --- api/client.go | 15 +++++++++++++++ api/info.go | 14 ++++++++++++++ api/time.go | 4 ++++ api/upgrade.go | 4 ++++ 4 files changed, 37 insertions(+) diff --git a/api/client.go b/api/client.go index 20e2fbd..67aa16b 100644 --- a/api/client.go +++ b/api/client.go @@ -11,8 +11,10 @@ import ( "go.arsenm.dev/itd/internal/types" ) +// Default socket address const DefaultAddr = "/tmp/itd/socket" +// Client is the socket API client type Client struct { conn net.Conn respCh chan types.Response @@ -23,6 +25,7 @@ type Client struct { dfuProgressCh chan DFUProgress } +// New creates a new client and sets it up func New(addr string) (*Client, error) { conn, err := net.Dial("unix", addr) if err != nil { @@ -48,6 +51,16 @@ func New(addr string) (*Client, error) { return out, err } +func (c *Client) Close() error { + err := c.conn.Close() + if err != nil { + return err + } + close(c.respCh) + return nil +} + +// request sends a request to itd and waits for and returns the response func (c *Client) request(req types.Request) (types.Response, error) { // Encode request into connection err := json.NewEncoder(c.conn).Encode(req) @@ -64,6 +77,7 @@ func (c *Client) request(req types.Request) (types.Response, error) { return res, nil } +// requestNoRes sends a request to itd and does not wait for the response func (c *Client) requestNoRes(req types.Request) error { // Encode request into connection err := json.NewEncoder(c.conn).Encode(req) @@ -73,6 +87,7 @@ func (c *Client) requestNoRes(req types.Request) error { return nil } +// handleResp handles the received response as needed func (c *Client) handleResp(res types.Response) error { switch res.Type { case types.ResTypeWatchHeartRate: diff --git a/api/info.go b/api/info.go index 409d631..cc5d555 100644 --- a/api/info.go +++ b/api/info.go @@ -6,6 +6,7 @@ import ( "go.arsenm.dev/itd/internal/types" ) +// Address gets the bluetooth address of the connected device func (c *Client) Address() (string, error) { res, err := c.request(types.Request{ Type: types.ReqTypeBtAddress, @@ -17,6 +18,7 @@ func (c *Client) Address() (string, error) { return res.Value.(string), nil } +// Version gets the firmware version of the connected device func (c *Client) Version() (string, error) { res, err := c.request(types.Request{ Type: types.ReqTypeFwVersion, @@ -28,6 +30,7 @@ func (c *Client) Version() (string, error) { return res.Value.(string), nil } +// BatteryLevel gets the battery level of the connected device func (c *Client) BatteryLevel() (uint8, error) { res, err := c.request(types.Request{ Type: types.ReqTypeBattLevel, @@ -39,6 +42,8 @@ func (c *Client) BatteryLevel() (uint8, error) { return uint8(res.Value.(float64)), nil } +// WatchBatteryLevel returns a channel which will contain +// new battery level values as they update func (c *Client) WatchBatteryLevel() (<-chan uint8, error) { c.battLevelCh = make(chan uint8, 2) err := c.requestNoRes(types.Request{ @@ -50,6 +55,7 @@ func (c *Client) WatchBatteryLevel() (<-chan uint8, error) { return c.battLevelCh, nil } +// HeartRate gets the heart rate from the connected device func (c *Client) HeartRate() (uint8, error) { res, err := c.request(types.Request{ Type: types.ReqTypeHeartRate, @@ -61,6 +67,8 @@ func (c *Client) HeartRate() (uint8, error) { return uint8(res.Value.(float64)), nil } +// WatchHeartRate returns a channel which will contain +// new heart rate values as they update func (c *Client) WatchHeartRate() (<-chan uint8, error) { c.heartRateCh = make(chan uint8, 2) err := c.requestNoRes(types.Request{ @@ -72,6 +80,7 @@ func (c *Client) WatchHeartRate() (<-chan uint8, error) { return c.heartRateCh, nil } +// StepCount gets the step count from the connected device func (c *Client) StepCount() (uint32, error) { res, err := c.request(types.Request{ Type: types.ReqTypeStepCount, @@ -83,6 +92,8 @@ func (c *Client) StepCount() (uint32, error) { return uint32(res.Value.(float64)), nil } +// WatchStepCount returns a channel which will contain +// new step count values as they update func (c *Client) WatchStepCount() (<-chan uint32, error) { c.stepCountCh = make(chan uint32, 2) err := c.requestNoRes(types.Request{ @@ -94,6 +105,7 @@ func (c *Client) WatchStepCount() (<-chan uint32, error) { return c.stepCountCh, nil } +// Motion gets the motion values from the connected device func (c *Client) Motion() (infinitime.MotionValues, error) { out := infinitime.MotionValues{} res, err := c.request(types.Request{ @@ -109,6 +121,8 @@ func (c *Client) Motion() (infinitime.MotionValues, error) { return out, nil } +// WatchMotion returns a channel which will contain +// new motion values as they update func (c *Client) WatchMotion() (<-chan infinitime.MotionValues, error) { c.motionCh = make(chan infinitime.MotionValues, 2) err := c.requestNoRes(types.Request{ diff --git a/api/time.go b/api/time.go index 5230008..4661204 100644 --- a/api/time.go +++ b/api/time.go @@ -6,6 +6,7 @@ import ( "go.arsenm.dev/itd/internal/types" ) +// SetTime sets the given time on the connected device func (c *Client) SetTime(t time.Time) error { _, err := c.request(types.Request{ Type: types.ReqTypeSetTime, @@ -17,6 +18,9 @@ func (c *Client) SetTime(t time.Time) error { return nil } +// SetTimeNow sets the time on the connected device to +// the current time. This is more accurate than +// SetTime(time.Now()) due to RFC3339 formatting func (c *Client) SetTimeNow() error { _, err := c.request(types.Request{ Type: types.ReqTypeSetTime, diff --git a/api/upgrade.go b/api/upgrade.go index f074072..3311b74 100644 --- a/api/upgrade.go +++ b/api/upgrade.go @@ -6,15 +6,19 @@ import ( "go.arsenm.dev/itd/internal/types" ) +// DFUProgress stores the progress of a DFU upfate type DFUProgress types.DFUProgress +// UpgradeType indicates the type of upgrade to be performed type UpgradeType uint8 +// Type of DFU upgrade const ( UpgradeTypeArchive UpgradeType = iota UpgradeTypeFiles ) +// FirmwareUpgrade initiates a DFU update and returns the progress channel func (c *Client) FirmwareUpgrade(upgType UpgradeType, files ...string) (<-chan DFUProgress, error) { err := json.NewEncoder(c.conn).Encode(types.Request{ Type: types.ReqTypeFwUpgrade,