Google cam kết thúc đẩy công bằng chủng tộc cho Cộng đồng người da đen. Xem cách thực hiện.

Cảm biến HAL 1.0

Giao diện Sensors HAL, được khai báo trong sensor.h , đại diện cho giao diện giữa khuôn khổ 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 các 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 số lấy mẫu và độ trễ báo cáo tối đa.
  • setDelay - Chỉ được sử dụng trong HAL phiên bản 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 xả hoàn toàn 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 cho 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ố kiểu đượ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 sensor.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 do HAL triển khai. Xem sensor_t để biết chi tiết về cách xác định các 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 hỗn hợp.

Nếu một số cảm biến chia sẻ cùng một 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, true / false)

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 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 sensor_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 one-shot sẽ tự động tắt khi nhận được một sự kiện và chúng vẫn phải chấp nhận ngừng kích hoạt thông qua một cuộc 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ế độ tạm ngừng; nghĩa là, HAL sẽ không giữ một phần khóa đánh thức thay mặt cho các ứng dụng.

Cảm biến đánh thức, khi phân phối các sự kiện liên tục, có thể ngăn SoC chuyển sang chế độ tạm ngừng, nhưng nếu không có sự kiện nào cần được phân phối, 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, thì chức năng này là không cần chọn và sẽ thành công.

Nếu enabled là 0 và cảm biến đã bị vô hiệu hóa, thì chức năng này là không cần sử dụng và sẽ thành công.

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

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 thông số của cảm biến, bao gồm tần suất lấy mẫuđộ 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 đổi từ tốc độ lấy mẫu này sang tốc độ lấy mẫu khác không thể gây ra các 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 để 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à tại đó 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 khi thành công và một số lỗi âm nếu không.

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, hàm 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 .

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 tuôn ra hoàn toàn 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ư bình thường (tức là: như thể độ trễ báo cáo tối đa đã hết hạn) và bị xóa khỏi FIFO.

Quá trình xả xảy ra không đồng bộ (nghĩa 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, FIFO đó sẽ được xóa và sự kiện hoàn thành xả 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ể đệm) hoặc nếu FIFO trống tại thời điểm cuộc gọi, quá trình flush vẫn phải thành công và gửi một 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 không phải là cảm biến chụp một lần.

Khi quá trình flush được gọi, ngay cả khi sự kiện xả đã 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ả. Số lượng lệnh gọi flush phải bằng số lượng các sự kiện hoàn thành tuôn ra đã tạo.

flush không áp dụng cho cảm biến một lần chụp ; nếu sensor_handle đề cập đến cảm biến một lần, quá trình 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 khi thành công, -EINVAL nếu cảm biến được chỉ định là cảm biến chụp 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 khi 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, 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, 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 thay đổi trong khi nó được kích hoạt, thì 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 cuộc gọi đó, chức năng poll ​​sẽ được gọi nhiều lần để 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.

sensor_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 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 định nghĩa ở trên: activate , batch , flushpoll . Trường common của nó (kiểu hw_device_t ) xác định số phiên bản của HAL.

sensor_t

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

tên: Một chuỗi 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 bên dưới, loại cảm biến và liệu nó 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 chỉnh MAX21000”, “Phong vũ biểu đánh thức BMP280”, “Véc tơ quay trò chơi MPU6515”

xử lý: Số nguyên được sử dụng để chỉ bộ cảm biến khi đăng ký với nó hoặc tạo ra các sự kiện từ nó.

type: Loại cảm biến. Xem 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 dò 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 sensor.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à 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 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ó 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ởi một sự cho phép.

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ị lớn nhất mà cảm biến có thể báo cáo, 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ão hòa trong [-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 á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: 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 milimét. Con số này gần như luôn luôn nhiều 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 bên dưới. Xem Base sensor! = 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 công suất tiêu thụ 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ị đang di chuyển, thì mức tiêu thụ điện năng trong 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ợ. Xem sampling_period_ns để biết chi tiết về cách sử dụng giá trị này. Hãy 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ảm biến chế độ báo cáo khi thay đổi và đặc biệt, trừ khi có quy định khác, minDelay phải bằng 0. Đối với cảm biến chụp một lần, nó phải là -1.

maxDelay: Đối với cảm biến liên tục và 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 sampling_period_ns để biết chi tiết về cách sử dụng giá trị này. Hãy 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.

FifoReservedEventCount: 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 chia sẻ FIFO 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 FIFO sẽ đầy nhanh như thế nào 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, FIFO của phần cứng là 0. Xem fifoMaxEventCount để 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 theo dõi nhịp tim buộc phải được bảo vệ bởi quyền SENSOR_PERMISSION_BODY_SENSORS .

sensor_event_t

Các sự kiện cảm biến được tạo ra bởi cảm biến Android 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)

sensor: 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 .

type: 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 một phép đo gia tốc kế đã được thực hiện), không phải là 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, độ chập chờn phải nhỏ. Việc 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ì chỉ sử dụng thời gian ngắt SoC để đặt dấu thời gian gây ra hiện tượng chập chờn quá cao và việc chỉ sử dụng thời gian chip cảm biến để đặt dấu thời gian có thể gây ra hiện tượng hủy đồ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ởi cảm biến. Ý nghĩa và đơn vị của các trường đó là cụ thể cho từng loại cảm biến. Xem sensor.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 các 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 các 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.

Siêu dữ liệu xóa các sự kiện hoàn chỉnh

Sự kiện siêu dữ liệu có cùng loại với sự kiện cảm biến bình thường: sensors_event_meta_data_t = sensors_event_t . Chúng được quay lại 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ọ có các trường 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 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 biểu thị sự hoàn thành củ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 làm mờ. Chúng được tạo ra khi và chỉ khi flush nước đượ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.