Giao diện Sensors HAL, được khai báo trongsensors.h , thể hiện 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 phải xác định từng hàm được khai báo trong cảm biến.h. Các chức năng chính là:
-
get_sensors_list- Trả về danh sách tất cả các cảm biến. -
activate- Khởi động hoặc dừng cảm biến. -
batch- Đặt các thông số của cảm biến như tần suất lấy mẫu và độ trễ báo cáo tối đa. -
setDelay- Chỉ được sử dụng trong phiên bản HAL 1.0. Đặt tần số lấy mẫu cho một cảm biến nhất định. -
flush- Xóa FIFO của cảm biến được chỉ định và báo cáo sự kiện xả hoàn tất khi việc này được thực hiện. -
poll- Trả về các sự kiện cảm biến có sẵn.
Việc triển khai phải an toàn theo luồng và cho phép các hàm này được gọi từ các luồng khác nhau.
Giao diện cũng xác định một số loại được sử dụng bởi các chức nă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 bên dưới, hãy xem cảm biến.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ác cảm biến được HAL triển khai. Xem cảm biến_t để biết chi tiết về cách xác định cảm biến.
Thứ tự các cảm biến xuất hiện trong danh sách là thứ tự các cảm biến sẽ được báo cáo cho ứng dụng. Thông thường, cảm biến cơ sở xuất hiện đầu tiên, tiếp theo là cảm biến tổng hợp.
Nếu một số cảm biến dùng chung 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”. Nó là cái đượ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, đúng/sai)
int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled);
Kích hoạt hoặc hủy kích hoạt một cảm biến.
sensor_handle là tay cầm của cảm biến để kích hoạt/hủy kích hoạt. Tay cầm của cảm biến được xác định bởi trường handle của cấu trúc cảm biến_t của nó.
enabled được đặt thành 1 để bật hoặc 0 để tắt cảm biến.
Cảm biến một lần tự động tắt khi nhận được sự kiện và chúng vẫn phải chấp nhận bị vô hiệu hóa thông qua lệnh gọi tới activate(..., enabled=0) .
Cảm biến không đánh thức không bao giờ ngăn SoC chuyển sang chế độ tạm dừng; nghĩa là HAL sẽ không thực hiện khóa đánh thức một phần thay mặt cho các ứng dụng.
Cảm biến đánh thức khi phân phối sự kiện liên tục có thể ngăn SoC chuyển sang chế độ tạm dừng, nhưng nếu không có sự kiện nào cần phân phối thì khóa đánh thức một phần phải được giải phóng.
Nếu enabled là 1 và cảm biến đã được kích hoạt, chức năng này sẽ không hoạt động và thành công.
Nếu enabled là 0 và cảm biến đã bị tắt, chức năng 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à ngược lại là số lỗi âm.
lô(cảm biến, cờ, 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 các tham số của cảm biến, bao gồm tần suất lấy mẫu và độ trễ báo cáo tối đa . Chức năng này có thể được gọi trong khi cảm biến được kích hoạt, trong trường hợp đó, nó không được làm mất bất kỳ phép đo cảm biến nào: Việc chuyển từ tốc độ lấy mẫu này sang tốc độ lấy mẫu khác không thể gây ra sự kiện bị mất và cũng không thể chuyển từ độ trễ báo cáo tối đa cao sang tốc độ thấp độ trễ báo cáo tối đa.
sensor_handle là tay cầm của cảm biế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. Xem lấy mẫu_thời_ns để biết thêm chi tiết.
max_report_latency_ns là thời gian tối đa mà các sự kiện có thể bị trì hoãn trước khi được báo cáo qua HAL, tính bằng nano giây. Xem đoạn max_report_latency_ns để biết thêm chi tiết.
Hàm này trả về 0 nếu thành công và ngược lại là số lỗi âm.
setDelay(cảm biến, thời gian lấy mẫu)
int (*setDelay)(
struct sensors_poll_device_t *dev,
int sensor_handle,
int64_t sampling_period_ns);
Sau HAL phiên bản 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ì batch để đặt samples_ Period_ns .
xả (cảm biến)
int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);
Thêm một sự kiện hoàn thành xóa vào cuối FIFO phần cứng cho cảm biến được chỉ định và xóa FIFO; những sự kiện đó được phân phối như thường lệ (tức là: như thể độ trễ báo cáo tối đa đã hết) và bị xóa khỏi FIFO.
Việc xóa 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ẽ bị xóa và sự kiện hoàn tất tuôn ra chỉ được thêm vào cho cảm biến đã chỉ định.
Nếu cảm biến được chỉ định không có FIFO (không thể đệm) hoặc nếu FIFO trống tại thời điểm cuộc gọi, flush vẫn phải thành công và gửi sự kiện hoàn thành xả cho cảm biến đó. Điều này áp dụng cho tất cả các cảm biến ngoại trừ cảm biến một lần.
Khi flush được gọi, ngay cả khi một sự kiện tuôn ra đã có trong FIFO cho cảm biến đó, một sự kiện bổ sung phải được tạo và thêm vào cuối FIFO và FIFO phải được xóa. Số lượng lệnh gọi flush phải bằng số lượng sự kiện hoàn thành tuôn ra được tạo.
flush không áp dụng cho cảm biến một lần ; nếu sensor_handle đề cập đến cảm biến một lần, thì flush phải trả về -EINVAL và không tạo ra bất kỳ sự kiện siêu dữ liệu hoàn chỉnh nào.
Hàm này trả về 0 nếu thành công, -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 và nếu không thì là số lỗi âm.
thăm dò ý kiến()
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 vào đối số data . Chức năng này phải chặn cho đến khi có sự kiện. Nó sẽ trả về số sự kiện được đọc thành công hoặc số lỗi âm trong trường hợp có lỗi.
Số lượng sự kiện được trả về trong data phải nhỏ hơn hoặc bằng đối count . Hàm này sẽ không bao giờ trả về 0 (không có sự kiện).
Trình tự cuộc gọi
Khi thiết bị khởi động, get_sensors_list được gọi.
Khi một cảm biến được kích hoạt, hàm batch sẽ được gọi với các tham số được yêu cầu, theo sau là activate(..., enable=1) .
Lưu ý rằng trong phiên bản HAL 1_0, thứ tự ngược lại: activate được gọi đầu tiên, theo sau là set_delay .
Khi các đặc tính được yêu cầu của cảm biến thay đổi trong khi nó đượ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 không được kích hoạt (trong trường hợp đó nó phải trả về -EINVAL )
Khi một cảm biến bị vô hiệu hóa, activate(..., enable=0) sẽ được gọi.
Song song với các lệnh gọi đó, hàm poll sẽ được gọi liên tục để yêu cầu dữ liệu. poll có thể được gọi ngay cả khi không có cảm biến nào được kích hoạt.
cảm biến_module_t
sensors_module_t là loại được sử dụng để tạo mô-đun phần cứng Android cho 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 . Xem định nghĩa của sensors_module_t trong cảm biến.h và định nghĩa của hw_module_t để biết thêm thông tin.
cảm biến_poll_device_t / cảm biến_poll_device_1_t
sensors_poll_device_1_t chứa phần còn lại của các phương thức được xác định ở trên: activate , batch , flush và poll . Trường common của nó (thuộc loại hw_device_t ) xác định số phiên bản của HAL.
cảm biến_t
sensor_t đại diện cho cảm biến Android . Dưới đây là một số lĩnh vực quan trọng của nó:
tên: Một chuỗi mà người dùng có thể 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ụ: “Gia tốc kế LIS2HH12”, “Con quay hồi chuyển không được hiệu chỉnh MAX21000”, “Phong vũ biểu đánh thức BMP280”, “Vectơ xoay trò chơi MPU6515”
xử lý: Số nguyên được sử dụng để chỉ cảm biến khi đăng ký hoặc tạo sự kiện từ nó.
type: Loại cảm biến. Xem phần giải thích về loại cảm biến trong Cảm biến Android là gì? để biết thêm chi tiết và xem Loại cảm biến để biết các loại cảm biến chính thức. Đối với 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, hãy đặt thành SENSOR_STRING_TYPE_* . Khi cảm biến có loại cụ thể của nhà sản xuất, stringType phải bắt đầu bằng tên miền đảo ngược của nhà sản xuất. Ví dụ: một cảm biến (giả sử là máy phát hiện kỳ lân) do nhóm Cool-product tại Fictional-Company xác định có thể sử dụng stringType=”com.fictional_company.cool_product.unicorn_detector” . stringType được sử dụng để xác định duy nhất các loại cảm biến không chính thức. Xem cảm biến.h để biết thêm thông tin về loại và loại chuỗi.
requirePermission: Một chuỗi biểu thị quyền mà ứng dụng phải có để xem cảm biến, đăng ký và nhận dữ liệu của nó. Một chuỗi trống có nghĩa là các ứng dụng không yêu cầu bất kỳ quyền nào để truy cập vào cảm biến này. Một số loại cảm biến như máy đo nhịp tim có bắt buộc phải requiredPermission . Tất cả các cảm biến cung cấp thông tin nhạy cảm cho người dùng (chẳng hạn như nhịp tim) phải được cấp phép bảo vệ.
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 giữ 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ó khả năng báo cáo các giá trị không bão hòa trong phạm vi [-maxRange; maxRange] . 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 các giá trị trên nhiều trục, phạm vi sẽ áp dụng cho từng trục. Ví dụ: gia tốc kế “+/- 2g” sẽ báo cáo maxRange = 2*9.81 = 2g .
độ phân giải: Sự khác biệt 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 để kích hoạt cảm biến, tính bằng milliAmps. Con số này gần như luôn cao hơn mức tiêu thụ điện năng được báo cáo trong biểu dữ liệu của cảm biến cơ bản. Xem Cảm biến cơ sở != cảm biến vật lý để biết thêm chi tiết và xem Quy trình đo công suất để biết chi tiết về cách đo 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 sẽ là mức tiêu thụ được báo cáo trong trường power .
minDelay: Đối với cảm biến liên tục, khoảng thời gian lấy mẫu, tính bằng micro giây, tương ứng với tốc độ nhanh nhất mà cảm biến hỗ trợ. Xem lấy mẫu_thời_ns để biết 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 trong khi sampling_period_ns được tính bằng nano giây. Đối với các cảm biến chế độ báo cáo đặc biệt và khi thay đổi, trừ khi có quy định khác, minDelay phải bằng 0. Đối với các cảm biến một lần, giá trị này phải là -1.
maxDelay: Đối với các cảm biến liên tục và liên tục 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ợ. Xem lấy mẫu_thời_ns để biết 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 trong khi sampling_period_ns được tính bằng nano giây. Đối với các cảm biến đặc biệt và cảm biến một lần, maxDelay phải bằng 0.
fifoReservedEventCount: Số lượng sự kiện dành riêng cho cảm biến này trong FIFO phần cứng. Nếu có FIFO dành riêng cho cảm biến này thì fifoReservedEventCount chính là kích thước của FIFO chuyên dụng này. Nếu FIFO được chia sẻ với các cảm biến khác, thì fifoReservedEventCount là kích thước của phần FIFO được dành riêng cho cảm biến đó. Trên hầu hết các hệ thống FIFO được chia sẻ và trên các hệ thống không có FIFO phần cứng, giá trị này là 0.
fifoMaxEventCount: Số lượng 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 sử dụng để ước tính tốc độ FIFO sẽ đầy khi đăng ký vào cảm biến ở một tốc độ 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. Xem Batching để 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 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ởi quyền SENSOR_PERMISSION_BODY_SENSORS .
cảm biến_event_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 chức năng thăm dò ý kiến đều thuộc type sensors_event_t . Dưới đây là một số trường quan trọng của sensors_event_t :
phiên bản: Phải là sizeof(struct sensors_event_t)
cảm biến: Bộ điều khiển của cảm biến đã tạo ra sự kiện, như được xác định bởi sensor_t.handle .
loại: Loại cảm biến của cảm biến đã tạo ra sự kiện, như được xác định bởi sensor_t.type .
dấu thời gian: Dấu thời gian của sự kiện tính bằng nano giây. Đây là thời gian sự kiện xảy ra (một bước được thực hiện hoặc phép đo gia tốc được thực hiện), không phải thời gian sự kiện được báo cáo. timestamp phải được đồng bộ hóa với đồng hồ elapsedRealtimeNano và trong trường hợp cảm biến liên tục, độ biến động phải nhỏ. Đôi khi, việc lọc dấu thời gian là cần thiết để đá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 hiện tượng giật hình quá cao và việc chỉ sử dụng thời gian của chip cảm biến để đặt dấu thời gian có thể gây ra hiện tượng mất đồng bộ hóa khỏi đồng hồ elapsedRealtimeNano , vì đồng hồ cảm biến trôi.
dữ liệu và các trường chồng chéo: Các giá trị được đo bằng cảm biến. Ý nghĩa và đơn vị của các trường đó dành riêng cho từng loại cảm biến. Xem cảm biến.h và định nghĩa về các loại Cảm biến khác nhau để biết 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 số đọc cũng được báo cáo như một phần của dữ liệu, thông qua trường status . Trường này chỉ được chuyển qua 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 những 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 xóa siêu dữ liệu
Các sự kiện siêu dữ liệu có cùng loại với các sự kiện cảm biến thông thường: sensors_event_meta_data_t = sensors_event_t . Chúng đượ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ò. Họ sở hữu các lĩnh vực sau:
phiên bản: Phải là META_DATA_VERSION
loại: Phải là SENSOR_TYPE_META_DATA
cảm biến, dành riêng và dấu thời gian : Phải là 0
meta_data.what: Chứa loại siêu dữ liệu cho sự kiện này. Hiện tại có một loại siêu dữ liệu hợp lệ duy nhất: META_DATA_FLUSH_COMPLETE .
Các sự kiện META_DATA_FLUSH_COMPLETE thể hiện sự hoàn thành của quá trình xả 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ả. Chúng được tạo khi và chỉ khi flush được gọi trên cảm biến. Xem phần về chức năng xả để biết thêm thông tin.