Qassay 快速检测阅读器 - 软件开发工具包 (SDK)

ENThe aim of this report is to describe the software development kit to build an application based on the Bluetooth characteristics of the device and connectivity to the Qassay API.

ENThe device exposes a single service UUID: 01DEA611-EFE9-4A3A-AA30-ED10C3C84F55

ENUUID: 01DEA612-EFE9-4A3A-AA30-ED10C3C84F55

ENThe button characteristic indicates if the button inside the device is pressed. If this button is pressed it indicates that the cassette is fully inserted.
Read: 1 byte unsigned
Notify: Triggered when the button changes its status

ENUUID: 01DEA617-EFE9-4A3A-AA30-ED10C3C84F55

ENHardware & software indicates some info about the embedded firmware and the sensors built within the device.
Read: 8 bytes unsigned
Format: AAAA BB CC DD 00 00 00
  AAAA: Hardware ID (0x201 White, 0x202 Dual)
  BB: Client ID (0x01 generic, 0xFF test)
  CC: SW Minor ID
  DD: SW Major ID

ENUUID: 01DEA614-EFE9-4A3A-AA30-ED10C3C84F55

ENIndicates the battery voltage, can be used in order to determine the battery percentage in order to proceed with a reading. Note that very low levels of charge may lead to malformed readings.
Read: 2 bytes unsigned little endian (HEX)
Formula: SOC (%) = 200 * (batteryVoltage / 1000) - 730
Example: 0x960F -> swap to 0x0F96 -> DEC=3990 -> 200*(3990/1000)-730 = 68%

Thresholds:
• <3650: 0% -> Dead (block readings)
• Low battery 3750: 20% -> Low battery (Red LED)
• >4150: 100% -> Full battery (Green LED)

ENUUID: 01DEA619-EFE9-4A3A-AA30-ED10C3C84F55
For now USB connection is used only for charging, so using charging characteristics is recommended.
Read: 1 byte unsigned

ENUUID: 01DEA61A-EFE9-4A3A-AA30-ED10C3C84F55
Indicates if the battery is charging
Read: 1 byte unsigned

ENUUID: 01DEA61E-EFE9-4A3A-AA30-ED10C3C84F55
There is a characteristic that notifies whether the device is in low battery status
Read: 1 byte unsigned

ENUUID: 01DEA618-EFE9-4A3A-AA30-ED10C3C84F55
Indicates the MAC address
Read: 6 bytes unsigned

ENUUID: 01DEA615-EFE9-4A3A-AA30-ED10C3C84F55
Indicates the configuration of the sensor in the previous reading
Read: 6 bytes unsigned
Byte 0 & 1: ASTEP
Byte 2: ATIME
Byte 3: AGAIN
Byte 4: LED_DRIVE
Byte 5: 0 (raw) / 1 (normalized)

ENUUID: 01DEA613-EFE9-4A3A-AA30-ED10C3C84F55
• Write 0x04: Enables reading, next button press/release will proceed with reading
• Write 0x07: Enables White LED (when using a DUAL reader and trying to read a visible test)

ENThe spectrals characteristics allow retrieval of the readings from the sensors. Key concepts:
• Once the device is turned on, when the button is released the device will execute a reading.
• The reading process takes about 1 second, and takes 250 sensor reads, after this the characteristics will be available.
• Once the reading is finished the device will notify the F1 characteristic.
• The read operations over any of the following characteristics will return the last reading.
• There is memory limit on how many characteristics can be read at the same time (3), but it is recommended to read them one by one.
• Each characteristic represents light for a certain wavelength with an array of 250 x 16 byte unsigned integers.

EN F1: 01DEA621-EFE9-4A3A-AA30-ED10C3C84F55
F2: 01DEA622-EFE9-4A3A-AA30-ED10C3C84F55
F3: 01DEA623-EFE9-4A3A-AA30-ED10C3C84F55
F4: 01DEA624-EFE9-4A3A-AA30-ED10C3C84F55
F5: 01DEA625-EFE9-4A3A-AA30-ED10C3C84F55
F6: 01DEA626-EFE9-4A3A-AA30-ED10C3C84F55
F7: 01DEA627-EFE9-4A3A-AA30-ED10C3C84F55
F8: 01DEA628-EFE9-4A3A-AA30-ED10C3C84F55

ENRead: 500 bytes unsigned, each 2 bytes represent a point, pairwise u8 as little endian
u8 => 2^8 = 16*16 = 256
Example: "eb", "6" -> eb + 6 -> 256*6 + 235 = 1771
Notify: Only F1 sends a notification, this notification indicates that the read operations can be executed.

ENAs a summary on how to operate with the device:
• Check if the battery is not very low, otherwise stop the execution
• If DUAL device is attempting to read a visible test -> Write operation with 0x07
• Write operation with 0x04
• Wait for button notification to be triggered with false (button released)
• Wait for F1 notification to be triggered (reading completed)
• Iterate over the frequencies reading them one by one.

const mac: string = '<DEVICE_MAC>';
const service: string = '01DEA611-EFE9-4A3A-AA30-ED10C3C84F55';

read = async (frequency: string): Promise<Uint16Array> => {
  const data: DataView = await BleClient.read(mac, service, frequency);
  return new Uint16Array(data.buffer);
}

const f1: string = '01DEA621-EFE9-4A3A-AA30-ED10C3C84F55';

// Operation - 操作控制
const BLE_OP_CONTROL = '01DEA613-EFE9-4A3A-AA30-ED10C3C84F55';
const BLE_OP_CONTROL_VALUE = 0x04;
const op: Uint8Array = new Uint8Array([BLE_OP_CONTROL_VALUE]);
await BleClient.write(mac, BLE_LFT_POC, BLE_OP_CONTROL, new DataView(op.buffer));

// Reading - 读取数据
await BleClient.startNotifications(mac, service, f1, async () => {
  // Notification received, reading values are ready
  // 收到通知，读取值已就绪
  const reading: Record<string, number[]> = {};
  // Array of characteristics, from F1 to F8
  // 光谱特征数组，从 F1 到 F8
  for (let frequency of frequencies) {
    const values: Uint16Array = read(frequency)
    // Values is an array of 250 unsigned integers of this certain frequency
    // values 是该频率对应的 250 个无符号整数数组
    reading[frequency] = values;
  }
  console.log(reading);
});

ENThis section provides a brief explanation of the connection flow for the Qassay device.

ENThe device connection screen can be accessed from the "How to" screen. At this point, the connect device screen or step will load. For the Qassay to be selected for connection, we must first turn on the device. When it flashes, we select it for connection.

ENWhen the device to be connected has been selected, the battery information and the connected message will be displayed, and this function will then manage the connection.

ENThe following handler from the function is used to manage the PIN. If the device is already paired, it will not prompt for the PIN; however, it will if it has never been paired before.

ENThe method for verifying the validity of the pairing and PIN varies depending on whether it is iOS or Android, notifying the user at all times of the status of their actions with visual alerts or toasts.

ENThe FUOTA functionality is implemented so that the firmware of the device can be updated via Bluetooth using the smartphone app.

EN Step 1: Connect the device
Step 2: Retrieve HW ID and SW ID from characteristic 01DEA617-EFE9-4A3A-AA30-ED10C3C84F55
  - Bytes 1 and 2 -> HW ID
  - Bytes 4 (SW minor) and 5 (SW major)
Step 3: Convert values from HEX to DEC
Step 4: Get from public bucket firmware, filter by HW ID, get the latest UUID:
https://s3.eu-west-3.amazonaws.com/qassay.pre.public/firmwares/index.json
  - Filter the FirmwareIndex by hardwareCode (HW ID in DEC)

EN FirmwareIndex Interface:

interface FirmwareIndex {
    entries: FirmwareIndexEntry[];
}
interface FirmwareIndexEntry {
    id: number;
    code: number;
    name: string;
    uuid: string;
    hardwareCodes: number[];
    createdAt: Date;
}

interface FirmwareIndex {
    entries: FirmwareIndexEntry[];
}
interface FirmwareIndexEntry {
    id: number;
    code: number;
    name: string;
    uuid: string;
    hardwareCodes: number[];
    createdAt: Date;
}

EN Step 5: Check if the SW ID is the latest. If so, no need to update.
Step 6: Download the firmware using the UUID from previous step:
https://s3.eu-west-3.amazonaws.com/qassay.pre.public/firmwares/${firmware.uuid}/data.bin
Step 7: Add a right pad of zeros to the binary so that the file matches a multiple of 16 bytes.
Step 8: Divide the binary in chunks of 240 bytes so the data is uploaded sliced.
Step 9: Calculate number of blocks of 8 (so the progress can be tracked)

EN Step 10: Write (without response) to Base Address 2046a492-6798-422d-8dc6-0cf7d7729940
  Data: [0x02, 0x04, 0x80, 0x00, {number of blocks in hex}]
Step 11: Wait (Indicate) for Confirmation Address 2046a492-6798-422d-8dc6-0cf7d7729940
Step 12: Write (without response) binary in chunks of 240 bytes
Step 13: Wait until all the chunks have been uploaded and the progress has finished
Step 14: Read Address 2046a495-6798-422d-8dc6-0cf7d7729940 to check it matches the size of the original binary (optional, recommended especially for iOS)
Step 15: Reboot after a couple of seconds to complete update
Step 16: Connect the device again
Step 17: POST /readers/{readerId}/firmware-update-history
  Body: { "hardwareVersion": 513, "softwareVersion": 1282 }

const BLE_INSTALL_FIRMWARE_CHUNK_SIZE: number = 240;
const BLE_INSTALL_FIRMWARE_BLOCK_SIZE: number = 16;

enum BleFirmwareUpdateBaseAddressActionEnum {
    StopAllUpload = 0x00,
    StartUserDataUpload = 0x01,
    StartApplicationFileUpload = 0x02,
    EndOfFileTransfer = 0x06,
    FileUploadFinish = 0x07,
    CancelUpload = 0x08
}

export interface InstallFirmwareProgressInterface {
    step: InstallFirmwareStepEnum;
    total: number;
    uploaded: number;
}

export enum InstallFirmwareStepEnum {
    'START',                 // 开始
    'WRITE_START_FILE_UPLOAD', // 写入启动文件上传
    'WAITING_FOR_CONFIRMATION', // 等待确认
    'UPLOAD_FIRMWARE',       // 上传固件
    'WRITE_END_OF_FILE_TRANSFER', // 写入结束文件传输
    'WAITING_FOR_REBOOT',    // 等待重启
    'FINISHED',              // 完成
    'FAILED'                 // 失败
}

ENThe QC Check is a functionality that verifies if the device is working correctly after several uses. The concept of QC check stands for verification of the performance of the device, not recalibration.

EN • Scan QR code on calibration stick
• Check QR code corresponds to a calibration stick
• GET calibration stick ID from endpoint, where code is QR code: GET /calibration-stick/by-code/:code
• On-screen instructions on how to insert the QC kit (recommended)
• When the QC kit is inserted, execute the test with a button in the app
• Write byte 0x07 and then byte 0x03 to characteristic 01DEA613-EFE9-4A3A-AA30-ED10C3C84F5
• Store spectral data from F1 to F8

EN Get normalization data from Black and White:
[BLACK] Write bytes 0x05 and 0x00 to characteristic 01DEA616-EFE9-4A3A-AA30-ED10C3C84F55
Expected response: 0B XX AAAA BBBB CCCC DDDD EEEE FFFF GGGG HHHH
(F1=AAAA, F2=BBBB, etc.; each Fx is 2 bytes of normalization data for each spectral)

[WHITE] Write bytes 0x05 and 0x01 to characteristic 01DEA616-EFE9-4A3A-AA30-ED10C3C84F55
Expected response: 0B XX AAAA BBBB CCCC DDDD EEEE FFFF GGGG HHHH
(F1=AAAA, F2=BBBB, etc.; each Fx is 2 bytes of normalization data for each spectral)

{
  "data": {
    "F1": { ... },
    "F2": { ... },
    "F3": { ... },
    "F4": { ... },
    "F5": { ... },
    "F6": { ... },
    "F7": { ... },
    "F8": { ... }
  },
  "normalizationData": {
    "white": { "F1": xx, "F2": xx, "F3": xx, "F4": xx, "F5": xx, "F6": xx, "F7": xx, "F8": xx },
    "black": { "F1": xx, "F2": xx, "F3": xx, "F4": xx, "F5": xx, "F6": xx, "F7": xx, "F8": xx }
  },
  "calibrationStick": { "id": 0 },
  "reader": { "id": 0 }
}

EN • Send composed JSON to endpoints:
  POST /readers/:id/quality-checks
  POST /readers/:id/check-calibration
• Expected response with status: "Error" or "Ok"
• OK -> Success, you can keep using the device
• Error -> Failed, please check your distributor and no longer use the device

ENEvery time a device is connected, the following checks are required. These are considered functionality errors, which may get the device inoperable. It is recommended to replace the reader in these cases.

ENDuring the use of the device, the following errors from the user may arise. This is a non-exhaustive list that aims to describe the most common ones, and the advised feedback and action from the user.

EN Step 1: Retrieve the strip ID from its code (the QR code)
GET https://api.qassay.com/documentation#/Strips/StripController_getByCode
Make sure to retrieve sampleTypes from the test you read, as it will be required on next step.
You can also retrieve the "maxReactionTime", the extra time after the test reaction time has been exceeded (to be checked after reaction time has expired).
- Check Expiration date -> If expired, notify user the test is expired, and to use another test.

EN Step 2: Create the sample
POST https://api.qassay.com/documentation#/Samples/SampleController_create
Make sure to choose a sampleType from the previous step, and set it up; this sample type will then apply a corrective factor. If sample type is blood, you can predefine it. In this case, select "blood" as sampleType.

EN Step 3: Retrieve the timer for the sample you just created
GET https://api.qassay.com/documentation#/Samples/SampleController_getTimer
Once the timer ends, the maxReactionTime needs to be tracked. If it also ends, the reading needs to be disabled and the user should be asked to repeat the reading with another test.

EN Step 4: Retrieve the reader ID from its MAC address
GET https://api.qassay.com/documentation#/Readers/ReaderController_getByMac
- Check the reader exists.

EN Step 5: Once the reading is finished, ask the server to validate the reading data
POST /samples/{id}/validate

{
  "id": 0,
  "attemptNumber": 0,
  "key": "string",
  "result": {
    "id": 0,
    "status": "Error",  // Error or OK
    "error": "ExtractionTooFast"  // Error codes
  },
  "createdAt": "2025-06-16T09:57:23.766Z",
  "updatedAt": "2025-06-16T09:57:23.766Z"
}

{
  "id": 0,
  "attemptNumber": 0,
  "key": "string",
  "result": {
    "id": 0,
    "status": "Error",  // Error 或 OK
    "error": "ExtractionTooFast"  // 错误码
  },
  "createdAt": "2025-06-16T09:57:23.766Z",
  "updatedAt": "2025-06-16T09:57:23.766Z"
}

EN Step 6: Upload the data to the server
POST https://api.qassay.com/documentation#/Samples/SampleController_upload
Once this is done, the server will start processing the sample. It takes a couple of seconds until the reading is available and processed.

ENFollowing properties are expected for tests (strip-type). These are examples for some markers already on the Qassay platform. A similar configuration may be set up for the custom platform.

ENAvailable result units: %, mg/L, ug/mL, ng/mL, TCID50/mL, uUi/mL, g/dL, pg/mL, UI/L, mUI/L, ug/dL, ug/g, U/mL, mg/dL, BAU/mL, mUI/mL, pmol/mL, ng/L, g/L, mmol/L, RBC/uL, WBC/uL, nmol/L

ENTests are manufactured in manufacturing batches, and identified via QR printed on the cassette.

ENManagement rule: Future requirement-analysis notes, command-integration decisions, translation fixes, and interface clarifications derived from this document should append a row to Revision History. File backup, restore, or migration actions should also append a row to this Document Management Log.