Cleanups in the BLE library. (#2644)

Better names...
toitlang · Nov 26, 2024 · df1c11d · df1c11d
1 parent 389c870
commit df1c11d
Show file tree

Hide file tree

Showing 50 changed files with 400 additions and 137 deletions.
diff --git a/examples/ble/advertise.toit b/examples/ble/advertise.toit
@@ -10,13 +10,13 @@ main:
   adapter := ble.Adapter
   peripheral := adapter.peripheral
 
-  data := ble.AdvertisementData
+  data := ble.Advertisement
       --name="Toit device"
       --services=[BATTERY-SERVICE]
       --manufacturer-specific=#[0xFF, 0xFF, 't', 'o', 'i', 't']
   if false:
     // An equivalent way to create the data would use data blocks.
-    data = ble.AdvertisementData [
+    data = ble.Advertisement [
       ble.DataBlock.name "Toit device",
       ble.DataBlock.services-16 [BATTERY-SERVICE],
       // The company-id is not included here, as its default is #[0xFF, 0xFF].

diff --git a/examples/ble/connect.toit b/examples/ble/connect.toit
@@ -12,15 +12,15 @@ SCAN-DURATION   ::= Duration --s=3
 find-with-service central/ble.Central service/ble.BleUuid:
   central.scan --duration=SCAN-DURATION: | device/ble.RemoteScannedDevice |
     if device.data.contains-service service:
-        return device.address
+        return device.identifier
   throw "no device found"
 
 main:
   adapter := ble.Adapter
   central := adapter.central
 
-  address := find-with-service central BATTERY-SERVICE
-  remote-device := central.connect address
+  identifier := find-with-service central BATTERY-SERVICE
+  remote-device := central.connect identifier
   // Discover the battery service.
   services := remote-device.discover-services [BATTERY-SERVICE]
   battery-service/ble.RemoteService := services.first
@@ -33,4 +33,4 @@ main:
   value := battery-level-characteristic.read
   battery-level := value[0]
 
-  print "Battery level of $address: $battery-level%"
+  print "Battery level of $identifier: $battery-level%"
diff --git a/examples/ble/scan.toit b/examples/ble/scan.toit
@@ -11,10 +11,10 @@ main:
   adapter := ble.Adapter
   central := adapter.central
 
-  addresses := []
+  identifiers := []
 
   central.scan --duration=SCAN-DURATION: | device/ble.RemoteScannedDevice |
     if device.data.contains-service BATTERY-SERVICE:
-      addresses.add device.address
+      identifiers.add device.identifier
 
-  print addresses
+  print identifiers
diff --git a/external/gold/toit-provision__examples__ble-provision.toit.gold b/external/gold/toit-provision__examples__ble-provision.toit.gold
@@ -0,0 +1,3 @@
+<pkg:..>/src_/ble.toit:55:12: warning: Class 'AdvertisementData' is deprecated. Use 'Advertisement' instead
+        ble.AdvertisementData
+           ^~~~~~~~~~~~~~~~~~
diff --git a/external/gold/toit-provision__src__provision.toit.gold b/external/gold/toit-provision__src__provision.toit.gold
@@ -0,0 +1,3 @@
+toit-provision/src/src_/ble.toit:55:12: warning: Class 'AdvertisementData' is deprecated. Use 'Advertisement' instead
+        ble.AdvertisementData
+           ^~~~~~~~~~~~~~~~~~
diff --git a/external/gold/toit-provision__src__src___ble.toit.gold b/external/gold/toit-provision__src__src___ble.toit.gold
@@ -0,0 +1,3 @@
+toit-provision/src/src_/ble.toit:55:12: warning: Class 'AdvertisementData' is deprecated. Use 'Advertisement' instead
+        ble.AdvertisementData
+           ^~~~~~~~~~~~~~~~~~
diff --git a/external/gold/toit-provision__src__src___config.toit.gold b/external/gold/toit-provision__src__src___config.toit.gold
@@ -0,0 +1,3 @@
+toit-provision/src/src_/ble.toit:55:12: warning: Class 'AdvertisementData' is deprecated. Use 'Advertisement' instead
+        ble.AdvertisementData
+           ^~~~~~~~~~~~~~~~~~
diff --git a/external/gold/toit-provision__src__src___rpc.toit.gold b/external/gold/toit-provision__src__src___rpc.toit.gold
@@ -0,0 +1,3 @@
+toit-provision/src/src_/ble.toit:55:12: warning: Class 'AdvertisementData' is deprecated. Use 'Advertisement' instead
+        ble.AdvertisementData
+           ^~~~~~~~~~~~~~~~~~
diff --git a/external/gold/toit-provision__src__src___scan.toit.gold b/external/gold/toit-provision__src__src___scan.toit.gold
@@ -0,0 +1,3 @@
+toit-provision/src/src_/ble.toit:55:12: warning: Class 'AdvertisementData' is deprecated. Use 'Advertisement' instead
+        ble.AdvertisementData
+           ^~~~~~~~~~~~~~~~~~
diff --git a/external/gold/toit-provision__src__src___security.toit.gold b/external/gold/toit-provision__src__src___security.toit.gold
@@ -0,0 +1,3 @@
+toit-provision/src/src_/ble.toit:55:12: warning: Class 'AdvertisementData' is deprecated. Use 'Advertisement' instead
+        ble.AdvertisementData
+           ^~~~~~~~~~~~~~~~~~
diff --git a/external/gold/toit-provision__src__src___session.toit.gold b/external/gold/toit-provision__src__src___session.toit.gold
@@ -0,0 +1,3 @@
+toit-provision/src/src_/ble.toit:55:12: warning: Class 'AdvertisementData' is deprecated. Use 'Advertisement' instead
+        ble.AdvertisementData
+           ^~~~~~~~~~~~~~~~~~
diff --git a/external/gold/toit-provision__src__src___version.toit.gold b/external/gold/toit-provision__src__src___version.toit.gold
@@ -0,0 +1,3 @@
+toit-provision/src/src_/ble.toit:55:12: warning: Class 'AdvertisementData' is deprecated. Use 'Advertisement' instead
+        ble.AdvertisementData
+           ^~~~~~~~~~~~~~~~~~
diff --git a/lib/ble/ble.toit b/lib/ble/ble.toit
@@ -678,14 +678,29 @@ class DataBlock:
     return result
 
 /**
-Advertisement data as either sent by advertising or received through scanning.
-
-The size of an advertisement packet is limited to 31 bytes. This includes the name
-  and bytes that are required to structure the packet.
+Deprecated. Use $Advertisement instead.
 */
-class AdvertisementData:
-  /** The $DataBlock fields of this instance. */
-  data-blocks/List  // Of DataBlock.
+class AdvertisementData extends Advertisement:
+  /**
+  Deprecated. Use the $Advertisement.constructor instead. The argument $manufacturer-data has
+    been renamed to 'manufacturer-specific', and $service-classes has been renamed to 'services'.
+  */
+  constructor
+      --name/string?=null
+      --service-classes/List=[]
+      --manufacturer-data/io.Data=#[]
+      --.connectable=false
+      --flags/int=0
+      --check-size/bool=true:
+    super
+        --name=name
+        --services=service-classes
+        --manufacturer-specific=manufacturer-data.byte-size > 0 ? manufacturer-data : null
+        --flags=flags
+        --check-size=check-size
+
+  constructor.raw_ bytes/ByteArray? --.connectable:
+    super.raw bytes
 
   /**
   Whether connections are allowed.
@@ -694,54 +709,58 @@ class AdvertisementData:
   */
   connectable/bool
 
+  /**
+  Advertised service classes as a list of $BleUuid.
+
+  Deprecated. Use $Advertisement.services instead.
+  */
+  service-classes -> List: return services
+
+  /**
+  Manufacturer data as a byte array.
+
+  For backwards compatibility, returns an empty byte array if no manufacturer data is present.
+
+  Returns the concatenation of the manufacturer-id and the manufacturer-specific data.
+
+  Deprecated. Use $Advertisement.manufacturer-specific instead.
+  */
+  manufacturer-data -> ByteArray:
+    data-blocks.do: | block/DataBlock |
+      if block.is-manufacturer-specific: return block.data.copy
+    return ByteArray 0
+
+/**
+Advertisement data as either sent by advertising or received through scanning.
+
+The size of an advertisement packet is limited to 31 bytes. This includes the name
+  and bytes that are required to structure the packet.
+*/
+class Advertisement:
+  /** The $DataBlock fields of this instance. */
+  data-blocks/List  // Of DataBlock.
+
   /**
   Constructs an advertisement data packet with the given data blocks.
 
   Advertisement packets are limited to 31 data bytes. If $check-size is true, then
     the size of the data blocks is checked to ensure that the packet size does not
     exceed 31 bytes.
-
-  The $connectable parameter is only used to set the deprecated field of the same name.
-    It is safe to ignore it if the field is not used.
   */
-  constructor .data-blocks --.connectable/bool=false --check-size/bool=true:
+  constructor .data-blocks --check-size/bool=true:
     if check-size and size > 31: throw "PACKET_SIZE_EXCEEDED"
 
   /**
   Constructs an advertisement data packet from the $raw data.
 
   Advertisement packets are limited to 31 data bytes.
-
-  The $connectable parameter is only used to set the deprecated field of the same name.
-    It is safe to ignore it if the field is not used.
   */
-  constructor.raw raw/ByteArray? --.connectable/bool=false:
+  constructor.raw raw/ByteArray?:
     data-blocks = raw ? DataBlock.decode raw : []
 
-  /**
-  Deprecated. Use the $(constructor --services --manufacturer-specific) instead.
-  */
-  constructor
-      --name/string?=null
-      --service-classes/List
-      --manufacturer-data/io.Data=#[]
-      --connectable/bool=false
-      --flags/int=0
-      --check-size/bool=true:
-    return AdvertisementData
-        --name=name
-        --services=service-classes
-        --manufacturer-specific=manufacturer-data.byte-size > 0 ? manufacturer-data : null
-        --connectable=connectable
-        --flags=flags
-        --check-size=check-size
-
   /**
   Constructs an advertisement packet.
 
-  The $connectable parameter is only used to set the deprecated field of the same name.
-    It is safe to ignore it if the field is not used.
-
   If the $services parameter is not empty, then the list is split into 16-bit, 32-bit,
     and 128-bit UUIDs. Each of the lists that isn't empty is then encoded into the
     advertisement data.
@@ -750,7 +769,6 @@ class AdvertisementData:
       --name/string?=null
       --services/List=[]
       --manufacturer-specific/io.Data?=null
-      --.connectable=false
       --flags/int?=null
       --check-size/bool=true:
     blocks := []
@@ -784,13 +802,6 @@ class AdvertisementData:
       if block.is-name: return block.name
     return null
 
-  /**
-  Advertised service classes as a list of $BleUuid.
-
-  Deprecated. Use $services instead.
-  */
-  service-classes -> List: return services
-
   /**
   Advertised services as a list of $BleUuid.
 
@@ -830,20 +841,6 @@ class AdvertisementData:
       if block.is-tx-power-level: return block.tx-power-level
     return null
 
-  /**
-  Manufacturer data as a byte array.
-
-  For backwards compatibility, returns an empty byte array if no manufacturer data is present.
-
-  Returns the concatenation of the manufacturer-id and the manufacturer-specific data.
-
-  Deprecated. Use $manufacturer-specific instead.
-  */
-  manufacturer-data -> ByteArray:
-    data-blocks.do: | block/DataBlock |
-      if block.is-manufacturer-specific: return block.data.copy
-    return ByteArray 0
-
   /**
   Calls the given $block with the first field of manufacturer specific data.
 

diff --git a/lib/ble/local.toit b/lib/ble/local.toit
@@ -57,8 +57,8 @@ class Peripheral extends Resource_:
   Throws if the adapter does not allow configuration of $interval or $connection-mode.
   */
   start-advertise
-      data/AdvertisementData
-      --scan-response/AdvertisementData?=null
+      data/Advertisement
+      --scan-response/Advertisement?=null
       --interval/Duration=DEFAULT-INTERVAL
       --connection-mode/int=BLE-CONNECT-MODE-NONE:
     if system.platform == system.PLATFORM-MACOS:
@@ -104,8 +104,8 @@ class Peripheral extends Resource_:
   Sets the connection-mode to $BLE-CONNECT-MODE-UNDIRECTIONAL.
   */
   start-advertise
-      data/AdvertisementData
-      --scan-response/AdvertisementData?=null
+      data/Advertisement
+      --scan-response/Advertisement?=null
       --interval/Duration=DEFAULT-INTERVAL
       --allow-connections/True:
     start-advertise data --scan-response=scan-response --interval=interval --connection-mode=BLE-CONNECT-MODE-UNDIRECTIONAL