Giao diện Sensors HAL, đượ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 phải xác định từng chức năng được khai báo trong sensors.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 tham 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ả FIFO của cảm biến được chỉ định và báo cáo sự kiện hoàn thành xả khi quá trình này được thực hiện. -
poll
- Trả về các sự kiện cảm biến khả dụng.
Việc triển khai phải là luồng an toàn và cho phép các chức năng 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 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ác cảm biến được triển khai bởi HAL. Xem sensor_t để biết chi tiết về cách xác định cảm biến.
Thứ tự mà các cảm biến xuất hiện trong danh sách là thứ tự mà các 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ở xuất hiện đầu tiên, tiếp theo là các 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”. 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/tắt 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 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 dùng một lần tự động hủy kích hoạt khi nhận được một sự kiện và chúng vẫn phải chấp nhận bị hủy kích hoạt thông qua lệnh gọi activate(..., enabled=0)
.
Cảm biến không đánh thức không bao giờ ngăn SoC chuyển sang chế độ treo; nghĩa là HAL sẽ không giữ khóa đánh thức một phần thay mặt cho các ứng dụng.
Các cảm biến đánh thức, khi liên tục phân phối các sự kiện, có thể ngăn SoC chuyển sang chế độ tạm dừng, nhưng nếu không cần phân phối sự kiện nào, thì phải giải phóng một phần khóa đánh thức.
Nếu enabled
là 1 và cảm biến đã được kích hoạt, chức năng này 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 không hoạt động và thành công.
Hàm này trả về 0 nếu thành công và một số lỗi âm nếu không.
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 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 đó, chức năng 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 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, cũng như không thể chuyển từ độ trễ báo cáo tối đa cao xuống 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 sampling_period_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à một số lỗi âm nếu không.
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 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 phiên bản HAL 1.0, setDelay đã được sử dụng thay vì lô để đặt sampling_period_ns .
tuôn ra (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; các sự kiện đó được phân phối như bình thường (nghĩa là: như thể độ trễ báo cáo tối đa đã hết) và bị xóa khỏi FIFO.
Quá trình tuôn ra diễn ra không đồng bộ (tức là: chức năng 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 thành xóa chỉ được thêm cho cảm biến đã chỉ định.
Nếu cảm biến được chỉ định không có FIFO (không thể lưu vào bộ đệm) hoặc nếu FIFO trống tại thời điểm gọi, thì flush
vẫn phải thành công và gửi một sự kiện hoàn thành xóa cho cảm biến đó. Điều này áp dụng cho tất cả các cảm biến trừ cảm biến chụp một lần.
Khi flush
được gọi, ngay cả khi một sự kiện flush đã 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, đồng thời FIFO phải được flush. Số lượng lệnh gọi flush
phải bằng với số lượng sự kiện hoàn thành xóa đã 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 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, -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ì trả về 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 khi thành công hoặc số lỗi âm trong trường hợp có lỗi.
Số 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).
Chuỗi 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, chức năng 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 trước, tiếp theo là set_delay
.
Khi các đặc tính được yêu cầu của một cảm biến đang thay đổi trong khi nó được kích hoạt, chức năng batch
đượ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ị hủy kích hoạt, activate(..., enable=0)
sẽ được gọi.
Song song với những lời gọi đó, chức năng 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á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 . 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.
cảm biến_thăm dò_thiết bị_t / cảm biến_thăm dò_thiết bị_1_t
sensors_poll_device_1_t
chứa phần còn lại của các phương pháp đượ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 một 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 hiển thị cho người dùng đạ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 bên dưới, 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 hiệu chuẩn 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ý cảm biến hoặc tạo sự kiện từ cảm biế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 Các 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 (chẳng hạn như máy dò kỳ lân) được xác định bởi nhóm Cool-product tại Fictional-Company 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 sensors.h để biết thêm thông tin về các loại và loại chuỗi.
requiredPermission: Một chuỗi thể hiện quyền mà các ứ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 rỗ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 cảm biến này. Một số loại cảm biến như máy đo nhịp tim có yêu cầu bắt requiredPermission
. Tất cả các cảm biến cung cấp thông tin nhạy cảm của người dùng (chẳng hạn như nhịp tim) phải được bảo vệ bằng quyền.
cờ: 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 để lại 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ị mà 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 một số 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í năng lượng để kích hoạt cảm biến, tính bằng milliAmps. Điều 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 bảng dữ liệu của cảm biến bên dưới. 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 của cảm biến. Nếu mức tiêu thụ năng lượ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ụ năng lượng trong khi di chuyển 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 sampling_period_ns để biết chi tiết về cách giá trị này được sử dụng. Xin lưu ý rằng minDelay
được biểu thị bằng micro giây trong khi sampling_period_ns
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à thay đổi, trừ khi có quy định khác, minDelay
phải là 0. Đối với các cảm biến one-shot, nó phải là -1.
maxDelay: Đối với cảm biến liên tục và khi thay đổi, khoảng thời gian lấy mẫu, tính bằng micrô giây, tương ứng với tốc độ chậm nhất mà cảm biến hỗ trợ. Xem sampling_period_ns để biết chi tiết về cách giá trị này được sử dụng. Xin lưu ý rằng maxDelay
được biểu thị bằng micro giây trong khi sampling_period_ns
tính bằng nano giây. Đối với cảm biến đặc biệt và cảm biến một lần, maxDelay
phải bằng 0.
fifoReserveEventCount: Số sự kiện dành riêng cho cảm biến này trong FIFO phần cứng. Nếu có 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 đượ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 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 sử dụng để ước tính FIFO sẽ đầy nhanh như thế nào 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ị ghi đè bởi khung. 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_sự kiệ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 chức năng thăm dò ý kiến 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: Tay cầm 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 điểm sự kiện xảy ra (một bước được thực hiện hoặc phép đo gia tốc kế được thực hiện), không phải thời điểm 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, jitter phải nhỏ. Lọc dấu thời gian đôi khi 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 từ đồng hồ elapsedRealtimeNano
trôi qua, vì đồng hồ cảm biến trôi.
dữ liệu và các trường chồng lấp: Các giá trị được cảm biến đo lường. Ý nghĩa và đơn vị của các trường đó là cụ thể cho từng loại cảm biến. Xem sensors.h và định nghĩa của 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 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 những cảm biến đó, thực tế là trường trạng thái phải được đặt đượ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 bình thường: sensors_event_meta_data_t = sensors_event_t
. Chúng được trả lại cùng với các sự kiện cảm biến khác thông qua thăm dò ý kiến. 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 bằng 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 việc hoàn thành quá trình xóa 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 tuôn ra để biết thêm thông tin.
Giao diện Sensors HAL, đượ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 phải xác định từng chức năng được khai báo trong sensors.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 tham 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ả FIFO của cảm biến được chỉ định và báo cáo sự kiện hoàn thành xả khi quá trình này được thực hiện. -
poll
- Trả về các sự kiện cảm biến khả dụng.
Việc triển khai phải là luồng an toàn và cho phép các chức năng 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 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ác cảm biến được triển khai bởi HAL. Xem sensor_t để biết chi tiết về cách xác định cảm biến.
Thứ tự mà các cảm biến xuất hiện trong danh sách là thứ tự mà các 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ở xuất hiện đầu tiên, tiếp theo là các 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”. 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/tắt 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 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 dùng một lần tự động hủy kích hoạt khi nhận được một sự kiện và chúng vẫn phải chấp nhận bị hủy kích hoạt thông qua lệnh gọi activate(..., enabled=0)
.
Cảm biến không đánh thức không bao giờ ngăn SoC chuyển sang chế độ treo; nghĩa là HAL sẽ không giữ khóa đánh thức một phần thay mặt cho các ứng dụng.
Các cảm biến đánh thức, khi liên tục phân phối các sự kiện, có thể ngăn SoC chuyển sang chế độ tạm dừng, nhưng nếu không cần phân phối sự kiện nào, thì phải giải phóng một phần khóa đánh thức.
Nếu enabled
là 1 và cảm biến đã được kích hoạt, chức năng này 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 không hoạt động và thành công.
Hàm này trả về 0 nếu thành công và một số lỗi âm nếu không.
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 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 đó, chức năng 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 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, cũng như không thể chuyển từ độ trễ báo cáo tối đa cao xuống 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 sampling_period_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à một số lỗi âm nếu không.
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 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 phiên bản HAL 1.0, setDelay đã được sử dụng thay vì lô để đặt sampling_period_ns .
tuôn ra (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; các sự kiện đó được phân phối như bình thường (nghĩa là: như thể độ trễ báo cáo tối đa đã hết) và bị xóa khỏi FIFO.
Quá trình tuôn ra diễn ra không đồng bộ (tức là: chức năng 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 thành xóa chỉ được thêm cho cảm biến đã chỉ định.
Nếu cảm biến được chỉ định không có FIFO (không thể lưu vào bộ đệm) hoặc nếu FIFO trống tại thời điểm gọi, thì flush
vẫn phải thành công và gửi một sự kiện hoàn thành xóa cho cảm biến đó. Điều này áp dụng cho tất cả các cảm biến trừ cảm biến chụp một lần.
Khi flush
được gọi, ngay cả khi một sự kiện flush đã 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, đồng thời FIFO phải được flush. Số lượng lệnh gọi flush
phải bằng với số lượng sự kiện hoàn thành xóa đã 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 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 dùng một lần hoặc không được bật và trả về số lỗi âm nếu không.
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 khi thành công hoặc số lỗi âm trong trường hợp có lỗi.
Số 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).
Chuỗi 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, chức năng 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 trước, tiếp theo là set_delay
.
Khi các đặc tính được yêu cầu của một cảm biến đang thay đổi trong khi nó được kích hoạt, chức năng batch
đượ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ị hủy kích hoạt, activate(..., enable=0)
sẽ được gọi.
Song song với những lời gọi đó, chức năng 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á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 . 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.
cảm biến_thăm dò_thiết bị_t / cảm biến_thăm dò_thiết bị_1_t
sensors_poll_device_1_t
chứa phần còn lại của các phương pháp đượ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 một 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 hiển thị cho người dùng đạ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 bên dưới, 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 hiệu chuẩn 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ý cảm biến hoặc tạo sự kiện từ cảm biế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 Các 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 (chẳng hạn như máy dò kỳ lân) được xác định bởi nhóm Cool-product tại Fictional-Company 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 sensors.h để biết thêm thông tin về các loại và loại chuỗi.
requiredPermission: Một chuỗi thể hiện quyền mà các ứ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 rỗ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 cảm biến này. Một số loại cảm biến như máy đo nhịp tim có yêu cầu bắt requiredPermission
. Tất cả các cảm biến cung cấp thông tin nhạy cảm của người dùng (chẳng hạn như nhịp tim) phải được bảo vệ bằng quyền.
cờ: 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 để lại 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ị mà 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 một số 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í năng lượng để kích hoạt cảm biến, tính bằng milliAmps. Điều 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 bảng dữ liệu của cảm biến bên dưới. 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 của cảm biến. Nếu mức tiêu thụ năng lượ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ụ năng lượng trong khi di chuyển 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 sampling_period_ns để biết chi tiết về cách giá trị này được sử dụng. Xin lưu ý rằng minDelay
được biểu thị bằng micro giây trong khi sampling_period_ns
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à thay đổi, trừ khi có quy định khác, minDelay
phải là 0. Đối với các cảm biến one-shot, nó phải là -1.
maxDelay: Đối với cảm biến liên tục và khi thay đổi, khoảng thời gian lấy mẫu, tính bằng micrô giây, tương ứng với tốc độ chậm nhất mà cảm biến hỗ trợ. Xem sampling_period_ns để biết chi tiết về cách giá trị này được sử dụng. Xin lưu ý rằng maxDelay
được biểu thị bằng micro giây trong khi sampling_period_ns
tính bằng nano giây. Đối với cảm biến đặc biệt và cảm biến một lần, maxDelay
phải bằng 0.
fifoReserveEventCount: Số sự kiện dành riêng cho cảm biến này trong FIFO phần cứng. Nếu có 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 đượ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 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 sử dụng để ước tính FIFO sẽ đầy nhanh như thế nào 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ị ghi đè bởi khung. 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_sự kiệ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 chức năng thăm dò ý kiến 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: Tay cầm 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 điểm sự kiện xảy ra (một bước được thực hiện hoặc phép đo gia tốc kế được thực hiện), không phải thời điểm 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, jitter phải nhỏ. Lọc dấu thời gian đôi khi 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 từ đồng hồ elapsedRealtimeNano
trôi qua, vì đồng hồ cảm biến trôi.
dữ liệu và các trường chồng lấp: Các giá trị được cảm biến đo lường. Ý nghĩa và đơn vị của các trường đó là cụ thể cho từng loại cảm biến. Xem sensors.h và định nghĩa của 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 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 những cảm biến đó, thực tế là trường trạng thái phải được đặt đượ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 bình thường: sensors_event_meta_data_t = sensors_event_t
. Chúng được trả lại cùng với các sự kiện cảm biến khác thông qua thăm dò ý kiến. 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 bằng 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 việc hoàn thành quá trình xóa 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 tuôn ra để biết thêm thông tin.