استوديو Android for Platform (ASfP) هو بيئة التطوير المتكاملة (IDE) المقترَحة لتطوير منصة المركبات المعرَّفة بالبرامج (SDV) في نظام التشغيل Android Automotive (AAOS). يتوافق ASfP مع جميع اللغات التي تستخدمها منصة SDV في نظام التشغيل Android Automotive، بما في ذلك لغة Rust لحِزم خدمات SDV.
تتناول هذه الصفحة الإعدادات الخاصة بمركبات SDV فقط. لمزيد من المعلومات حول الميزات وسير العمل العامة في ASfP، يُرجى الاطّلاع على "استوديو Android" للمنصة.
لا تعمل ASfP إلا على نظام التشغيل Linux 64 بت مع وحدات المعالجة المركزية x86-64. يمكنك استخدامه على محطة عمل Linux محلية أو في السحابة الإلكترونية. لمزيد من المعلومات حول إعداد السحابة الإلكترونية، يُرجى الاطّلاع على التطوير في السحابة الإلكترونية.
تثبيت ASfP
يبلغ الحد الأقصى التلقائي لحجم الذاكرة المؤقتة في ASfP 30 غيغابايت. تستهلك فهرسة عملية الدفع في النظام الأساسي قدرًا كبيرًا من الذاكرة، خاصةً عند تشغيل أجهزة Cuttlefish متعددة الأجهزة الافتراضية على الجهاز نفسه. احرص على أن يقتصر نطاق مشروعك على الأدلة التي تعمل عليها، وعدِّل الحد الأقصى لحجم الذاكرة المؤقتة في إعدادات ذاكرة ASfP إذا لزم الأمر.
تتيح ASfP التحديثات التلقائية داخل بيئة التطوير المتكاملة (IDE). لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تحديث "استوديو Android للمنصة". لمزيد من المعلومات حول تنزيل استوديو Android for Platform وتثبيته والتحقّق من متطلبات النظام، يُرجى الاطّلاع على تثبيت Android Studio for Platform.
إنشاء مشروع SDV
يجب إعداد عملية الدفع في AAOS SDV ومزامنتها وإنشاؤها قبل البدء. لمزيد من المعلومات حول إعداد عملية الدفع، يُرجى الاطّلاع على موقع الرمز والتنزيل والإنشاء والتشغيل.
لإنشاء مشروع SDV، اتّبِع الخطوات التالية:
- أنشئ مشروعًا جديدًا في ASfP واختَر جذر عملية سحب SDV في AAOS كعملية سحب المستودع. لمزيد من المعلومات حول خطوات المعالج، يُرجى الاطّلاع على إنشاء مشروع أو استيراده.
- بعد أن تنشئ ASfP المشروع، انقر على ASfP > Project > Open Config لفتح ملف
.asfp-project. استبدِل محتوى الملف بالمثال التالي، ثم اضبط
repoعلى مسار الدفع:repo: /path/to/sdv_source lunch: sdv_core_cf-aosp_current-userdebug directories: include: - system/software_defined_vehicle/samples other_languages: - rustعدِّل
lunchوdirectoriesللمنطقة التي تعمل فيها. للحفاظ على سرعة الفهرسة والمزامنة، يجب تضمين الأدلة التي تعدّلها بشكل نشط فقط. يسرد الجدول التالي أهداف SDV والأدلة الشائعة:التركيز على تطوير SDV هدف واحد ( lunch)موصى بها directoriesحِزم خدمات SDV sdv_core_cf-aosp_current-userdebugدليل حِزم وكتالوج الخدمات، مثل system/software_defined_vehicle/samplesدمج منصة SDV Core sdv_core_cf-aosp_current-userdebugsystem/software_defined_vehicle/middlewareوsystem/software_defined_vehicle/automotive_servicesوdevice/google/sdvSDV Gateway على SDV IVI sdv_ivi_cf-aosp_current-userdebugsystem/software_defined_vehicle/sdv_gatewayوsystem/software_defined_vehicle/samples/sdv_gatewayوpackages/services/Carعرض ميزات السلامة على وسائط SDV sdv_media_har_cf-aosp_current-userdebugpackages/services/display_safety،device/google/sdv_display_safetyعرض ميزات السلامة على نظام المعلومات والترفيه داخل المركبة (IVI) في المركبات المعرَّفة بالبرامج (SDV) sdv_ivi_cf_ds-aosp_current-userdebugpackages/apps/Car/DriverUI،packages/services/display_safety/serviceإذا كانت عملية الدفع تستخدم بيان
trunk_staging، استبدِل-aosp_current-userdebugبـ-trunk_staging-userdebug. لتصفُّح رمز النظام الأساسي الأصلي أيضًا، أضِفcppإلىother_languages. لمزيد من المعلومات حول جميع خيارات الضبط، يُرجى الاطّلاع على مَعلمات الضبط.لتطبيق التغييرات، اختَر ASfP > مزامنة > مزامنة المشروع. لمزيد من المعلومات حول أوضاع المزامنة (المزامنة الكاملة والمزامنة الجزئية والمزامنة بدون إنشاء) وتصدير أو استيراد نماذج
.asfp-projectالقابلة للمشاركة لفريقك، يُرجى الاطّلاع على أوضاع المزامنة ونافذة أدوات Soong ونماذج المشاريع القابلة للمشاركة (التصدير والاستيراد).
نشر حِزم خدمات SDV
يتضمّن ASfP مكوّنًا إضافيًا لـ SDV ينشر ملف APEX يحتوي على حِزم الخدمات مباشرةً على جهاز SDV قيد التشغيل. يكون المكوّن الإضافي غير مفعَّل تلقائيًا. لاستخدامها، يجب تفعيل المكوّن الإضافي لـ SDV من خلال الإعدادات > المكوّنات الإضافية. لمزيد من المعلومات حول حِزم APEX، يُرجى الاطّلاع على إنشاء حِزم الخدمات ونشرها.
تعتمد طريقة النشر على ما إذا كان ملف APEX متوفّرًا على الجهاز:
- إذا كان APEX مثبّتًا، يمكنك نشر التغييرات مباشرةً من ASfP.
- إذا كان ملف APEX جديدًا، يجب إعادة إنشاء صورة النظام وإعادة تشغيلها أولاً، أو استخدام صورة نظام تتضمّن المفتاح المستخدَم لتوقيع ملف APEX. بعد ذلك، يمكنك نشر التطبيق من ASfP.
لنشر حزمة APEX لحزمة خدمات، اتّبِع الخطوات التالية:
- شغِّل جهاز SDV باستخدام المكوّن الإضافي Cuttlefish. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تشغيل أجهزة SDV على Cuttlefish.
- افتح ملف
apex/Android.bpلحزمة الخدمة وانقر على رمز تشغيل في المسافة بين الأعمدة بجانب مجموعةapex {. - في القائمة التي تظهر، انقر على تشغيل "نشر APEX_NAME". يمكنك أيضًا إنشاء ملف APEX بدون نشره أو تغيير إعدادات التشغيل من القائمة نفسها.
تشغيل أجهزة SDV على Cuttlefish
يتضمّن ASfP مكوّنًا إضافيًا لـ Cuttlefish ينشئ أجهزة Cuttlefish محلية ويشغّلها. يتطلّب المكوّن الإضافي أداة تنسيق مضيف Cuttlefish. إذا لم يكن برنامج تنسيق المضيف متاحًا، سيعرض ASfP تعليمات لإعداده.
لإنشاء جهاز SDV، اتّبِع الخطوات التالية:
- اختَر الأدوات > أداة إدارة الأجهزة، وانقر على +، ثم اختَر إنشاء جهاز Cuttlefish.
- لإنشاء إعدادات متعددة للأجهزة الافتراضية، اختَر من الإعدادات الأساسية وأنشئ إعدادات خاصة بك أو استورِدها، مثل SDV Core مع SDV IVI أو SDV Media مع SDV IVI لميزة "أمان الشاشة". لإنشاء جهاز افتراضي واحد، اختَر من عملية سحب شجرة مصدر Android المحلية بدلاً من ذلك.
لعرض جميع شاشات الأجهزة الافتراضية على شاشة واحدة والوصول إلى خيارات إضافية للأجهزة، استخدِم نافذة أدوات Cuttlefish. لفتحها، انقر على الرمز ... في اللوحة الجانبية واختَر Cuttlefish، أو ابحث عن Cuttlefish في مساعدة > البحث عن إجراء. يمكنك أيضًا عرض شاشات فردية في الأجهزة المتصلة. بما أنّ SDV Core يعمل بدون شاشة، استخدِم Logcat وTerminal لفحصه.
تصحيح الأخطاء والاختبار
تتضمّن ASfP مصحِّح أخطاء LLDB مدمجًا لرموز C++ وRust. لمزيد من المعلومات حول تصحيح الأخطاء والاختبار في ASfP، يُرجى الاطّلاع على تصحيح أخطاء رمز النظام الأساسي وتصحيح أخطاء رمز Rust واختبار رمز النظام الأساسي باستخدام أداة atest وتصحيح أخطاء أهداف cc_test وrust_test ضمن LLDB.
عند إرفاق برنامج تصحيح الأخطاء بحزمة خدمات، يجب إرفاقه بالعملية التي
تستضيفه. تستخدم أسماء العمليات تنسيق <bundle_name>:<instance_name>، مثل
OrchestratorSampleRustServiceBundle:sample-main-no-conditions. يسرد الأمر التالي العمليات المطابقة ومعرّفات العمليات الخاصة بها:
adb shell ps -A | grep <bundle_name>
لمزيد من المعلومات حول سير عمل تصحيح أخطاء SDV، مثل الاتصال بأجهزة متعددة وعرض السجلات، يُرجى الاطّلاع على تصحيح أخطاء SDV.
تعديل ملفات VSIDL
تتضمّن ASfP خادم لغة VSIDL (vsidl-lsp). لمزيد من المعلومات
حول كيفية إعداد الكتالوج لخادم اللغة، يُرجى الاطّلاع على
التحديثات التلقائية للكتالوج والتكامل مع LSP. عندما يتضمّن الكتالوج ملف CATALOG_UPDATE، يوفّر المحرِّر الميزات التالية لملفات .vsidl:
- التحقّق المباشر: يميّز المحرّر الكلمات الرئيسية في VSIDL ويعرض أخطاء بناء الجملة والأنواع التي لم يتم حلّها وأخطاء التحقّق من VSIDLC في نافذة المشاكل. لمزيد من المعلومات حول قواعد التحقّق من الصحة ورموز الخطأ، يُرجى الاطّلاع على مواصفات لغة VSIDL.
- الإكمال التلقائي والتوثيق: يمكنك الضغط على Ctrl+Space للحصول على اقتراحات بشأن الكلمات الرئيسية والرسائل والخدمات والمواضيع والقنوات، والضغط على Ctrl+Q لعرض تعليقات التوثيق.
- التنقّل والتنسيق: يمكنك الضغط على Ctrl+B للانتقال إلى تعريفات
.vsidlأو.proto، وAlt+Shift+F7 للعثور على المراجع، وCtrl+F12 لعرض بنية الملف، وCtrl+Alt+L لتنسيق الملف.
إضافة سياق SDV للمساعدين المستندين إلى الذكاء الاصطناعي
يتضمّن ASfP الذكاء الاصطناعي في "استوديو Android" ووكيل مدمج مع أداة الإنشاء Soong وأدوات atest. بما أنّ ملفات AGENTS.md تكون محفوظة بجانب الرمز المصدر في نظام التحكّم في الإصدارات، يمكنك مشاركة قواعد SDV نفسها بين وكيل ASfP المضمّن ووكلاء الترميز المستندين إلى سطر الأوامر أو الحاويات الذين يقرأون ملفات AGENTS.md. عند
إرسال طلب مع فتح ملف في ASfP، يحمّل الوكيل ملفات AGENTS.md
من دليل هذا الملف وأدلته الرئيسية (ما لم يكن لملف GEMINI.md
في الدليل نفسه الأولوية)، ويمكنك التحقّق من الملفات النشطة
في لوحة الدرج السياق ضمن ملفات AGENTS.md. لمزيد من المعلومات، يُرجى الاطّلاع على مقالتَي التعرّف على "استوديو Android" للمنصة وتخصيص الوكيل باستخدام ملفات AGENTS.md.
توفّر النماذج التالية نقاط بداية لسير العمل في إنشاء مشروع SDV.
حِزم خدمات SDV
ضَع ملف AGENTS.md هذا في دليل الحزمة المضمّن في .asfp-project
الذي يحتوي على مجلدات catalog/ وservices/ وapex/. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء برمجيات وسيطة وإنشاء حِزم الخدمات ونشرها وكتابة ملف ربط SOME/IP ونظرة عامة على تفويض الاتصالات في SDV.
# AAOS SDV service bundle and VSIDL rules
## Build and test
- Initialize the build environment (`source build/envsetup.sh` and
`lunch sdv_core_cf-aosp_current-userdebug`) when running outside ASfP, build
modules with Soong (`m <module_name>`), and run tests with
`atest <TestModuleName>` (`rust_test`, `rust_test_host`, `cc_test`, or
`python_test_host`), without creating `Cargo.toml` files or running `cargo`
- In catalog `Android.bp` files, avoid `defaults` on `rust_protobuf` modules
(`vsidlc` uses a regex parser), include each `.proto` file in at most one
`rust_protobuf` target, and cover all catalog files in the first `filegroup`
(`srcs: ["**/*"]`)
## Protobuf, VSIDL, and AUTOSAR SOME/IP mapping conventions
- Keep `.proto` files limited to `message`, `enum`, and RPC `service` schemas
(using `sdv/vsidl/v1/annotations.proto` only for field size bounds), without
topic names, channel names, or queue capacities
- Write `.vsidl` files in TextProto `VsidlEntry` syntax (`package: "..."`,
`service_bundle { name: "..." }`, `publisher` or `subscriber` with `message`
and `topic`, and `server` or `client` with `service` and `channel`, without
`import` statements; RPCs support unary, client-streaming, and
server-streaming methods, not bidirectional streaming), and isolate
`some_ip_mapping` (`sdv_type_mapping` and `someip_service_mapping` for
AUTOSAR electronic control unit (ECU) `ARXML` or `vsomeip` IDs) or
`vhal_mapping` rules in dedicated `.vsidl` mapping files so core bundles stay
transport-independent
- Use `PascalCase` for `service_bundle` names (avoiding Rust, C++, and Java
keywords), `snake_case` for `build_cfg.target_name`, a globally unique
lowercase `package` with at least four segments (`com.<org>.sdv.<domain>`;
never reuse platform-reserved `com.android.sdv.*` or sample `com.sdv.*`
names), and lowercase dash-case starting with a letter (no consecutive or
trailing hyphens, underscores, or slashes) for `topic`, `channel`, and
instance names
- Set `capacity` on every `publisher` to an even integer greater than or equal
to 2, and pair every `subscriber` and RPC `client` with a matching
`publisher` or `server` in the catalog or its `-d` dependency catalogs
## Code generation, authorization, and APEX packaging
- Export `ANDROID_BUILD_TOP`, check `CATALOG_UPDATE` for catalog-relative
`output_path` (such as `".."`), `dependency_catalog_paths` (`-d`), and
`vsidlc_gen_args`, and run `vsidlc -c <catalog_dir> -o <output_dir>`; omit
`--services` from `vsidlc_gen_args` and avoid `-p` (`--purge`) or
`regenerator` when `output_path` holds handwritten `services/` code
- Leave generated files in `generated_rs/`, `apex/`, and `configs/` unmodified,
and implement Rust logic in `services/<ServiceBundleName>/src/main.rs` (even
though the initial `vsidlc --services` skeleton header says not to edit; C++
bundles do not use `vsidlc` C++ codegen and instead use
`libsdv_lifecycle_client_cpp`, `libsdv_comms_cpp`, and
`sdv_service_bundle_metadata` with `native_library_path: "lib64/lib<so>.so"`
in `sdv_service_bundles_manifest.textproto`)
- Keep communications authorization `.textproto` policies in `configs/` aligned
with every `publisher`, `subscriber`, `server`, and `client` unit (omitting
`capacity` inside manual authorization `.textproto` `publisher` entries) so
Service Discovery does not reject endpoints at runtime
- In Rust bundles, wait for publisher or RPC server availability before
creating subscribers or clients, stop active tasks in `on_stop`, and run
blocking work in `tokio::spawn_blocking`
- Generate Rust service bundle APEXes with `vsidlc --apex` (`updatable: true`,
`min_sdk_version: "35"`, and `product_specific: true` in `apex/Android.bp`,
never `vendor: true` or `soc_specific: true`, with matching unique `name` and
`version` >= 1 in `apex_manifest.json`), and do not set
`supportsRebootlessUpdate: true` or run `adb install --force-non-staged`
because SDV APEX updates require a reboot
بوابة SDV على SDV IVI
ضَع ملف AGENTS.md هذا في دليل وحدة عميل "المعلومات والترفيه داخل المركبة" (IVI) أو
system/software_defined_vehicle/sdv_gateway/. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة
استخدام SDV Gateway على نظام المعلومات والترفيه داخل المركبة (IVI).
# AAOS SDV Gateway on SDV IVI rules
- Initialize the build environment (`source build/envsetup.sh` and
`lunch sdv_ivi_cf-aosp_current-userdebug`) when running outside ASfP, build
IVI modules with Soong (`m <module_name>`), and run verification with
`atest <TestModuleName>`
- For native C or C++ IVI clients (including vehicle hardware abstraction layer
(VHAL) integrations), link `libsdvgatewayclient`
(`#include "libsdvgatewayclient.h"`) or `ISdvGateway`; for in-tree system Java
or Kotlin clients, use `libsdvgatewayclient-java`,
`libsdvgatewayclient-java-sdk.stubs`, `libsdvgatewayclient-java-sdk`, and
`com.android.sdv.gateway.client`
- Start the Binder thread pool before calling `ASDVGateway_Client_new`, and
call `ASDVGateway_Client_initComms` (or `SdvGatewayClient.initComms`) before
any service discovery, data tunnel, or RPC calls
- Check `ASDVGateway_Client_isRpcAvailable` or
`ASDVGateway_Client_isProcessBoundToSdvRpcNetworkInterface` before opening
RPC sockets on early boot, treat `ASDVGateway_StatusCode_OK` with null
`ASDVGateway_RpcCredentials_t` as insecure `UNLOCKED` boot mode, and free
non-null credentials with `ASDVGateway_Client_deleteRpcCredentials`
- Grant `sdv_gateway_client_domain(<domain>)` in SELinux (do not add
`binder_use` on `/vendor` daemons, which violates Treble `neverallow`; add
`group inet` on native init services, and `INTERNET` plus
`CONNECTIVITY_USE_RESTRICTED_NETWORKS` privapp permissions for system Java
RPC clients)
أمان الشبكة الإعلانية
ضَع ملف AGENTS.md هذا في packages/services/display_safety/ أو دليل تطبيق لوحة القيادة. لمزيد من المعلومات، يُرجى الاطّلاع على
بدء استخدام ميزة "أمان الشاشة" وطبقة تجريد النظام الأساسي لـ HAR
وسلسلة أدوات تصميم الأمان وDriverUI.
# AAOS Display Safety partner integration rules
- Display Safety spans two guest VMs with separate `lunch` targets: keep
safety-critical telltales, gauges, camera views, chimes, and early-boot or
fallback placeholders in the Rust high availability renderer (HAR) and safety
monitor on SDV Media (`sdv_media_har_cf`), and build non-safety cluster UI on
SDV IVI (`sdv_ivi_cf_ds`) using `ClusterHomeManager` (`Cluster2` rather than
legacy `Cluster1`)
- Implement target OS and hardware subsystems (display, graphics, exterior view
system (EVS) cameras, audio, user input, and vehicle signals) in a dedicated
`har-platform-<target>` platform abstraction layer (PAL) crate implementing
`har-platform-api` traits rather than modifying core `harry` framework crates,
and verify PAL crates against the HAR platform test suite with `atest`
- Generate safety monitor configurations and telltale inspection artifacts from
the serialized Automotive Design for Compose document and safety JSON mapping
(`{"documents": [{"rootnode": "#...", "display_id": 1, "document_id": "...",`
`"states": {"<signal>": "#<node_id>"}}]}`) using the safety design compiler
rather than hardcoding telltale pixel coordinates
- Because the HAR display plane composites above Android IVI, ensure HAR clears
the cluster viewport region to `alpha = 0.0` while valid `HeartbeatRequest`
gRPC messages arrive from IVI, and set opaque pixels in custom HAR OpenGL ES
surfaces to `alpha = 1.0` (`0xFF`)
- Initialize the build environment (`source build/envsetup.sh` and `lunch`) when
running outside ASfP, integrate prebuilt cluster APKs into `sdv_ivi_cf_ds`
through `DriverUIPrebuilt` (`overrides: ["DriverUIStubApp"]`), launch dual-VM
Cuttlefish setups from ASfP or with `ds_toolkit launch`, pass `--user 0` to
`adb shell am` cluster commands, and note that
`adb shell dumpsys SurfaceFlinger` on SDV IVI inspects only Android layers
rather than the overlying HAR plane