[api] Add 48-bit MAC address varint fast path for BLE advertisements

Adds a (mac_address) field option that switches uint64 fields holding
48-bit MAC addresses to a specialized varint encoder. The fast path
emits exactly 7 bytes when bits [42..47] are non-zero (the common case
for real MACs, since OUIs occupy the top 24 bits) -- one bounds check
and 7 independent stores instead of the 7-iteration shift+branch loop.
calc_uint64_48bit_force mirrors the same fast path in size calculation.

Applied to BluetoothLERawAdvertisement.address, the per-advertisement
address encode in BluetoothLERawAdvertisementsResponse drops from a
serialized per-byte loop to straight-line code.

esphome/components/api/api.proto

@@ -1628,7 +1628,7 @@ message BluetoothLEAdvertisementResponse {
 
 message BluetoothLERawAdvertisement {
   option (inline_encode) = true;
-  uint64 address = 1 [(force) = true];
+  uint64 address = 1 [(force) = true, (mac_address) = true];
   sint32 rssi = 2 [(force) = true];
   uint32 address_type = 3 [(max_value) = 4];
 

esphome/components/api/api_options.proto

@@ -110,4 +110,10 @@ extend google.protobuf.FieldOptions {
     // length varint calculations and direct byte writes, since the length
     // varint is guaranteed to be 1 byte.
     optional uint32 max_data_length = 50018;
+
+    // mac_address: Field is a 48-bit MAC address stored in a uint64.
+    // Emits encode_varint_raw_48bit which has a 7-byte fast path that avoids
+    // the per-byte loop when the upper bits are non-zero (the common case
+    // for real MAC addresses, since OUIs occupy the top 24 bits).
+    optional bool mac_address = 50019 [default=false];
 }

esphome/components/api/api_pb2.cpp

@@ -2348,7 +2348,7 @@ BluetoothLERawAdvertisementsResponse::encode(ProtoWriteBuffer &buffer PROTO_ENCO
     uint8_t *len_pos = pos;
     ProtoEncode::reserve_byte(pos PROTO_ENCODE_DEBUG_ARG);
     ProtoEncode::write_raw_byte(pos PROTO_ENCODE_DEBUG_ARG, 8);
-    ProtoEncode::encode_varint_raw_64(pos PROTO_ENCODE_DEBUG_ARG, sub_msg.address);
+    ProtoEncode::encode_varint_raw_48bit(pos PROTO_ENCODE_DEBUG_ARG, sub_msg.address);
     ProtoEncode::write_raw_byte(pos PROTO_ENCODE_DEBUG_ARG, 16);
     ProtoEncode::encode_varint_raw_short(pos PROTO_ENCODE_DEBUG_ARG, encode_zigzag32(sub_msg.rssi));
     if (sub_msg.address_type) {
@@ -2369,7 +2369,7 @@ BluetoothLERawAdvertisementsResponse::calculate_size() const {
   for (uint16_t i = 0; i < this->advertisements_len; i++) {
     auto &sub_msg = this->advertisements[i];
     size += 2;
-    size += ProtoSize::calc_uint64_force(1, sub_msg.address);
+    size += ProtoSize::calc_uint64_48bit_force(1, sub_msg.address);
     size += ProtoSize::calc_sint32_force(1, sub_msg.rssi);
     size += sub_msg.address_type ? 2 : 0;
     size += 2 + sub_msg.data_len;

esphome/components/api/proto.h

@@ -342,6 +342,26 @@ class ProtoEncode {
     }
     encode_varint_raw_loop(pos PROTO_ENCODE_DEBUG_ARG, value);
   }
+  /// Encode a 48-bit MAC address (stored in a uint64) as varint.
+  /// Real MAC addresses occupy the full 48 bits (OUI in upper 24), so the
+  /// fast path -- any non-zero bit in bits [42..47] -- emits exactly 7 bytes
+  /// with no per-byte branch. Falls back to the general loop otherwise.
+  static inline void ESPHOME_ALWAYS_INLINE encode_varint_raw_48bit(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM,
+                                                                   uint64_t value) {
+    if (value >= (1ULL << 42)) [[likely]] {
+      PROTO_ENCODE_CHECK_BOUNDS(pos, 7);
+      pos[0] = static_cast<uint8_t>(value | 0x80);
+      pos[1] = static_cast<uint8_t>((value >> 7) | 0x80);
+      pos[2] = static_cast<uint8_t>((value >> 14) | 0x80);
+      pos[3] = static_cast<uint8_t>((value >> 21) | 0x80);
+      pos[4] = static_cast<uint8_t>((value >> 28) | 0x80);
+      pos[5] = static_cast<uint8_t>((value >> 35) | 0x80);
+      pos[6] = static_cast<uint8_t>(value >> 42);
+      pos += 7;
+      return;
+    }
+    encode_varint_raw_64(pos PROTO_ENCODE_DEBUG_ARG, value);
+  }
   static inline void ESPHOME_ALWAYS_INLINE encode_field_raw(uint8_t *__restrict__ &pos PROTO_ENCODE_DEBUG_PARAM,
                                                             uint32_t field_id, uint32_t type) {
     encode_varint_raw(pos PROTO_ENCODE_DEBUG_ARG, (field_id << 3) | type);
@@ -817,6 +837,13 @@ class ProtoSize {
   static constexpr inline uint32_t ESPHOME_ALWAYS_INLINE calc_uint64_force(uint32_t field_id_size, uint64_t value) {
     return field_id_size + varint(value);
   }
+  /// 48-bit MAC address variant: matches encode_varint_raw_48bit's fast path.
+  /// When value uses any of bits [42..47] the encoded varint is 7 bytes;
+  /// otherwise fall back to the general size calculation.
+  static constexpr inline uint32_t ESPHOME_ALWAYS_INLINE calc_uint64_48bit_force(uint32_t field_id_size,
+                                                                                 uint64_t value) {
+    return field_id_size + (value >= (1ULL << 42) ? 7 : varint(value));
+  }
   static constexpr uint32_t calc_length(uint32_t field_id_size, size_t len) {
     return len ? field_id_size + varint(static_cast<uint32_t>(len)) + static_cast<uint32_t>(len) : 0;
   }

script/api_protobuf/api_protobuf.py

@@ -184,6 +184,11 @@ class TypeInfo(ABC):
         """Check if this field should always be encoded (skip zero/empty check)."""
         return get_field_opt(self._field, pb.force, False)
 
+    @property
+    def mac_address(self) -> bool:
+        """Check if this uint64 field is a 48-bit MAC address (use 7-byte fast path)."""
+        return get_field_opt(self._field, pb.mac_address, False)
+
     @property
     def max_value(self) -> int | None:
         """Get the max_value option for this field, or None if not set."""
@@ -665,8 +670,22 @@ class UInt64Type(VarintTypeMixin, TypeInfo):
         return o
 
     def get_size_calculation(self, name: str, force: bool = False) -> str:
+        if self.mac_address and force:
+            field_id_size = self.calculate_field_id_size()
+            return (
+                f"size += ProtoSize::calc_uint64_48bit_force({field_id_size}, {name});"
+            )
         return self._get_simple_size_calculation(name, force, "uint64")
 
+    @property
+    def RAW_ENCODE_MAP(self) -> dict[str, str]:  # noqa: N802
+        if self.mac_address:
+            return {
+                **TypeInfo.RAW_ENCODE_MAP,
+                "encode_uint64": "ProtoEncode::encode_varint_raw_48bit(pos, {value});",
+            }
+        return TypeInfo.RAW_ENCODE_MAP
+
     def get_estimated_size(self) -> int:
         return self.calculate_field_id_size() + 3  # field ID + 3 bytes typical varint