gatt: add ble.Profile and modify API accordingly.

A profile is simply the top level of grouping hierachy.

1. Rename group.go to profile.go
2. Add DiscoverProfile() to discover the whole hierachy.
3. modify explorer to use the new API.

Author: Tzu-Jung Lee

Diff for: darwin/client.go

@@ -1,14 +1,16 @@
 package darwin
 
 import (
+	"fmt"
+
 	"github.com/currantlabs/ble"
 	"github.com/raff/goble/xpc"
 )
 
 // A Client is a GATT client.
 type Client struct {
-	svcs []*ble.Service
-	name string
+	profile *ble.Profile
+	name    string
 
 	id   xpc.UUID
 	conn *conn
@@ -33,9 +35,34 @@ func (cln *Client) Name() string {
 	return cln.name
 }
 
-// Services returns discovered services.
-func (cln *Client) Services() []*ble.Service {
-	return cln.svcs
+// Profile returns the discovered profile.
+func (cln *Client) Profile() *ble.Profile {
+	return cln.profile
+}
+
+// DiscoverProfile discovers the whole hierachy of a server.
+func (cln *Client) DiscoverProfile(force bool) (*ble.Profile, error) {
+	if cln.profile != nil && !force {
+		return cln.profile, nil
+	}
+	ss, err := cln.DiscoverServices(nil)
+	if err != nil {
+		return nil, fmt.Errorf("can't discover services: %s\n", err)
+	}
+	for _, s := range ss {
+		cs, err := cln.DiscoverCharacteristics(nil, s)
+		if err != nil {
+			return nil, fmt.Errorf("can't discover characteristics: %s\n", err)
+		}
+		for _, c := range cs {
+			_, err := cln.DiscoverDescriptors(nil, c)
+			if err != nil {
+				return nil, fmt.Errorf("can't discover descriptors: %s\n", err)
+			}
+		}
+	}
+	cln.profile = &ble.Profile{Services: ss}
+	return cln.profile, nil
 }
 
 // DiscoverServices finds all the primary services on a server. [Vol 3, Part G, 4.4.1]
@@ -57,7 +84,9 @@ func (cln *Client) DiscoverServices(ss []ble.UUID) ([]*ble.Service, error) {
 			EndHandle: uint16(xs.serviceEndHandle()),
 		})
 	}
-	cln.svcs = svcs
+	if cln.profile == nil {
+		cln.profile = &ble.Profile{Services: svcs}
+	}
 	return svcs, nil
 }
 

Diff for: examples/explorer/main.go

@@ -20,18 +20,14 @@ var (
 func explorer(cln ble.Client) error {
 	fmt.Printf("Exploring Peripheral [ %s ] ...\n", cln.Address())
 
-	ss, err := cln.DiscoverServices(nil)
+	p, err := cln.DiscoverProfile(true)
 	if err != nil {
 		return fmt.Errorf("can't discover services: %s\n", err)
 	}
-	for _, s := range ss {
+	for _, s := range p.Services {
 		fmt.Printf("Service: %s %s, Handle (0x%02X)\n", s.UUID.String(), ble.Name(s.UUID), s.Handle)
 
-		cs, err := cln.DiscoverCharacteristics(nil, s)
-		if err != nil {
-			return fmt.Errorf("can't discover characteristics: %s\n", err)
-		}
-		for _, c := range cs {
+		for _, c := range s.Characteristics {
 			fmt.Printf("  Characteristic: %s, Property: 0x%02X (%s), %s, Handle(0x%02X), VHandle(0x%02X)\n",
 				c.UUID, c.Property, propString(c.Property), ble.Name(c.UUID), c.Handle, c.ValueHandle)
 			if (c.Property & ble.CharRead) != 0 {
@@ -43,11 +39,7 @@ func explorer(cln ble.Client) error {
 				fmt.Printf("    Value         %x | %q\n", b, b)
 			}
 
-			ds, err := cln.DiscoverDescriptors(nil, c)
-			if err != nil {
-				return fmt.Errorf("can't discover descriptors: %s\n", err)
-			}
-			for _, d := range ds {
+			for _, d := range c.Descriptors {
 				fmt.Printf("    Descriptor: %s, %s, Handle(0x%02x)\n", d.UUID, ble.Name(d.UUID), d.Handle)
 				b, err := cln.ReadDescriptor(d)
 				if err != nil {

Diff for: gatt.go

@@ -9,9 +9,11 @@ type Client interface {
 	// This can be the advertised name, if exists, or the GAP device name, which takes priority.
 	Name() string
 
-	// Services returns discovered services.
-	Services() []*Service
+	// Profile returns discovered profile.
+	Profile() *Profile
 
+	// DiscoverProfile discovers the whole hierachy of a server.
+	DiscoverProfile(force bool) (*Profile, error)
 	// DiscoverServices finds all the primary services on a server. [Vol 3, Part G, 4.4.1]
 	// If filter is specified, only filtered services are returned.
 	DiscoverServices(filter []UUID) ([]*Service, error)

Diff for: linux/gatt/client.go

@@ -2,19 +2,20 @@ package gatt
 
 import (
 	"encoding/binary"
+	"fmt"
 	"log"
 	"sync"
 
-	"github.com/currantlabs/ble/linux/att"
 	"github.com/currantlabs/ble"
+	"github.com/currantlabs/ble/linux/att"
 )
 
 const (
 	cccNotify   = 0x0001
 	cccIndicate = 0x0002
 )
 
-// NewClient ...
+// NewClient returns a GATT Client.
 func NewClient(conn ble.Conn) (*Client, error) {
 	p := &Client{
 		subs: make(map[uint16]*sub),
@@ -25,48 +26,77 @@ func NewClient(conn ble.Conn) (*Client, error) {
 	return p, nil
 }
 
-// Client ...
+// A Client is a GATT Client.
 type Client struct {
 	sync.RWMutex
 
-	svcs []*ble.Service
-	name string
-	subs map[uint16]*sub
+	profile *ble.Profile
+	name    string
+	subs    map[uint16]*sub
 
 	ac   *att.Client
 	conn ble.Conn
 }
 
-// Address ...
+// Address returns the address of the client.
 func (p *Client) Address() ble.Addr {
 	p.RLock()
 	defer p.RUnlock()
 	return p.conn.RemoteAddr()
 }
 
-// Name ...
+// Name returns the name of the client.
 func (p *Client) Name() string {
 	p.RLock()
 	defer p.RUnlock()
 	return p.name
 }
 
-// Services ...
-func (p *Client) Services() []*ble.Service {
+// Profile returns the discovered profile.
+func (p *Client) Profile() *ble.Profile {
 	p.RLock()
 	defer p.RUnlock()
-	return p.svcs
+	return p.profile
+}
+
+// DiscoverProfile discovers the whole hierachy of a server.
+func (p *Client) DiscoverProfile(force bool) (*ble.Profile, error) {
+	if p.profile != nil && !force {
+		return p.profile, nil
+	}
+	ss, err := p.DiscoverServices(nil)
+	if err != nil {
+		return nil, fmt.Errorf("can't discover services: %s\n", err)
+	}
+	for _, s := range ss {
+		cs, err := p.DiscoverCharacteristics(nil, s)
+		if err != nil {
+			return nil, fmt.Errorf("can't discover characteristics: %s\n", err)
+		}
+		for _, c := range cs {
+			_, err := p.DiscoverDescriptors(nil, c)
+			if err != nil {
+				return nil, fmt.Errorf("can't discover descriptors: %s\n", err)
+			}
+		}
+	}
+	p.profile = &ble.Profile{Services: ss}
+	return p.profile, nil
 }
 
-// DiscoverServices ...
+// DiscoverServices finds all the primary services on a server. [Vol 3, Part G, 4.4.1]
+// If filter is specified, only filtered services are returned.
 func (p *Client) DiscoverServices(filter []ble.UUID) ([]*ble.Service, error) {
 	p.Lock()
 	defer p.Unlock()
+	if p.profile == nil {
+		p.profile = &ble.Profile{}
+	}
 	start := uint16(0x0001)
 	for {
 		length, b, err := p.ac.ReadByGroupType(start, 0xFFFF, ble.PrimaryServiceUUID)
 		if err == ble.ErrAttrNotFound {
-			return p.svcs, nil
+			return p.profile.Services, nil
 		}
 		if err != nil {
 			return nil, err
@@ -81,25 +111,27 @@ func (p *Client) DiscoverServices(filter []ble.UUID) ([]*ble.Service, error) {
 					Handle:    h,
 					EndHandle: endh,
 				}
-				p.svcs = append(p.svcs, s)
+				p.profile.Services = append(p.profile.Services, s)
 			}
 			if endh == 0xFFFF {
-				return p.svcs, nil
+				return p.profile.Services, nil
 			}
 			start = endh + 1
 			b = b[length:]
 		}
 	}
 }
 
-// DiscoverIncludedServices ...
+// DiscoverIncludedServices finds the included services of a service. [Vol 3, Part G, 4.5.1]
+// If filter is specified, only filtered services are returned.
 func (p *Client) DiscoverIncludedServices(ss []ble.UUID, s *ble.Service) ([]*ble.Service, error) {
 	p.Lock()
 	defer p.Unlock()
 	return nil, nil
 }
 
-// DiscoverCharacteristics ...
+// DiscoverCharacteristics finds all the characteristics within a service. [Vol 3, Part G, 4.6.1]
+// If filter is specified, only filtered characteristics are returned.
 func (p *Client) DiscoverCharacteristics(filter []ble.UUID, s *ble.Service) ([]*ble.Characteristic, error) {
 	p.Lock()
 	defer p.Unlock()
@@ -138,7 +170,8 @@ func (p *Client) DiscoverCharacteristics(filter []ble.UUID, s *ble.Service) ([]*
 	return s.Characteristics, nil
 }
 
-// DiscoverDescriptors ...
+// DiscoverDescriptors finds all the descriptors within a characteristic. [Vol 3, Part G, 4.7.1]
+// If filter is specified, only filtered descriptors are returned.
 func (p *Client) DiscoverDescriptors(filter []ble.UUID, c *ble.Characteristic) ([]*ble.Descriptor, error) {
 	p.Lock()
 	defer p.Unlock()
@@ -171,21 +204,21 @@ func (p *Client) DiscoverDescriptors(filter []ble.UUID, c *ble.Characteristic) (
 	return c.Descriptors, nil
 }
 
-// ReadCharacteristic ...
+// ReadCharacteristic reads a characteristic value from a server. [Vol 3, Part G, 4.8.1]
 func (p *Client) ReadCharacteristic(c *ble.Characteristic) ([]byte, error) {
 	p.Lock()
 	defer p.Unlock()
 	return p.ac.Read(c.ValueHandle)
 }
 
-// ReadLongCharacteristic ...
+// ReadLongCharacteristic reads a characteristic value which is longer than the MTU. [Vol 3, Part G, 4.8.3]
 func (p *Client) ReadLongCharacteristic(c *ble.Characteristic) ([]byte, error) {
 	p.Lock()
 	defer p.Unlock()
 	return nil, nil
 }
 
-// WriteCharacteristic ...
+// WriteCharacteristic writes a characteristic value to a server. [Vol 3, Part G, 4.9.3]
 func (p *Client) WriteCharacteristic(c *ble.Characteristic, v []byte, noRsp bool) error {
 	p.Lock()
 	defer p.Unlock()
@@ -196,21 +229,21 @@ func (p *Client) WriteCharacteristic(c *ble.Characteristic, v []byte, noRsp bool
 	return p.ac.Write(c.ValueHandle, v)
 }
 
-// ReadDescriptor ...
+// ReadDescriptor reads a characteristic descriptor from a server. [Vol 3, Part G, 4.12.1]
 func (p *Client) ReadDescriptor(d *ble.Descriptor) ([]byte, error) {
 	p.Lock()
 	defer p.Unlock()
 	return p.ac.Read(d.Handle)
 }
 
-// WriteDescriptor ...
+// WriteDescriptor writes a characteristic descriptor to a server. [Vol 3, Part G, 4.12.3]
 func (p *Client) WriteDescriptor(d *ble.Descriptor, v []byte) error {
 	p.Lock()
 	defer p.Unlock()
 	return p.ac.Write(d.Handle, v)
 }
 
-// ReadRSSI ...
+// ReadRSSI retrieves the current RSSI value of remote peripheral. [Vol 2, Part E, 7.5.4]
 func (p *Client) ReadRSSI() int {
 	p.Lock()
 	defer p.Unlock()
@@ -226,7 +259,8 @@ func (p *Client) ExchangeMTU(mtu int) (int, error) {
 	return p.ac.ExchangeMTU(mtu)
 }
 
-// Subscribe ...
+// Subscribe subscribes to indication (if ind is set true), or notification of a
+// characteristic value. [Vol 3, Part G, 4.10 & 4.11]
 func (p *Client) Subscribe(c *ble.Characteristic, ind bool, h ble.NotificationHandler) error {
 	p.Lock()
 	defer p.Unlock()
@@ -236,7 +270,8 @@ func (p *Client) Subscribe(c *ble.Characteristic, ind bool, h ble.NotificationHa
 	return p.setHandlers(c.CCCD.Handle, c.ValueHandle, cccNotify, h)
 }
 
-// Unsubscribe ...
+// Unsubscribe unsubscribes to indication (if ind is set true), or notification
+// of a specified characteristic value. [Vol 3, Part G, 4.10 & 4.11]
 func (p *Client) Unsubscribe(c *ble.Characteristic, ind bool) error {
 	p.Lock()
 	defer p.Unlock()
@@ -273,7 +308,7 @@ func (p *Client) setHandlers(cccdh, vh, flag uint16, h ble.NotificationHandler)
 	return p.ac.Write(s.cccdh, v)
 }
 
-// ClearSubscriptions ...
+// ClearSubscriptions clears all subscriptions to notifications and indications.
 func (p *Client) ClearSubscriptions() error {
 	p.Lock()
 	defer p.Unlock()

Diff for: group.go renamed to profile.go

@@ -30,12 +30,17 @@ const (
 	CharExtended    Property = 0x80 // supports extended properties
 )
 
+// A Profile is composed of one or more services necessary to fulfill a use case.
+type Profile struct {
+	Services []*Service
+}
+
 // A Service is a BLE service.
 type Service struct {
 	UUID            UUID
 	Characteristics []*Characteristic
 
-	Handle       uint16
+	Handle    uint16
 	EndHandle uint16
 }
 
@@ -72,9 +77,9 @@ type Characteristic struct {
 	NotifyHandler   NotifyHandler
 	IndicateHandler NotifyHandler
 
-	Handle       uint16
-	ValueHandle  uint16
-	EndHandle uint16
+	Handle      uint16
+	ValueHandle uint16
+	EndHandle   uint16
 }
 
 // AddDescriptor adds a descriptor to a characteristic.