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 phải xác định từng hàm được khai báo trong sensors.h. Các hàm 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 một 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 nhất định.flush– Xoá sạch FIFO của cảm biến đã chỉ định và báo cáo sự kiện xoá sạch 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ừ nhiều luồng.
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_tsensors_poll_device_tsensor_tsensors_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ảm biến do HAL triển khai. Hãy xem sensor_t để biết thông tin chi tiết về cách xác định cảm biến.
Thứ tự xuất hiện của các cảm biến trong danh sách là thứ tự mà cảm biến sẽ được báo cáo cho ứng dụng. Thông thường, cảm biến cơ sở sẽ xuất hiện trước, sau đó 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". Đó là giá trị do getDefaultSensor(int sensorType, bool wakeUp) trả về.
Hàm này trả về số lượng cảm biến trong danh sách.
activate(sensor, true/false)
int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int enabled);
Bật hoặc tắt cảm biến.
sensor_handle là tên xử lý 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; nghĩa là HAL sẽ không giữ khoá chế độ thức một phần thay cho ứ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 khi thành công và nếu không thì trả về số lỗi âm.
lô(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 các tham số của cảm biến, bao gồm tần số lấy mẫu và độ trễ 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à tay điều khiể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 sampling_period_ns để biết thêm thông tin chi tiết.
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. Hãy xem đoạn max_report_Latency_ns
để biết thêm thông tin chi tiết.
Hàm này trả về 0 nếu thành công và số lỗi âm nếu không.
setDelay(sensor, sampling period)
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ì lô để đặ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 nhiều cảm biến, thì FIFO đó sẽ được xoá và sự kiện hoàn tất xả nước chỉ được thêm vào cho cảm biến được 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 tất 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 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 với số sự kiện hoàn tất xả dữ liệu đã 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, 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 chưa được bật và nếu không thì số lỗi âm.
cuộc 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 đố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 không bao giờ trả về 0 (không có sự kiện).
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 các 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 thay đổi trong quá trình kích hoạt, hàm batch sẽ được gọi.
Bạn có thể gọi flush 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ày, hàm này phải trả về -EINVAL)
Khi một cảm biến bị huỷ kích hoạt, 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 để yêu cầu dữ liệ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.
sensors_module_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. Đố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 dành riêng cho 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 (ví dụ: trình phát hiện kỳ lân) do nhóm Sản phẩm thú vị tại Công ty hư cấu xác định 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. Hãy 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 đạ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 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ó requiredPermission bắt buộc. Tất 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 để 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ị đã 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]. Hãy 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 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: Mức chênh lệch nhỏ nhất về giá trị mà cảm biến có thể đo lường.
Thường được tính toán dựa trên maxRange và số bit trong phép đo.
power: Mức hao tổn năng lượng khi bật cảm biến, tính bằng miliAmpe.
Mức tiêu thụ điện năng 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 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ả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ợ. Hãy xem phần 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ảm biến chế độ báo cáo đặc biệt và chế độ thay đổi, trừ khi có quy định khác, minDelay phải là 0. Đối với cảm biến một lần, giá trị này phải là -1.
maxDelay:Đối với cảm biến liên tục và đang 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ợ. 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 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 đặc biệt và cảm biến một lần, maxDelay phải là 0.
fifoĐặt trướcEventCount: Số sự kiện dành riêng 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 được chia sẻ với các cảm biến khác, 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 dùng chung và trên các hệ thống không có FIFO phần cứng, giá trị này là 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 tốc độ FIFO sẽ đầy khi đăng ký với 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. Hãy xem phần Gộp nhóm để biết thêm thông tin 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 cuộc thăm dò ý kiến có giá trị là type sensors_event_t. Sau đây là một số trường quan trọng của sensors_event_t:
version: Phải là sizeof(struct sensors_event_t)
cảm biến: Tay điều khiển của cảm biến đã tạo ra sự kiện, như được sensor_t.handle xác định.
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 (một bước đã được thực hiện hoặc một phép đo gia tốc kế đã được thực hiện), chứ không phải thời điểm sự kiện được báo cáo. 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. Vui lòng xem sensors.h và định nghĩa về nhiều loại cảm biến để 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 các lần đọc cũng được báo cáo trong 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 sự kiện 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. Các tệp này có các trường sau:
version: Phải là META_DATA_VERSION
type: 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 tại, chỉ có một loại siêu dữ liệu hợp lệ: 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.