ES-CS20M: broadcast-only variant (non-connectable) findings

[KristianP26]

Cross-project findings: ES-CS20M hardware variants

I maintain ble-scale-sync (Node.js/TypeScript alternative for BLE scales) and we've been debugging the same ES-CS20M problems in our issue #34. Sharing our findings here since they're relevant to openScale users.

The ES-CS20M ships in at least 3 hardware variants

Variant	Advertised name	Protocol	Services	GATT connectable
1	"QN-Scale"	QN/Qingniu	0xFFE0 / 0xFFF0	Yes
2	"ES-CS20M" or unnamed	Yunmai	0x1A10	Yes
3	"Renpho Scale" or unnamed	QN/Qingniu (broadcast)	none	No (ADV_NONCONN_IND)

Variant 1 works with the QN handler. Variant 2 was fixed by PR #1300. Variant 3 is the problematic one.

Variant 3: broadcast-only (non-connectable)

Some ES-CS20M units advertise as non-connectable (ADV_NONCONN_IND). No BLE stack on any OS can establish a GATT connection to these devices. This explains the "unable to connect" reports from users where the scale is visible but connection always fails, on both Windows and Android.

These devices use QN/Qingniu manufacturer data advertisements with the AABB marker:

FF FF AA BB [MAC 6 bytes] [data bytes...] [stability byte near end]

Impedance is not available in broadcast mode (confirmed independently by two users).

Weight byte position is still unconfirmed. Our initial assumption (bytes [10-11] as big-endian uint16 / 100) produced incorrect readings: 135 kg for a user who actually weighs ~70 kg. We are currently collecting controlled data samples (known weights + raw hex) from a user with this variant to determine the correct byte positions and divisor. Will update once the format is confirmed.

Two raw samples captured so far:

Idle (stable):      FF FF AA BB ED 67 39 DC 60 60 08 D6 00 00 FF FF FF 02 00 18 1A 4C 09 03 FC 01
With weight (meas): FF FF AA BB ED 67 39 DC 60 60 13 00 00 00 FF FF FF 02 00 55 05 4C 09 03 27 00

Bytes that change between samples: [10-11], [19-20], [24], [25]. The last byte appears to be a stability flag (0x01 = stable, 0x00 = measuring).

How to identify the variant

The easiest way is to check the advertisement type in nRF Connect:

• Connectable + service UUID 0xFFE0/0xFFF0 = Variant 1 (QN handler)
• Connectable + service UUID 0x1A10 = Variant 2 (ES-CS20M handler)
• Non-connectable + manufacturer data starting with AABB = Variant 3 (needs broadcast parser)

Implementation in ble-scale-sync

Added broadcast mode support that reads weight from advertisement data without requiring a GATT connection. Body composition is estimated via the Deurenberg BMI formula since impedance is unavailable. The broadcast parser is functional but the weight byte layout needs correction (see above). This also includes a BLE diagnostic tool that detects broadcast-only devices and shows parsed weight from advertisements.

Possibly related: #1302 (unhandled opcode 0xa1)

Issue #1302 shows a connectable QN variant ("Renpho-Scale", manufacturer: "Qing Niu Technology") that completes the full handshake (0x12 → 0x13 → 0x14 → 0x20 → 0x21 → 0xA0) but the 0xA1 response is unhandled. The 0xA1 frame is likely the ACK to the user profile command (0xA0). After this, no weight data arrives. This might be a separate issue with the QN handler not completing the handshake for certain firmware versions.

[oliexdev]

First of all interessting project you have.

One possible path here is that this might already be close to working via the existing OkOkHandler, if it accepts the AA BB marker and parses the payload correctly — but I don’t have access to a the actual problematic scale to verify this. If someone with the current broadcast-only ES-CS20M variant can test this and/or adjust the handler accordingly, a PR would be very welcome.

This is the following changes that was generated by AI:

/*
 * openScale
 * Copyright (C) 2025 olie.xdev <olie.xdeveloper@googlemail.com>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
package com.health.openscale.core.bluetooth.scales

import android.bluetooth.le.ScanResult
import android.util.SparseArray
import com.health.openscale.core.bluetooth.data.ScaleMeasurement
import com.health.openscale.core.bluetooth.data.ScaleUser
import com.health.openscale.core.data.WeightUnit
import com.health.openscale.core.service.ScannedDeviceInfo
import com.health.openscale.core.utils.ConverterUtils

/**
 * Unified OKOK + QN broadcast handler with dynamic display name:
 *  - "OKOK V20"  (manufacturer id 0x20CA): stable flag + XOR checksum
 *  - "OKOK V11"  (manufacturer id 0x11CA): XOR checksum, unit & resolution in body properties
 *  - "OKOK VF0"  (manufacturer id 0xF0FF): simple weight field
 *  - "OKOK C0" (any manufacturer id where low byte == 0xC0): MAC-embedded, unit & resolution in attrib
 *  - "QN Broadcast" (data starts with FF FF AA BB): QN/Qingniu broadcast-only variant (Issue #1308)
 *
 * Link mode: BROADCAST_ONLY (no GATT connection).
 */
class OkOkHandler : ScaleDeviceHandler() {

    // Known manufacturer ids
    private val MANUF_V20 = 0x20ca
    private val MANUF_V11 = 0x11ca
    private val MANUF_VF0 = 0xf0ff

    // V20 indices
    private val IDX_V20_FINAL = 6
    private val IDX_V20_WEIGHT_MSB = 8
    private val IDX_V20_WEIGHT_LSB = 9
    private val IDX_V20_IMPEDANCE_MSB = 10
    private val IDX_V20_IMPEDANCE_LSB = 11
    private val IDX_V20_CHECKSUM = 12

    // V11 indices
    private val IDX_V11_WEIGHT_MSB = 3
    private val IDX_V11_WEIGHT_LSB = 4
    private val IDX_V11_BODY_PROPERTIES = 9
    private val IDX_V11_CHECKSUM = 16

    // VF0 indices
    private val IDX_VF0_WEIGHT_MSB = 3
    private val IDX_VF0_WEIGHT_LSB = 2

    // 0xC0 indices
    private val IDX_WEIGHT_MSB = 0
    private val IDX_WEIGHT_LSB = 1
    private val IDX_ATTRIB     = 6
    private val UNIT_KG   = 0
    private val UNIT_JIN  = 1
    private val UNIT_LB   = 2
    private val UNIT_STLB = 3

    // QN Broadcast (AA BB) indices
    // Based on Issue #1308 raw samples:
    // Idle:   FF FF AA BB ED 67 39 DC 60 60 08 D6 00 00 FF FF FF 02 00 18 1A 4C 09 03 FC 01
    // Meas:   FF FF AA BB ED 67 39 DC 60 60 13 00 00 00 FF FF FF 02 00 55 05 4C 09 03 27 00
    //                                          ^^ ^^                   ^^ ^^ ^^       ^^ ^^
    //                                       bytes 10-11              bytes 19-20     24-25
    private val IDX_QN_STABILITY = 25  // Last byte: 0x01 = stable, 0x00 = measuring

    // WEIGHT POSITION IS STILL UNCONFIRMED
    // Issue reports bytes[10-11] big-endian /100 gives wrong values (135kg instead of 70kg)
    // Alternative candidates: bytes[19-20] or combination of changing bytes
    // Current implementation uses bytes[10-11] as fallback until correct format is confirmed
    private val IDX_QN_WEIGHT_CANDIDATE_1_MSB = 10
    private val IDX_QN_WEIGHT_CANDIDATE_1_LSB = 11
    private val IDX_QN_WEIGHT_CANDIDATE_2_MSB = 19
    private val IDX_QN_WEIGHT_CANDIDATE_2_LSB = 20

    private val NamelessAlias = "OKOK Nameless"

    /**
     * Decide support + build a *dynamic* displayName based on manufacturer data present
     * in the advertisement that matched this device.
     */
    override fun supportFor(device: ScannedDeviceInfo): DeviceSupport? {
        val m = device.manufacturerData ?: return null

        if (device.name.isEmpty() && containsLowByteC0(m))
            device.name = NamelessAlias
        val name = device.name

        // Check for QN broadcast marker (FF FF AA BB)
        val hasQNBroadcast = hasQNBroadcastMarker(m)

        // Check for OKOK variants
        val supportsOkok = name.equals(NamelessAlias)
                || name.equals("ADV")
                || name.equals("Chipsea-BLE")
                || name.startsWith("Yoda0", ignoreCase = true)
                || name.startsWith("Yoda1", ignoreCase = true)

        if (!supportsOkok && !hasQNBroadcast) return null

        val variantName = when {
            hasKey(m, MANUF_V20) -> "OKOK V20"
            hasKey(m, MANUF_V11) -> "OKOK V11"
            hasKey(m, MANUF_VF0) -> "OKOK VF0"
            containsLowByteC0(m) -> "OKOK C0"
            hasQNBroadcast -> "QN Broadcast"
            else -> null
        } ?: return null

        // What the device can in theory (capabilities) vs what we actually implement now (implemented)
        val capabilities: Set<DeviceCapability> = when {
            hasKey(m, MANUF_V20) -> setOf(
                DeviceCapability.LIVE_WEIGHT_STREAM,
                DeviceCapability.BODY_COMPOSITION
            )
            else -> setOf(DeviceCapability.LIVE_WEIGHT_STREAM)
        }

        val implemented: Set<DeviceCapability> = setOf(
            DeviceCapability.LIVE_WEIGHT_STREAM
        )

        return DeviceSupport(
            displayName = variantName,
            capabilities = capabilities,
            implemented = implemented,
            linkMode = LinkMode.BROADCAST_ONLY
        )
    }

    /**
     * Parse manufacturer frames from advertisements; publish on first stable result.
     */
    override fun onAdvertisement(result: ScanResult, user: ScaleUser): BroadcastAction {
        val m = result.scanRecord?.manufacturerSpecificData ?: return BroadcastAction.IGNORED

        // Try QN broadcast first (new variant)
        parseQNBroadcast(m)?.let { kg ->
            publish(ScaleMeasurement().apply { userId = user.id; weight = kg })
            return BroadcastAction.CONSUMED_STOP
        }

        // Try OKOK formats
        parseV20(m)?.let { kg ->
            publish(ScaleMeasurement().apply { userId = user.id; weight = kg })
            return BroadcastAction.CONSUMED_STOP
        }
        parseV11(m)?.let { kg ->
            publish(ScaleMeasurement().apply { userId = user.id; weight = kg })
            return BroadcastAction.CONSUMED_STOP
        }
        parseVF0(m)?.let { kg ->
            publish(ScaleMeasurement().apply { userId = user.id; weight = kg })
            return BroadcastAction.CONSUMED_STOP
        }

        // Fallback: 0xC0 vendor
        parseC0(m)?.let { kg ->
            publish(ScaleMeasurement().apply { userId = user.id; weight = kg })
            return BroadcastAction.CONSUMED_STOP
        }

        return BroadcastAction.IGNORED
    }

    // --- Parsers --------------------------------------------------------------

    /**
     * Parse QN/Qingniu broadcast format (Issue #1308 Variant 3).
     *
     * Format: FF FF AA BB [MAC 6 bytes] [data bytes...] [stability byte]
     *
     * WARNING: Weight byte position is UNCONFIRMED!
     * Current implementation tries two candidate positions:
     * - Candidate 1: bytes[10-11] big-endian / 100 (reported as incorrect in issue)
     * - Candidate 2: bytes[19-20] big-endian / 100 (observed to change in samples)
     *
     * This parser uses a heuristic: try both positions and accept values in plausible range.
     * Once correct format is confirmed in issue, this should be updated.
     */
    private fun parseQNBroadcast(m: SparseArray<ByteArray>): Float? {
        val data = getQNBroadcastData(m) ?: return null

        // Minimum length check (26 bytes based on samples)
        if (data.size < 26) return null

        // Check stability flag (last byte)
        val stable = data[IDX_QN_STABILITY].toInt() and 0xFF == 0x01
        if (!stable) return null

        // TENTATIVE: Try both candidate positions and use plausible value
        // This is a WORKAROUND until correct byte positions are confirmed

        // Candidate 1: bytes[10-11] (reported incorrect in issue - gives 135kg for 70kg user)
        val weight1 = u16be(data[IDX_QN_WEIGHT_CANDIDATE_1_MSB], data[IDX_QN_WEIGHT_CANDIDATE_1_LSB]) / 100.0f

        // Candidate 2: bytes[19-20] (changes in sample data)
        val weight2 = u16be(data[IDX_QN_WEIGHT_CANDIDATE_2_MSB], data[IDX_QN_WEIGHT_CANDIDATE_2_LSB]) / 100.0f

        // Accept weight in plausible range (20kg - 200kg)
        // Prefer candidate 2 if both are plausible (based on issue report that [10-11] is wrong)
        return when {
            weight2 in 20f..200f -> {
                logD("QN Broadcast: using candidate 2 (bytes[19-20]) = ${weight2}kg")
                weight2
            }
            weight1 in 20f..200f -> {
                logD("QN Broadcast: using candidate 1 (bytes[10-11]) = ${weight1}kg (may be incorrect)")
                weight1
            }
            else -> {
                logD("QN Broadcast: no plausible weight found (w1=${weight1}kg, w2=${weight2}kg)")
                null
            }
        }
    }

    private fun parseV20(m: SparseArray<ByteArray>): Float? {
        val data = getManuf(m, MANUF_V20) ?: return null
        if (data.size != 19) return null

        val finalFlag = (data[IDX_V20_FINAL].toInt() and 0x01) != 0
        if (!finalFlag) return null

        // XOR checksum including implicit version 0x20
        var checksum = 0x20
        for (i in 0 until IDX_V20_CHECKSUM) checksum = checksum xor (data[i].toInt() and 0xFF)
        val got = data[IDX_V20_CHECKSUM].toInt() and 0xFF
        if (got != (checksum and 0xFF)) return null

        val divider = if ((data[IDX_V20_FINAL].toInt() and 0x04) != 0) 100.0f else 10.0f
        val weightRaw = u16be(data[IDX_V20_WEIGHT_MSB], data[IDX_V20_WEIGHT_LSB])

        // If needed later:
        // val imp = u16be(data[IDX_V20_IMPEDANCE_MSB], data[IDX_V20_IMPEDANCE_LSB]) / 10.0f

        return weightRaw / divider
    }

    private fun parseV11(m: SparseArray<ByteArray>): Float? {
        val data = getManuf(m, MANUF_V11) ?: return null
        // legacy length check: IDX_V11_CHECKSUM + 6 + 1 = 23 bytes
        if (data.size != IDX_V11_CHECKSUM + 6 + 1) return null

        // XOR checksum with implicit 0xCA ^ 0x11
        var checksum = 0xCA xor 0x11
        for (i in 0 until IDX_V11_CHECKSUM) checksum = checksum xor (data[i].toInt() and 0xFF)
        val got = data[IDX_V11_CHECKSUM].toInt() and 0xFF
        if (got != (checksum and 0xFF)) return null

        val props = data[IDX_V11_BODY_PROPERTIES].toInt() and 0xFF

        // resolution ((props >> 1) & 3)
        var divider = when ((props shr 1) and 0x3) {
            0 -> 10.0f
            1 -> 1.0f
            2 -> 100.0f
            else -> 10.0f
        }

        var weight = u16be(data[IDX_V11_WEIGHT_MSB], data[IDX_V11_WEIGHT_LSB])

        // unit ((props >> 3) & 3)
        return when ((props shr 3) and 0x3) {
            UNIT_KG -> weight / divider
            UNIT_JIN -> weight / (divider * 2.0f)
            UNIT_LB -> (weight / divider) / 2.204623f
            UNIT_STLB -> {
                val stones = (weight shr 8)
                val pounds = (weight and 0xFF) / divider
                stones * 6.350293f + pounds * 0.453592f
            }
            else -> null
        }
    }

    private fun parseVF0(m: SparseArray<ByteArray>): Float? {
        val data = getManuf(m, MANUF_VF0) ?: return null
        if (data.size < 4) return null
        val raw = u16be(data[IDX_VF0_WEIGHT_MSB], data[IDX_VF0_WEIGHT_LSB])
        return raw / 10.0f
    }

    private fun parseC0(m: SparseArray<ByteArray>): Float? {
        val key = firstKeyWithLowByteC0(m) ?: return null
        val data = m.get(key) ?: return null
        if (data.size < 13) return null

        val attrib = data[IDX_ATTRIB].toInt() and 0xFF
        val isStable = (attrib and 0x01) != 0
        if (!isStable) return null

        val divider = when ((attrib shr 1) and 0x3) {
            0 -> 10f
            1 -> 1f
            2 -> 100f
            else -> 10f
        }

        return when ((attrib shr 3) and 0x3) {
            UNIT_KG -> {
                val raw = u16be(data[IDX_WEIGHT_MSB], data[IDX_WEIGHT_LSB])
                raw / divider
            }
            UNIT_JIN -> {
                val raw = u16be(data[IDX_WEIGHT_MSB], data[IDX_WEIGHT_LSB])
                raw / divider / 2
            }
            UNIT_LB -> {
                val raw = u16be(data[IDX_WEIGHT_MSB], data[IDX_WEIGHT_LSB])
                ConverterUtils.toKilogram(raw / divider, WeightUnit.LB)
            }
            UNIT_STLB -> {
                val stones = data[IDX_WEIGHT_MSB].toInt() and 0xFF
                val pounds = (data[IDX_WEIGHT_LSB].toInt() and 0xFF) / divider
                stones * 6.350293f + pounds * 0.453592f
            }
            else -> null
        }
    }

    // --- utils ----------------------------------------------------------------

    private fun hasKey(sa: SparseArray<ByteArray>, key: Int): Boolean =
        sa.indexOfKey(key) >= 0

    private fun getManuf(sa: SparseArray<ByteArray>, key: Int): ByteArray? =
        if (sa.indexOfKey(key) >= 0) sa.get(key) else null

    private fun containsLowByteC0(sa: SparseArray<ByteArray>): Boolean {
        for (i in 0 until sa.size()) if ((sa.keyAt(i) and 0xFF) == 0xC0) return true
        return false
    }

    private fun firstKeyWithLowByteC0(sa: SparseArray<ByteArray>): Int? {
        for (i in 0 until sa.size()) {
            val k = sa.keyAt(i)
            if ((k and 0xFF) == 0xC0) return k
        }
        return null
    }

    /**
     * Check if any manufacturer data starts with FF FF AA BB (QN broadcast marker).
     */
    private fun hasQNBroadcastMarker(sa: SparseArray<ByteArray>): Boolean {
        for (i in 0 until sa.size()) {
            val data = sa.valueAt(i)
            if (data.size >= 4 &&
                data[0].toInt() and 0xFF == 0xFF &&
                data[1].toInt() and 0xFF == 0xFF &&
                data[2].toInt() and 0xFF == 0xAA &&
                data[3].toInt() and 0xFF == 0xBB) {
                return true
            }
        }
        return false
    }

    /**
     * Get the manufacturer data that starts with FF FF AA BB.
     */
    private fun getQNBroadcastData(sa: SparseArray<ByteArray>): ByteArray? {
        for (i in 0 until sa.size()) {
            val data = sa.valueAt(i)
            if (data.size >= 4 &&
                data[0].toInt() and 0xFF == 0xFF &&
                data[1].toInt() and 0xFF == 0xFF &&
                data[2].toInt() and 0xFF == 0xAA &&
                data[3].toInt() and 0xFF == 0xBB) {
                return data
            }
        }
        return null
    }

    private fun u16be(msb: Byte, lsb: Byte): Int =
        ((msb.toInt() and 0xFF) shl 8) or (lsb.toInt() and 0xFF)
}

Please keep us updated once you’ve confirmed the correct weight byte layout/divisor from controlled samples — that would make implementing much easier.

Thanks again for sharing this!

[KristianP26]

Update from ble-scale-sync testing:

The two affected users (@Tosiman-Global and @BenBaril83) have since tested further. The root cause is now confirmed: their ES-CS20M units advertise as non-connectable (ADV_NONCONN_IND). No BLE stack on any platform can establish a GATT connection to these devices.

@Tosiman-Global tested with the openScale dev APK and confirmed it does not work either. The connection fails for the same reason: the scale firmware only supports broadcast-mode advertisements, not connectable ones.

On the ble-scale-sync side, we have added broadcast-mode support that reads weight directly from the AABB manufacturer data advertisements. The weight byte layout is still being validated with controlled samples (known weights vs raw hex). Will update this issue once the correct byte positions and divisor are confirmed, which should help with the OkOk handler implementation suggested above.

[oliexdev]

@Tosiman-Global or somebody else with the mentioned scale have to test it with the above code changes, I didn't have these changes in the dev version yet.