Kể từ ngày 27 tháng 3 năm 2025, bạn nên sử dụng android-latest-release thay vì aosp-main để xây dựng và đóng góp cho AOSP. Để biết thêm thông tin, hãy xem phần Thay đổi đối với AOSP.

Trang này được dịch bởi Cloud Translation API.

Sensors HAL 1.0
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Giao diện HAL của cảm biến, được khai báo trong sensors.h, đại diện cho giao diện giữa khung Android và phần mềm dành riêng cho phần cứng. Việc triển khai HAL (Lớp trừu tượng phần cứng) phải xác định từng hàm đã khai báo trong sensor.h. Các chức năng chính là:

get_sensors_list – Trả về danh sách tất cả cảm biến.
activate – Bắt đầu hoặc dừng cảm biến.
batch – Đặt các thông số của cảm biến, chẳng hạn như tần suất lấy mẫu và độ trễ báo cáo tối đa.
setDelay – Chỉ dùng trong HAL phiên bản 1.0. Đặt tần suất lấy mẫu cho một cảm biến cụ thể.
flush – Xoá FIFO của cảm biến được chỉ định và báo cáo một lượt xả nước đã hoàn tất khi quá trình này hoàn tất.
poll – Trả về các sự kiện cảm biến hiện có.

Quá trình triển khai phải an toàn cho luồng và cho phép gọi các hàm này từ các chuỗi khác nhau.

Giao diện cũng xác định một số loại được các hàm đó sử dụng. Các loại chính là:

sensors_module_t
sensors_poll_device_t
sensor_t
sensors_event_t

Ngoài các phần dưới đây, hãy xem sensors.h để biết thêm thông tin về các loại đó.

get_sensors_list(danh_sách)

int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t
  const** list);

Cung cấp danh sách cảm biến do HAL (Lớp trừu tượng phần cứng) triển khai. Vui lòng xem sensor_t để biết chi tiết về cách xác định cảm biến.

Thứ tự xuất hiện của cảm biến trong danh sách là thứ tự mà cảm biến sẽ được báo cáo cho các ứng dụng. Thông thường, các cảm biến cơ sở trước tiên là cảm biến tổng hợp.

Nếu một số cảm biến có cùng loại cảm biến và thuộc tính đánh thức, thì cảm biến đầu tiên trong danh sách được gọi là cảm biến "mặc định". Đây là URL được trả về bởi getDefaultSensor(int sensorType, bool wakeUp).

Hàm này trả về số lượng cảm biến trong danh sách.

kích hoạt(cảm biến, true/false)

int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int
  enabled);

Kích hoạt hoặc huỷ kích hoạt cảm biến.

sensor_handle là tay cầm của cảm biến để kích hoạt/huỷ kích hoạt. Tay điều khiển của cảm biến được xác định bằng trường handle của cấu trúc sensor_t.

enabled được đặt thành 1 để bật hoặc 0 để tắt cảm biến.

Các cảm biến một lần tự động tự huỷ kích hoạt khi nhận được một sự kiện và vẫn phải chấp nhận bị huỷ kích hoạt thông qua lệnh gọi đến activate(..., enabled=0).

Các cảm biến không đánh thức không bao giờ ngăn SoC chuyển sang chế độ tạm ngưng; tức là HAL sẽ không giữ khoá chế độ thức một phần thay mặt cho các ứng dụng.

Khi liên tục phân phối sự kiện, cảm biến đánh thức có thể ngăn SoC chuyển sang chế độ tạm ngưng, nhưng nếu không cần phân phối sự kiện nào, thì bạn phải nhả một phần khoá chế độ thức.

Nếu enabled là 1 và cảm biến đã được kích hoạt, thì hàm này sẽ không hoạt động và thành công.

Nếu enabled là 0 và cảm biến đã bị vô hiệu hoá, thì hàm này sẽ không hoạt động và thành công.

Hàm này trả về 0 nếu thành công và số lỗi âm nếu không.

hàng loạt(cảm biến, cờ, khoảng thời gian lấy mẫu, độ trễ báo cáo tối đa)

int (*batch)(
     struct sensors_poll_device_1* dev,
     int sensor_handle,
     int flags,
     int64_t sampling_period_ns,
     int64_t max_report_latency_ns);

Đặt thông số của cảm biến, bao gồm tần suất lấy mẫu và báo cáo tối đa . Bạn có thể gọi hàm này trong khi cảm biến đang được kích hoạt, trong trường hợp này, hàm này không được làm mất bất kỳ phép đo cảm biến nào: Việc chuyển đổi từ tốc độ lấy mẫu này sang tốc độ lấy mẫu khác không được làm mất sự kiện, cũng như không được chuyển đổi từ độ trễ báo cáo tối đa cao sang độ trễ báo cáo tối đa thấp.

sensor_handle là tên của cảm biến cần định cấu hình.

flags hiện không được sử dụng.

sampling_period_ns là khoảng thời gian lấy mẫu mà cảm biến sẽ chạy, tính bằng nano giây. Hãy xem phần Sample_period_ns để biết chi tiết hơn.

max_report_latency_ns là thời gian tối đa mà các sự kiện có thể bị trễ trước khi được báo cáo thông qua HAL, tính bằng nano giây. Xem max_report_Latency_ns để biết thêm chi tiết.

Hàm này trả về 0 khi thành công và nếu không thì trả về số lỗi âm.

setDelay(cảm biến, khoảng thời gian lấy mẫu)

int (*setDelay)(
     struct sensors_poll_device_t *dev,
     int sensor_handle,
     int64_t sampling_period_ns);

Sau phiên bản HAL 1.0, chức năng này không được dùng nữa và không bao giờ được gọi. Thay vào đó, hàm batch được gọi để đặt tham số sampling_period_ns.

Trong HAL phiên bản 1.0, setDelay được sử dụng thay vì hàng loạt để đặt sampling_period_ns.

flush(sensor)

int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);

Thêm sự kiện hoàn tất xả vào cuối FIFO phần cứng cho cảm biến đã chỉ định và xả FIFO; các sự kiện đó được phân phối như bình thường (tức là như thể độ trễ báo cáo tối đa đã hết hạn) và bị xoá khỏi FIFO.

Việc xả xảy ra không đồng bộ (tức là hàm này phải trả về ngay lập tức). Nếu quá trình triển khai sử dụng một FIFO duy nhất cho một số cảm biến, thì FIFO đó sẽ được xoá và sự kiện hoàn tất xoá chỉ được thêm cho cảm biến được chỉ định.

Nếu cảm biến được chỉ định không có FIFO (không có khả năng tải vào bộ đệm) hoặc nếu FIFO, trống tại thời điểm gọi, flush vẫn phải thành công và gửi một sự kiện hoàn tất xả nước cho cảm biến đó. Điều này áp dụng cho tất cả các cảm biến khác so với cảm biến một lần.

Khi flush được gọi, ngay cả khi một sự kiện xả đã có trong FIFO cho cảm biến đó, bạn vẫn phải tạo thêm một sự kiện và thêm vào cuối FIFO, đồng thời phải xả FIFO. Số lệnh gọi flush phải bằng số sự kiện hoàn tất xả được tạo.

flush không áp dụng cho cảm biến một lần; nếu sensor_handle tham chiếu đến cảm biến một lần, thì flush phải trả về -EINVAL và không tạo bất kỳ sự kiện siêu dữ liệu hoàn chỉnh nào.

Hàm này trả về 0 khi thành công, trả về -EINVAL nếu cảm biến được chỉ định là cảm biến một lần hoặc không được bật cùng với số lỗi âm.

poll()

int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int
  count);

Trả về một mảng dữ liệu cảm biến bằng cách điền đối số data. Hàm này phải chặn cho đến khi có sự kiện. Phương thức này sẽ trả về số lượng sự kiện được đọc khi thành công hoặc số lỗi âm trong trường hợp xảy ra lỗi.

Số lượng sự kiện được trả về trong data phải nhỏ hơn hoặc bằng đối số count. Hàm này sẽ không bao giờ trả về 0 (không có sự kiện nào).

Trình tự lệnh gọi

Khi thiết bị khởi động, get_sensors_list sẽ được gọi.

Khi một cảm biến được kích hoạt, hàm batch sẽ được gọi bằng tham số được yêu cầu, theo sau là activate(..., enable=1).

Xin lưu ý rằng trong HAL phiên bản 1_0, thứ tự lại ngược lại: activate được gọi trước, theo sau là set_delay.

Khi các đặc điểm được yêu cầu của một cảm biến đang thay đổi trong khi cảm biến đó đang được kích hoạt, hàm batch sẽ được gọi.

flush có thể được gọi bất cứ lúc nào, ngay cả trên các cảm biến chưa được kích hoạt (trong trường hợp đó) thì kết quả phải trả về -EINVAL)

Khi một cảm biến bị vô hiệu hoá, activate(..., enable=0) sẽ được gọi.

Song song với các lệnh gọi đó, hàm poll sẽ được gọi nhiều lần để dữ liệu yêu cầu. Bạn có thể gọi poll ngay cả khi không có cảm biến nào được kích hoạt.

mô-đun cảm biến_t

sensors_module_t là loại dùng để tạo mô-đun phần cứng Android cho các cảm biến. Việc triển khai HAL phải xác định một đối tượng HAL_MODULE_INFO_SYM thuộc loại này để hiển thị hàm get_sensors_list. Hãy xem định nghĩa của sensors_module_t trong sensors.h và định nghĩa của hw_module_t để biết thêm thông tin.

sensors_poll_device_t / sensors_poll_device_1_t

sensors_poll_device_1_t chứa các phương thức còn lại được xác định ở trên: activate, batch, flush và poll. Trường common (loại hw_device_t) xác định số phiên bản của HAL.

cảm biến

sensor_t đại diện cho một cảm biến Android. Dưới đây là một số trường quan trọng của lớp này:

name (tên): Chuỗi mà người dùng nhìn thấy, đại diện cho cảm biến. Chuỗi này thường chứa tên bộ phận của cảm biến cơ bản, loại cảm biến và liệu đó có phải là cảm biến đánh thức hay không. Ví dụ: "Cảm biến gia tốc LIS2HH12", "Con quay hồi chuyển chưa được hiệu chuẩn MAX21000", "Báo áp đánh thức BMP280", "Vectơ xoay trò chơi MPU6515"

handle: Số nguyên dùng để tham chiếu đến cảm biến khi đăng ký hoặc tạo sự kiện từ cảm biến đó.

type: Loại cảm biến. Hãy xem phần giải thích về loại cảm biến trong bài viết Cảm biến Android là gì? để biết thêm thông tin chi tiết và xem phần Các loại cảm biến để biết các loại cảm biến chính thức. Để các loại cảm biến không chính thức, type phải bắt đầu bằng SENSOR_TYPE_DEVICE_PRIVATE_BASE

stringType: Loại cảm biến dưới dạng chuỗi. Khi cảm biến có loại chính thức, được đặt thành SENSOR_STRING_TYPE_*. Thời gian cảm biến có loại dành riêng cho nhà sản xuất, stringType phải bắt đầu bằng tên miền ngược của nhà sản xuất. Ví dụ: một cảm biến (ví dụ: trình phát hiện kỳ lân) do nhóm Cool-product xác định tại Công ty hư cấu có thể sử dụng stringType=”com.fictional_company.cool_product.unicorn_detector”. stringType được dùng để xác định riêng biệt các loại cảm biến không chính thức. Vui lòng xem sensors.h để biết thêm thông tin về các loại và chuỗi loại.

requiredPermission: Một chuỗi đại diện cho quyền mà ứng dụng phải có để xem cảm biến, đăng ký với cảm biến và nhận dữ liệu của cảm biến. Chuỗi trống có nghĩa là ứng dụng không yêu cầu bất kỳ quyền nào để truy cập cảm biến này. Một số loại cảm biến như máy đo nhịp tim có requiredPermission bắt buộc. Tất cả cảm biến cung cấp tín hiệu nhạy cảm thông tin người dùng (chẳng hạn như nhịp tim) phải được bảo vệ bằng quyền.

flags: Cờ cho cảm biến này, xác định chế độ báo cáo của cảm biến và liệu cảm biến đó có phải là cảm biến đánh thức hay không. Ví dụ: cảm biến đánh thức một lần sẽ có flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP. Các bit của cờ không được sử dụng trong phiên bản HAL hiện tại phải được để bằng 0.

maxRange: Giá trị tối đa mà cảm biến có thể báo cáo, theo cùng đơn vị với các giá trị được báo cáo. Cảm biến phải có thể báo cáo các giá trị mà không bị bão hoà trong [-maxRange; maxRange]. Xin lưu ý rằng điều này có nghĩa là tổng phạm vi của cảm biến theo nghĩa chung là 2*maxRange. Khi cảm biến báo cáo giá trị trên nhiều trục, phạm vi sẽ áp dụng cho mỗi trục. Ví dụ: gia tốc kế "+/- 2g" sẽ báo cáo maxRange = 2*9.81 = 2g.

Độ phân giải: Mức chênh lệch nhỏ nhất về giá trị mà cảm biến có thể đo được. Thường được tính toán dựa trên maxRange và số bit trong phép đo.

power: Chi phí điện năng để bật cảm biến, tính bằng mili giây. Mức tiêu thụ năng lượng này hầu như luôn cao hơn mức tiêu thụ điện năng được báo cáo trong bảng dữ liệu của cảm biến cơ bản. Hãy xem phần Cảm biến cơ sở != cảm biến thực tế để biết thêm thông tin chi tiết và xem phần Quy trình đo lường điện năng để biết thông tin chi tiết về cách đo lường mức tiêu thụ điện năng của cảm biến. Nếu mức tiêu thụ điện năng của cảm biến phụ thuộc vào việc thiết bị có đang di chuyển hay không, thì mức tiêu thụ điện năng khi di chuyển là mức được báo cáo trong trường power.

minDelay:Đối với các cảm biến liên tục, khoảng thời gian lấy mẫu, tính theo micrô giây, tương ứng với tốc độ nhanh nhất mà cảm biến hỗ trợ. Hãy xem sampling_period_ns để biết thông tin chi tiết về cách sử dụng giá trị này. Xin lưu ý rằng minDelay được biểu thị bằng micro giây còn sampling_period_ns được biểu thị bằng nano giây. Đối với các cảm biến chế độ báo cáo khi thay đổi và chế độ báo cáo đặc biệt, trừ khi nếu không thì minDelay phải bằng 0. Đối với cảm biến chụp một lần, phải là -1.

maxDelay: Đối với cảm biến liên tục và cảm biến thay đổi, khoảng thời gian lấy mẫu, tính bằng micro giây, tương ứng với tốc độ chậm nhất mà cảm biến hỗ trợ. Hãy xem phần Sample_period_ns để biết thông tin chi tiết về cách sử dụng giá trị này. Xin lưu ý rằng maxDelay được biểu thị bằng micro giây còn sampling_period_ns được biểu thị bằng nano giây. Đối với cảm biến chụp một lần và cảm biến đặc biệt, maxDelay phải: 0.

fifoReservedEventCount: Số sự kiện được đặt trước cho cảm biến này trong FIFO phần cứng. Nếu có một FIFO chuyên dụng cho cảm biến này, thì fifoReservedEventCount là kích thước của FIFO chuyên dụng này. Nếu FIFO là được chia sẻ với các cảm biến khác, fifoReservedEventCount là kích thước của phần FIFO dành riêng cho cảm biến đó. Trên hầu hết các hệ thống FIFO dùng chung và trên các hệ thống không có FIFO phần cứng, thì giá trị này bằng 0.

fifoMaxEventCount: Số sự kiện tối đa có thể được lưu trữ trong FIFO cho cảm biến này. Giá trị này luôn lớn hơn hoặc bằng fifoReservedEventCount. Giá trị này được dùng để ước tính nhanh chóng, FIFO sẽ đầy khi đăng ký cảm biến tại một điểm cụ thể giả sử không có cảm biến nào khác được kích hoạt. Trên các hệ thống không có FIFO phần cứng, fifoMaxEventCount là 0. Hãy xem phần Tạo lô để biết thêm chi tiết.

Đối với các cảm biến có loại cảm biến chính thức, một số trường sẽ bị khung ghi đè. Ví dụ: cảm biến gia tốc kế buộc phải có chế độ báo cáo liên tục và máy đo nhịp tim buộc phải được bảo vệ bằng quyền SENSOR_PERMISSION_BODY_SENSORS.

sự kiện_cảm biến_t

Các sự kiện cảm biến do cảm biến Android tạo ra và được báo cáo thông qua hàm poll là type sensors_event_t. Sau đây là một số các trường quan trọng của sensors_event_t:

version: Phải là sizeof(struct sensors_event_t)

sensor: Tên của cảm biến đã tạo sự kiện, theo định nghĩa của sensor_t.handle.

type: Loại cảm biến của cảm biến đã tạo sự kiện, như được xác định bởi sensor_t.type.

timestamp: Dấu thời gian của sự kiện tính bằng nano giây. Đây là thời điểm sự kiện đã xảy ra (đã thực hiện một bước hoặc đã thực hiện đo gia tốc kế), không phải thời gian báo cáo sự kiện. timestamp phải được đồng bộ hoá với đồng hồ elapsedRealtimeNano và trong trường hợp cảm biến liên tục, độ trễ phải nhỏ. Đôi khi, bạn cần lọc dấu thời gian để đáp ứng các yêu cầu của CDD, vì việc chỉ sử dụng thời gian ngắt SoC để đặt dấu thời gian sẽ gây ra độ trễ quá cao và việc chỉ sử dụng thời gian của khối cảm biến để đặt dấu thời gian có thể gây ra tình trạng không đồng bộ với đồng hồ elapsedRealtimeNano, vì đồng hồ cảm biến bị trôi.

dữ liệu và các trường chồng chéo: Các giá trị do cảm biến đo lường. Ý nghĩa và đơn vị của các trường đó là dành riêng cho từng loại cảm biến. Hãy xem sensors.h và định nghĩa về các Loại cảm biến khác nhau để biết nội dung mô tả về các trường dữ liệu. Đối với một số cảm biến, độ chính xác của kết quả đo cũng được báo cáo dưới dạng một phần của dữ liệu, thông qua trường status. Trường này chỉ được chuyển qua cho các loại cảm biến được chọn, xuất hiện ở lớp SDK dưới dạng giá trị độ chính xác. Đối với các cảm biến đó, việc phải đặt trường trạng thái được đề cập trong định nghĩa loại cảm biến của chúng.

Sự kiện hoàn tất việc làm mới siêu dữ liệu

Sự kiện siêu dữ liệu có cùng loại với sự kiện cảm biến thông thường: sensors_event_meta_data_t = sensors_event_t. Các kết quả này được trả về cùng với các sự kiện cảm biến khác thông qua cuộc thăm dò ý kiến. Họ sở hữu các trường sau:

version: Phải là META_DATA_VERSION

loại: Phải là SENSOR_TYPE_META_DATA

sensor, reserved và timestamp: Phải là 0

meta_data.what: Chứa loại siêu dữ liệu cho sự kiện này. Hiện có một loại siêu dữ liệu hợp lệ duy nhất: META_DATA_FLUSH_COMPLETE.

Sự kiện META_DATA_FLUSH_COMPLETE thể hiện việc hoàn tất việc xả một FIFO cảm biến. Khi meta_data.what=META_DATA_FLUSH_COMPLETE, meta_data.sensor phải được đặt thành tay cầm của cảm biến đã được xả. Các sự kiện này chỉ được tạo khi flush được gọi trên một cảm biến. Hãy xem phần về hàm flush để biết thêm thông tin.