From 120a2677992ea299eea5fb5cb0ed1081f76bb92c Mon Sep 17 00:00:00 2001 From: Vinod Ahuja Date: Sat, 19 Nov 2022 13:59:20 -0600 Subject: Updating File name and links in the documentation Updating documentation: 1. Renamed all the files and folder following 01-99 index numbering 2. Matched title name and file name 3. Inserted title in the files where ever missing 4. Updated all the reference links in the documentation Bug-AGL: [SPEC-4470] Signed-off-by: Vinod Ahuja Change-Id: Ib73e1f91107646e11b5b19ab6ead4080add506e4 Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/28170 Reviewed-by: Jan-Simon Moeller Tested-by: Jan-Simon Moeller --- .../01_Application_Framework/01_Introduction.md | 150 +++++++++++++++++ .../02_Application_Startup.md | 184 +++++++++++++++++++++ docs/04_Developer_Guides/01_Setting_Up_AGL_SDK.md | 70 ++++++++ .../02_AGL_Layers/01_Overview.md | 25 +++ .../02_AGL_Layers/02_meta_agl.md | 124 ++++++++++++++ .../02_AGL_Layers/03_meta_agl_demo.md | 159 ++++++++++++++++++ .../02_AGL_Layers/04_meta_agl_devel.md | 143 ++++++++++++++++ .../02_Creating_a_New_Service.md | 151 +++++++++++++++++ .../03_Creating_a_New_Application.md | 135 +++++++++++++++ .../04_Creating_a_custom_recipe.md | 49 ++++++ .../05_Generic_devices_setup.md | 94 +++++++++++ docs/04_Developer_Guides/images/AGL_add_recipe.png | Bin 0 -> 27037 bytes 12 files changed, 1284 insertions(+) create mode 100644 docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md create mode 100644 docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup.md create mode 100644 docs/04_Developer_Guides/01_Setting_Up_AGL_SDK.md create mode 100644 docs/04_Developer_Guides/02_AGL_Layers/01_Overview.md create mode 100644 docs/04_Developer_Guides/02_AGL_Layers/02_meta_agl.md create mode 100644 docs/04_Developer_Guides/02_AGL_Layers/03_meta_agl_demo.md create mode 100644 docs/04_Developer_Guides/02_AGL_Layers/04_meta_agl_devel.md create mode 100644 docs/04_Developer_Guides/02_Creating_a_New_Service.md create mode 100644 docs/04_Developer_Guides/03_Creating_a_New_Application.md create mode 100644 docs/04_Developer_Guides/04_Creating_a_custom_recipe.md create mode 100644 docs/04_Developer_Guides/05_Generic_devices_setup.md create mode 100644 docs/04_Developer_Guides/images/AGL_add_recipe.png (limited to 'docs/04_Developer_Guides') diff --git a/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md b/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md new file mode 100644 index 0000000..24d8c1a --- /dev/null +++ b/docs/04_Developer_Guides/01_Application_Framework/01_Introduction.md @@ -0,0 +1,150 @@ +--- +title: Introduction +--- + +# Foreword + +The AGL Application Framework is nothing new. However, the implementation used up until +the `lamprey` release has been retired starting with the `marlin` release and replaced +by a redesigned Application Framework one. However, this new implementation isn't a 1:1 +replacement, and as such it doesn't provide all of the features of the previous +Application Framework. Some of those will be added back over time, others have been +discarded in favor of more modern and/or widely-used alternatives. + +# Introduction + +As a provider of an integrated solution to build up on, AGL needs to define a reliable +and well-specified method for managing the deployment and integration of applications +and services, as well as the way they can interact with the rest of the system. + +This is achieved by providing a common set of rules and components, known as the +Application Framework. By ensuring conformity to those rules, application developers +can have a good understanding of the requirements for creating and packaging +applications targeting AGL-based systems. Likewise, system developers and integrators +have a clear path for including such applications in AGL-based products. + +The Application Framework's scope extends to the following areas: +- system services integration and lifecycle management +- user session management, including user-level applications and services lifecycle + management +- inter-process communication + +In order to be as simple as possible and avoid any unneded custom implementation, the +Application Framework relies mainly on third-party technologies and/or software +components, most of those being maintained under the +[freedesktop.org](https://www.freedesktop.org) umbrella. Those include: + + +- [systemd](https://www.freedesktop.org/wiki/Software/systemd/): system services and user session services management + + +- [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/): inter-process communication + + +- [Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/): + application enumeration and startup + +AGL also provides reference implementations whenever possible and relevant, located in +the [meta-agl](/04_Developer_Guides/02_AGL_Layers/02_meta_agl/) layer under `meta-app-framework`. At the +moment, the Application Framework contains 2 such components: + +- `agl-session`: `systemd` unit files for user sessions management + +- `applaunchd`: application launcher service + +# Services management + +Both system and user services are managed by `systemd`, which provides a number of +important features, such as dependency management or service monitoring: when starting +a service, `systemd` will ensure any other units this service depends on are available, +and otherwise start those dependencies. Similarly, `systemd` can automatically restart +a crashed service, ensuring minimal downtime. + +`systemd` also provides an efficient first layer of security through its +[sandboxing](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Sandboxing) +and other security-related options. + +It is also well integrated with D-Bus and can be used for a more fine-grained control +over D-Bus activated services: by delegating the actual service startup to `systemd`, +developers can take advantage of some of its advanced features, allowing for improved +reliability and security. + +Each service should be represented by a `systemd` unit file installed to the appropriate +location. More details can be obtained from the [Creating a New Service](/04_Developer_Guides/02_Creating_a_New_Service/) +document. + +# User session management + +Similarly, user sessions and the services they rely on are also managed by `systemd`. + +AGL provides 2 `systemd` units: + + +1\. `agl-session@.service` is a template system service for managing user sessions; it +takes a username or UID as a parameter, creating a session for the desired user. +Instanciating this service can be achieved by enabling `agl-session@USER.service`, for +example by executing the following command on a running system: + +``` +$ systemctl enable agl-session@USER.service +``` + +By default, AGL enables this service as `agl-session@agl-driver.service`, running as +user `agl-driver`. + +*Note: while you can create sessions for as many users as needed, only one instance of +`agl-session@.service` is allowed per user.* + + +2\. `agl-session.target` is a user target for managing user services and their +dependencies. It is started by `agl-session@.service`. + +By default, `agl-compositor` is part of this target. It is therefore automatically +started for user `agl-driver`. + +Any other service needed as part of the user session should similarly depend on this +target by appending the following lines to their unit file: + +``` +[Install] +WantedBy=agl-session.target +``` + +# Inter-process communication + +In order to provide a "standard", language-independent IPC mechanism and avoid the need +for maintaining custom bindings for each programming language to be used on top of AGL, +the Application Framework promotes the use of [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/) +as the preferred way for applications to interact with services. + +Most services already included in AGL provide one or several D-Bus interfaces, and can +therefore interact with D-Bus capable applications and services without requiring any +additional component. Those services include, among others: + +- [ConnMan](https://git.kernel.org/pub/scm/network/connman/connman.git/): network connectivity + +- [BlueZ](http://www.bluez.org/): Bluetooth connectivity + +- [oFono](https://git.kernel.org/pub/scm/network/ofono/ofono.git): telephony and modem + management + +- [GeoClue](https://gitlab.freedesktop.org/geoclue/geoclue/-/wikis/home): geolocation + +# Application launcher service + +As mentioned above, the Application Framework follows the guidelines of the +[Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/) +for application enumeration and startup. + +As no simple reference implementation exists for this part of the specification, AGL +provides an application launcher service named `applaunchd`. This service is part of the +default user session, and as such is automatically started on session startup. It can +therefore be considered always available. + +`applaunchd` enumerates applications installed on the system and provides a D-bus +interface for services and applications to: +- query the list of available applications +- request the startup and/or activation of a specific application +- be notified when applications are started or terminated + +`applaunchd` is described with more details in [the following document](../02_Application_Startup/). diff --git a/docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup.md b/docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup.md new file mode 100644 index 0000000..232f41e --- /dev/null +++ b/docs/04_Developer_Guides/01_Application_Framework/02_Application_Startup.md @@ -0,0 +1,184 @@ +--- +title: Application Startup +--- + +# Introduction + +At system runtime, it may be necessary for applications to start other applications +on demand. Such actions can be executed in reaction to a user request, or they may +be needed to perform a specific task. + +In order to do so, running applications and services need an established way of +discovering installed applications and executing those. The +[Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) +defines how applications can be discovered by using `.desktop` files, but there's no +simple reference implementation for this function. + +In order to provide a language-independent interface for applications and service to +use, AGL includes `applaunchd`, a user service part of the default session. + +*Note: as mentioned [previously](../01_Introduction/), services are managed using `systemd` +and are therefore not in the scope of this document.* + +# Application launcher service + +The purpose of `applaunchd` is to enumerate applications available on the system and +provide a way for other applications to query this list and start those on demand. +It is also able to notify clients of the startup and termination of applications it +manages. + +To that effect, `applaunchd` provides a D-Bus interface other applications can use +in order to execute those actions. + +*Note: `applaunchd` will only send notifications for applications it started; it isn't +aware of applications started by other means (`systemd`, direct executable call...), +and therefore can't send notifications for those.* + +## Application discovery + +On startup, `applaunchd` inspects all `.desktop` files present under the `applications/` +subfolder of any element of the `XDG_DATA_DIRS` environment variable, ignoring all entries +containing either the `NoDisplay=true` or `Hidden=true` lines. + +It then looks for the following keys: +- `Terminal` +- `DBusActivatable` + +If the desktop entry file contains the `Terminal` key set to `true`, then the application +is marked as a non-graphical one. As such, it won't be included in the applications list +if the client requests only graphical applications. + +If `DBusActivatable` is set to `true`, then the application is marked as D-Bus activated. +Additionally, `applaunchd` will search for a corresponding D-Bus service file in case this +line is missing. This is a workaround allowing D-Bus activated applications providing +an incomplete desktop entry file (i.e missing the `DBusActivatable` key) to be +identified as such. + +### Requirements for D-Bus activation + +`applaunchd` will always start D-Bus activatable applications using D-Bus activation +instead of executing the command line stated in the desktop entry file. + +This is handled by calling the `Activate` method of the +[org.freedesktop.Application](https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html) +interface with an empty argument. + +As a consequence, all D-Bus activatable applications **must** implement this D-Bus +interface. + +## Application identifiers + +Each application is identified by a unique Application ID. Although this ID can be +any valid string, it is highly recommended to use the "reverse DNS" convention in order +to avoid potential name collisions and ease D-Bus integration. + +The application ID is set in the desktop entry file itself for +[graphical applications](../3_Creating_a_New_Application/#graphical-applications): +it is the value of the `StartupWMClass` field, which must be identical to the `app-id` +advertised through the Wayland XDG toplevel protocol. In case this field is missing +(as is usually the case for non-graphical application), the application ID will be the +desktop entry file name, stripped from its `.desktop` extension. + +## D-Bus interface + +The `applaunchd` D-Bus interface is named `org.automotivelinux.AppLaunch`. The object +path for `applaunchd` is `/org/automotivelinux/AppLaunch`. The interface provides methods +for the following actions: +- retrieve the list of available applications; the client can choose to retrieve all + available applications, or only those suitable for a graphical environment +- request an application to be started + +Moreover, signals are available for clients to be notified when an application has +successfully started or its execution terminated. + +### Applications list + +The `listApplications` method allows clients to retrieve the list of available applications. +It takes one boolean argument named `graphical`: +- if set to `true`, only applications suitable for graphical environments are returned +- otherwise, the list contains all applications + +This method returns an array of variants (type `av`), each element being a structure made up +of 3 strings (type `(sss)`): +- the application ID +- the application's displayed name +- the full path to the application icon file (or an empty string if no icon was specified in + the application's desktop entry file) + +### Application startup request + +Applications can be started by using the `start` method, passing the corresponding application +ID as the only argument. This method doesn't return any data. + +If the application is already running, `applaunchd` won't start another instance, but instead +emit a `started` signal to notify clients the application is ready. + +### Status notifications + +The `org.automotivelinux.AppLaunch` interface provides 2 signals clients can connect to: +- `started` indicates an application has started + - for D-Bus activated applications, it is emitted upon successful completion of the + call to the `Activate` method of the `org.freedesktop.Application` interface + - for other applications, this signal is emitted as soon as the child process has been + successfully created +- `terminated` is emitted when an application quits + +Both signals have an additional argument named `appid`, containing the ID of the application +affected by the event. + +As mentioned above, the `started` signal is also emitted if `applaunchd` receives a request to +start an already running application. This can be useful, for example, when switching between +graphical applications: +- the application switcher doesn't need to track the state of each application; instead, it can + simply send a `start` request to `applaunchd` every time the user requests to switch to another + application +- the desktop environment then receives the `started` signal, indicating it should activate the + window with the corresponding `app-id` + +## Testing + +`applaunchd` can be manually tested using the `gdbus` command-line tool: + +1. Query the application list (graphical applications only): + +``` +$ gdbus call --session --dest "org.automotivelinux.AppLaunch" \ + --object-path "/org/automotivelinux/AppLaunch" \ + --method "org.automotivelinux.AppLaunch.listApplications" \ + true +``` + +This command will output something similar to what follows: + +``` +([<('navigation', 'Navigation', '/usr/share/icons/hicolor/scalable/navigation.svg')>, + <('settings', 'Settings', '/usr/share/icons/hicolor/scalable/settings.svg')>, + <('dashboard', 'Dashboard', '/usr/share/icons/hicolor/scalable/dashboard.svg')>, + <('hvac', 'HVAC', '/usr/share/icons/hicolor/scalable/hvac.svg')>, + <('org.freedesktop.weston.wayland-terminal', 'Weston Terminal', '/usr/share/icons/Adwaita/scalable/apps/utilities-terminal-symbolic.svg')>],) +``` + +2. Request startup of the `org.freedesktop.weston.wayland-terminal` application: + +``` +$ gdbus call --session --dest "org.automotivelinux.AppLaunch" \ + --object-path "/org/automotivelinux/AppLaunch" \ + --method "org.automotivelinux.AppLaunch.start" \ + "org.freedesktop.weston.wayland-terminal" +``` + +3. Monitor signals emitted by `applaunchd`: + +``` +$ gdbus monitor --session --dest "org.automotivelinux.AppLaunch" +``` + +This results in the following output when starting, then exiting, the +`org.freedesktop.weston.wayland-terminal` application: + +``` +Monitoring signals from all objects owned by org.automotivelinux.AppLaunch +The name org.automotivelinux.AppLaunch is owned by :1.4 +/org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.started ('org.freedesktop.weston.wayland-terminal',) +/org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.terminated ('org.freedesktop.weston.wayland-terminal',) +``` diff --git a/docs/04_Developer_Guides/01_Setting_Up_AGL_SDK.md b/docs/04_Developer_Guides/01_Setting_Up_AGL_SDK.md new file mode 100644 index 0000000..d3f01fb --- /dev/null +++ b/docs/04_Developer_Guides/01_Setting_Up_AGL_SDK.md @@ -0,0 +1,70 @@ +--- +title: Setting Up AGL SDK +--- + +AGL provides a pre-built ready-made Software Development Kit (SDK) to help +quickstart the service and application development process. + +1. Download the prebuilt SDK : + + Please open the link below and download .sh file for desired machine. + + **Note:** The links provided are for the master branch. If you want SDK for specific branch than change the name from master to specific branch. + + - **x86** : [qemux86-64](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/deploy/sdk/) + + **Note:** .sh file will be with name "poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-corei7-64-qemux86-64-toolchain-$(version number).sh" where version number is regularly updated on the site. + + + - **ARM 32 bit** : [qemuarm](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm/deploy/sdk/) + + **Note:** .sh file will be with name " poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-armv7vet2hf-neon-vfpv4-qemuarm-toolchain-$(version number).sh" where version number is regularly updated on the site. + + + - **AARCH64 - ARM 64bit** : [qemuarm64](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm64/deploy/sdk/) + + **Note:** .sh file will be with name " poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-aarch64-qemuarm64-toolchain-$(version number).sh" where version number is regularly updated on the site. + + + *Henceforth,* **qemux86-64** *is used in these guides, unless specified + otherwise. We also use the 'agl-demo-platform-crosssdk' as example.* + +2. Create application development directory and copy SDK into them : + + **Note:** In the copy command below change the file name with name of your downloaded .sh file. In the example below file name is based on x86 + + ```sh + $ mkdir ~/agl-app + $ cp ~/Downloads/poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-*.sh ~/agl-app/ + $ cd ~/agl-app + ``` + +3. Install the downloaded SDK : + + **Note:** In commands below again change the file name based on your downloaded .sh file + + + ```sh + $ chmod 777 poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-*.sh + $ mkdir agl-sdk/ + $ ./poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-*.sh + ``` + Select target directory for SDK : `~/agl-app/agl-sdk` + + ```sh + Automotive Grade Linux SDK installer version 14.0.0 + ============================================================= + Enter target directory for SDK (default: /opt/agl-sdk/10.90.0+snapshot-corei7-64): ~/agl-app/agl-sdk + You are about to install the SDK to "/home/boron/agl-app/agl-sdk". Proceed [Y/n]? Y + Extracting SDK..........................................................................................................................................done + Setting it up...done + SDK has been successfully set up and is ready to be used. + Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. + $ . /home/boron/agl-app/agl-sdk/environment-setup-corei7-64-agl-linux + ``` + +4. Source the SDK environment setup, each time you wish to use the SDK in a new shell session : + + ```sh + $ source ~/agl-app/agl-sdk/environment-setup-corei7-64-agl-linux + ``` diff --git a/docs/04_Developer_Guides/02_AGL_Layers/01_Overview.md b/docs/04_Developer_Guides/02_AGL_Layers/01_Overview.md new file mode 100644 index 0000000..dec8054 --- /dev/null +++ b/docs/04_Developer_Guides/02_AGL_Layers/01_Overview.md @@ -0,0 +1,25 @@ +--- +title: Overview +--- + +The [AGL Project](https://www.automotivelinux.org/) is an automotive-specific +development environment that provides a Linux distribution +([AGL UCB](https://www.automotivelinux.org/software/unified-code-base)). + +AGL uses layers designed to be compatible with the +[Yocto Project](https://www.yoctoproject.org) and the +[OpenEmbedded Project (OE)](https://www.openembedded.org/wiki/Main_Page). + +This section provides information about the layers used by the AGL Project: + +* **`meta-agl`**: Minimal set of software needed to create an AGL distribution + used to boot a system. + AGL profiles are built on top of this minimal set of software. + +* **`meta-agl-demo`**: Provides a reference or demo platform and applications + for the AGL Distribution. + The reference UI is part of the `meta-agl-demo` layer. + +* **`meta-agl-devel`**: Contains components under development or being tested. + This layer also contains software packages that OEMs need but do not exist + in AGL. diff --git a/docs/04_Developer_Guides/02_AGL_Layers/02_meta_agl.md b/docs/04_Developer_Guides/02_AGL_Layers/02_meta_agl.md new file mode 100644 index 0000000..1ac45a6 --- /dev/null +++ b/docs/04_Developer_Guides/02_AGL_Layers/02_meta_agl.md @@ -0,0 +1,124 @@ +--- +title: meta-agl +--- + +## Introduction + +The `meta-agl` layer provides the minimal set of software +to boot an AGL Distribution system. +You use this layer as the minimal core on which to build AGL profiles. + +**NOTE:** The `meta-agl` layer does not include a reference UI. + The reference UI is included as part of the + [`meta-agl-demo`](3_meta-agl-demo.md) layer. + Furthermore, `meta-agl` does not include additional components, such + as security, which are part of the + `meta-agl-extra` layer. + +## Sub-Layers + +The `meta-agl` layer itself contains many sub-layers and files. +Following is a "tree" look at the layer: + +``` +. +├── docs +├── meta-agl +├── meta-agl-bsp +├── meta-agl-distro +├── meta-agl-profile-cluster +├── meta-agl-profile-cluster-qt5 +├── meta-agl-profile-core +├── meta-agl-profile-graphical +├── meta-agl-profile-graphical-html5 +├── meta-agl-profile-graphical-qt5 +├── meta-agl-profile-hud +├── meta-agl-profile-telematics +├── meta-app-framework +├── meta-netboot +├── meta-security +├── README-AGL.md +├── README.md +├── scripts +├── templates +``` + +This list provides some overview information on the files and sub-layers +in `meta-agl`: + +* `docs`: Contains files that support AGL documentation. +* `meta-agl`: Contains layer configuration for the `meta-agl` layer. +* `meta-agl-bsp`: Contains adaptations for recipes and required packages + to boot an AGL distribution on targeted hardware and emulation (i.e. QEMU). +* `meta-agl-distro`: Contains distro configuration and supporting scripts. +* `meta-agl-profile-cluster`: The middleware for the AGL cluster profile. + The set of packages required for AGL Cluster Distribution. + Profiles include support for Wayland images. +* `meta-agl-profile-cluster-qt5`: The middleware for the AGL Qt5-based cluster profile. + The set of packages required for AGL Qt5-based Cluster Distribution. + Profiles include support for Wayland images with Qt5. +* `meta-agl-profile-core`: Configuration and recipes for the AGL core profiles. +* `meta-agl-profile-graphical`: Configuration and recipes supporting graphical user + interfaces. +* `meta-agl-profile-graphical-html5`: Configuration and recipes supporting profiles + with HTML user interface support. +* `meta-agl-profile-graphical-qt5`: Configuration and recipes supporting profiles + with Qt5-based user interface support. +* `meta-agl-profile-hud`: Configuration and recipes supporting profiles with + Head-Up-Display (HUD) support. +* `meta-agl-profile-telematics`: Configuration and recipes supporting profiles with + telematics support. +* `meta-app-framework`: Configuration and recipes supporting the AGL Application + Framework. +* `meta-netboot`: Contains recipes and configuration adjustments to allow network + boot through network block device (NBD) since network file system (NFS) does not + support security labels. +* `meta-security`: Configuration and recipes supporting security applications. +* `scripts`: AGL development setup and support scripts. +* `templates`: Base, feature, and machine templates used in the AGL development + environment. + +## Packagegroups + +This section describes the AGL +[packagegroup](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks) +design: + +* packagegroup-agl-image-minimal + + packagegroup-agl-core-automotive.bb + packagegroup-agl-core-connectivity.bb + packagegroup-agl-core-graphics.bb + packagegroup-agl-core-kernel.bb + packagegroup-agl-core-multimedia.bb + packagegroup-agl-core-navi-lbs.bb + packagegroup-agl-core-os-commonlibs.bb + packagegroup-agl-core-security.bb + packagegroup-agl-core-speech-services.bb + + The previous list of Packagegroups are used to create the `agl-image-minimal` image, + which is a small image just capable of allowing a device to boot. + + Subsystem should maintain packagegroup-agl-core-[subsystem].bb which should + hold sufficient packages to build `agl-image-minimal`. + +* packagegroup-agl-image-ivi + + packagegroup-agl-ivi-automotive.bb + packagegroup-agl-ivi-connectivity.bb + packagegroup-agl-ivi-graphics.bb + packagegroup-agl-ivi-kernel.bb + packagegroup-agl-ivi-multimedia.bb + packagegroup-agl-ivi-navi-lbs.bb + packagegroup-agl-ivi-os-commonlibs.bb + packagegroup-agl-ivi-security.bb + packagegroup-agl-ivi-speech-services.bb + + The previous list of Packagegroups are used to create the `agl-image-ivi` + image, which is a baseline image (i.e. Service Layer and Operating System + Layer defined in AGL Spec v1.0) for the AGL profiles. + +* packagegroup-agl-test.bb + + Additional tools used in QA tests (for agl-image*-qa). + diff --git a/docs/04_Developer_Guides/02_AGL_Layers/03_meta_agl_demo.md b/docs/04_Developer_Guides/02_AGL_Layers/03_meta_agl_demo.md new file mode 100644 index 0000000..c560989 --- /dev/null +++ b/docs/04_Developer_Guides/02_AGL_Layers/03_meta_agl_demo.md @@ -0,0 +1,159 @@ +--- +title: meta-agl-demo +--- + +## Introduction + +The `meta-agl-demo` layer is the reference user interface layer for the DEMO +platform of Automotive Grade Linux (AGL). +The layer provides a reference platform and applications. +The BitBake target name for the DEMO platform is `agl-demo-platform`, which is +the full DEMO platform image. + +## Layer Dependencies + +This section describes dependencies for the `meta-agl-demo` layer. +Dependencies are grouped into base, hardware, and feature dependencies. + +### Base Dependencies + +The `meta-agl-demo` layer has the following base dependencies: + +- Yocto Project Release: + + - URI: git://git.yoctoproject.org/poky + - Branch: "thud" + - Tested Revision: See the + [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision information. + +- AGL `meta-agl` Layer: + + - URI: https://gerrit.automotivelinux.org/gerrit/AGL/meta-agl + - Branch: "master" + +- OpenEmbedded `meta-openembedded` Layer: + + - Branch: "thud" + - Tested Revision: See the + [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision information. + + Specifically, out of `meta-openembedded`, these sub-layers are used: + + - `meta-oe` + - `meta-multimedia` + - `meta-networking` + - `meta-python` + +- Yocto Project `meta-qt5` Layer from the + [OpenEmbedded Layer Index](https://layers.openembedded.org/layerindex/branch/master/layers/): + + - URI: https://github.com/meta-qt5/meta-qt5.git + - Branch: "thud" + - Tested Revision: See the + [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision information. + +### Hardware Dependencies + +Aside from the previously listed base dependencies, if you are using a +[supported Renesas board](../../0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3.md) +supported Renesas board, these dependencies exist: + +- AGL's `meta-renesas` Layer: + + - URI: https://gerrit.automotivelinux.org/gerrit/AGL/meta-renesas + +### Feature Dependencies + +The `meta-agl-demo` layer has the following AGL [feature](../../0_Getting_Started/2_Building_AGL_Image/3_Initializing_Your_Build_Environment.md#agl-features) +dependencies: + +- Yocto Project `meta-security` Layer: + + - URI: https://git.yoctoproject.org/cgit/cgit.cgi/meta-security + - Branch: "master" + - Tested Revision: See the + [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision information. + +- AGL's `meta-app-framework` Layer within the `meta-agl` Layer: + + - URI: https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git + - Branch: "master" + +**The `agl-sota` Feature:** + +- Here Technologies' `meta-updater` Layer: + + - URI: https://github.com/advancedtelematic/meta-updater/ + - Branch: "thud" + +- Here Technologies' `meta-updater-qemux86-64` Layer: + + - URI: https://github.com/advancedtelematic/meta-updater-qemux86-64/ + - Branch: "thud" + +- OpenEmbedded's `meta-openembedded` Layer: + + - URI: https://github.com/openembedded/meta-openembedded + - Branch: "thud" + - Tested Revision: See the + [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision information. + + Specifically, out of `meta-openembedded`, these sub-layers are used: + + - `meta-filesystems` + - `meta-oe` + - `meta-python` + +**The `agl-netboot` Feature:** + +- AGL's `meta-netboot` Layer within the `meta-agl` Layer: + + - URI: https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git + - Branch: "master" + + +## Packagegroups + +AGL DEMO Platform's [packagegroups](https://www.yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks) +consist of the following: + +- packagegroup-agl-demo-platform + + This packagegroup is used for generating the `agl-demo-platform` image, + which is the full image for the AGL distributions IVI profile. You can see the + recipe (i.e. `agl-demo-platform.bb`) that installs the + `packagegroup-agl-demo-platform` packagegroup [here](https://git.automotivelinux.org/AGL/meta-agl-demo/tree/recipes-platform/images/agl-demo-platform.bb). + + As meta-agl's design of packagegroups, the `agl-demo-platform.bb` recipe installs + only `packagegroup-agl-demo-platform` and the packages of the DEMO applications. + + ``agl-demo-platform`` contains the following three packagegroups: + + * `packagegroup-agl-image-minimal` + * `packagegroup-agl-image-ivi` + * `packagegroup-agl-demo-platform` + +- packagegroup-agl-appfw* + + These packagegroups contain packages for the AGL distribution's + Application Framework. Subsystem should maintain + `packagegroup-agl-appfw-[subsystem].bb`, which should hold sufficient packages + for the Application Framework. + + Subsystems also can maintain their own packagegroups using appropriate + `recipes-*/`. + + For example, Qt5 has two packagegroups in `meta-agl-demo`: + `packagegroup-agl-appfw-native-qt5` and `packagegroup-agl-demo-qt-examples`, + which are under `recipes-qt/`. + + The `packagegroup-agl-appfw-native-qt5` is included by `packagegroup-agl-appfw-native` because Qt5 belongs to native application framework of AGL Distro. + + Because the `packagegroup-agl-demo-qt-examples` is not mandatory for the AGL + Application Framework and the AGL DEMO, the packagegroup is added to the layer's + `local.conf` file only when needed. \ No newline at end of file diff --git a/docs/04_Developer_Guides/02_AGL_Layers/04_meta_agl_devel.md b/docs/04_Developer_Guides/02_AGL_Layers/04_meta_agl_devel.md new file mode 100644 index 0000000..d662ed5 --- /dev/null +++ b/docs/04_Developer_Guides/02_AGL_Layers/04_meta_agl_devel.md @@ -0,0 +1,143 @@ +--- +title: meta-agl-devel +--- + +## Introduction + +The `meta-agl-devel` layer contains components that are being tested or +still in development. +The layer also contains software packages that Original Equipment +Manufacturers (OEMs) need but are not included in the AGL software. + +## Sub-Layers + +The `meta-agl-devel` layer contains the following files and sub-layers: + +``` +. +├── meta-agl-telemetry +├── meta-audio-4a-framework +├── meta-audio-soundmanager-framework +├── meta-egvirt +├── meta-gstrecorder-rcar-gen3 +├── meta-hmi-framework +├── meta-oem-extra-libs +├── README.md +├── templates +``` + +The following list provides a summary of these sub-layers: + +* `meta-agl-telemetry`: Provides the smallest AGL image. + The image is designed to be used when a device requires restricted + scope of responsibilites (e.g. collecting vehicle telemetry). + +* `meta-audio-4a-framework`: A collection of recipes used for the + first integration of 4A (i.e. Advanced AGL Audio Architecture). + +* `meta-pipewire`: A collection of recipes used for the integration + of the pipewire sound system. + +* `meta-audio-soundmanager-framework`: Supports the Soundmanager + Audio Framework features, which maps to the `agl-audio-soundmanager-framework` + AGL feature. + +* `meta-egvirt`: The AGL Virtualization Expert Group (EG-VIRT) layer. + This layer supports the design, test, implementation, and assessment + of virtualization technologies (e.g. containers, hypervisors, system + partitioners, and so forth) aimed at AGL ARMv8 and Intel platforms. + +* `meta-gstrecorder-rcar-gen3`: Supports streaming audio and video for + the Pro and Premier board kits (e.g. + [Renesas R-Car Starter Kit Pro Board](https://www.elinux.org/R-Car/Boards/M3SK) + and + [Renesas R-Car Starter Kit Premier Board](https://www.elinux.org/R-Car/Boards/H3SK)). + +* `meta-hmi-framework`: Provides AGL's Human Machine Interface (HMI) framework + through resource management consisting of sounds, windows, and input control. + For more information, see the + [HMI-Framework Page](https://wiki.automotivelinux.org/hmiframework) of the + AGL Wiki. + +* `meta-oem-extra-libs`: Provides libraries and software packages needed by + OEMs but not provided by the AGL software. + +* `templates`: Feature templates that support the `meta-agl-devel` layer. + +## Additional Sub-Layer Information + +This section provides additional information for the `meta-egvirt`, +`meta-oem-extra-libs`, and `meta-hmi-framework` layers. + +### Virtualization Support + +The `meta-egvirt` layer enables virtualization support in AGL. +The AGL Virtualization Expert (EG-VIRT) group is responsible +for design and implementation of AGL virtualization solutions +(.e.g the Virtualization platform architecture of AGL). +You can read about EG-VERT's efforts on the +"[Virtualization Expert Group's](https://wiki.automotivelinux.org/eg-virt)" +page of the AGL wiki. + +Additionally, you can learn more about virtualization as it applies to AGL +by reading +"[The Automotive Grade Linux Software Defined Connected Car Architecture](https://www.automotivelinux.org/wp-content/uploads/sites/4/2018/06/agl_software_defined_car_jun18.pdf)" +whitepaper. + +### OEM Extra Libraries + +The `meta-oem-extra-libs` layer provides additional software packages many OEMs need +but are not part of the AGL source. +Following is the list of packages this layer provides: + + * boost + * fixesproto + * imagemagick + * iptables + * Xorg-macros + * zlib + * eglibc = glibc + * libcurl + * libgif + * libneon + * mongoose + * fuse + * protocol buffers + * bsdiff + * module-init-tools + * libcroco + * libtiff + * librsvg + * libpcap + +To add these packages to your library, you need to include the +`agl-oem-extra-libs` AGL feature when you initialize your build +environment using the `aglsetup.sh` script. + +For information on how to use the `aglsetup.sh` script to initialize +your build environment, see the +"[Initializing Your Build Environment](../../01_Getting_Started/02_Building_AGL_Image/04_Initializing_Your_Build_Environment.md)" +section. + +Once you have included the AGL feature, you can build your image. + +### HMI Framework + +The `meta-hmi-framework` layer supports the Human-Machine Interface (HMI) Framework. +The HMI-Framework is the User Interface (UI) to control the Infotainment System. +Work continues to close the gap between the user experience of a smart phone +and the Infotainment System in a vehicle, for example. + +You can find more out about HMI Framework progress on the +"[HMI Framework](https://wiki.automotivelinux.org/hmiframework)" page on the AGL Wiki. + +To add HMI Framework support to your image, you need to include the +`hmi-framework` AGL feature when you initialize your build +environment using the `aglsetup.sh` script. + +For information on how to use the `aglsetup.sh` script to initialize +your build environment, see the +"[Initializing Your Build Environment](../../01_Getting_Started/02_Building_AGL_Image/04_Initializing_Your_Build_Environment.md)" +section. + +Once you have included the AGL feature, you can build your image. diff --git a/docs/04_Developer_Guides/02_Creating_a_New_Service.md b/docs/04_Developer_Guides/02_Creating_a_New_Service.md new file mode 100644 index 0000000..22e98ea --- /dev/null +++ b/docs/04_Developer_Guides/02_Creating_a_New_Service.md @@ -0,0 +1,151 @@ +--- +title: Creating a New Service +--- + +Services are software running in the background and providing, as their name suggests, +various services to other software: access to specific system hardware, connectivity +management, and network servers. Services can be split into 2 categories: + +- **System services:** those usually run as a privileged user and make use of shared system + resources which they should have exclusive access to + +- **User services:** such services run as part of an unprivileged user's session and can + only be called by said user + +# Basic requirements + +The only mandatory requirement is that service packages provide a `.service` file +so they can be properly managed by `systemd`. This file must be installed to a specific +location, determined by the service type (system or user): + +- `/usr/lib/systemd/system/` for system services + +- `/usr/lib/systemd/user/` for user services + +Below is an example of a simple user service, running in a graphical session and +therefore requiring a compositor to be already running before the service starts: + +``` +[Unit] +Requires=agl-compositor.service +After=agl-compositor.service + +[Service] +Type=simple +ExecStart=/usr/bin/homescreen +Restart=on-failure + +[Install] +WantedBy=agl-session.target +``` + +The `WantedBy=agl-session.target` indicates the service is part of the default AGL +user session, as mentioned in the [Application Framework](../01_Application_Framework/01_Introduction/#user-session-management) +documentation. + +The `Restart=on-failure` directive ensures the service will be automatically +restarted by `systemd` in case it crashes. + +More details about `systemd` service files can be found in the +[systemd documentation](https://www.freedesktop.org/software/systemd/man/systemd.service.html). + +# D-Bus activation + +Services can also provide a D-Bus interface. In this case, they need not be started +on system boot (or user session startup in the case of user services) but can be +automatically started only when a client sends a request to the D-Bus name the service +registers. + +D-Bus activated services must name their `systemd` service file `dbus-NAME.service` +where `NAME` is the D-Bus name registered by the service. This file must include the +following lines: + +``` +[Service] +Type=dbus +BusName=NAME +ExecStart=/path/to/executable +``` + +In addition, they must provide a D-Bus service file named `NAME.service` and installed +to one of the following locations: + +- `/usr/share/dbus-1/system-services` for system services + +- `/usr/share/dbus-1/services` for user services + +The contents of the D-Bus service file must be the following: + +``` +[D-BUS Service] +Name=NAME +Exec=/path/to/executable +SystemdService=dbus-NAME.service +``` + +This ensures the service can be safely activated through D-Bus and no conflict will occur +between `systemd` and the D-Bus daemon. + +More details about D-Bus activation can be found in the +[D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services), +under the "Message Bus Starting Services (Activation)" section. + +# Services startup + +For D-Bus activated services, no additional action is required as those will be automatically +started whenever needed. Other services, however, need a few more steps in order to be +executed on system or session startup. + +## System services + +System services can take advantage of the Yocto `systemd` class which automates the process of +enabling such services. + +1\. Ensure the recipe inherits from the `systemd` class: + +``` +inherit systemd +``` + +2\. Declare the system services that needs to be enabled on boot: + +``` +SYSTEMD_SERVICE:${PN} = "NAME.service" +``` + +3\. Ensure the `FILES` variable includes the systemd service directory the corresponding +file will be installed to: + +``` +FILES:${PN} = "\ + ... + ${systemd_system_unitdir}/* \ +" +``` + +## User services + +The `systemd` class doesn't provide an equivalent mechanism for user services. This must +therefore be done manually as part of the package's install process. + +1\. Make the service a part of the user session: + +``` +do_install:append() { + install -d ${D}${systemd_user_unitdir}/agl-session.target.wants + ln -s ../NAME.service ${D}${systemd_user_unitdir}/agl-session.target.wants/NAME.service +} +``` + +This ensures `agl-session.target` depends on `NAME.service`, the latter being therefore +automatically started on session creation. + +2\. Ensure the `FILES` variable includes the systemd service directory the corresponding +file will be installed to: + +``` +FILES:${PN} = "\ + ... + ${systemd_user_unitdir}/* \ +" +``` diff --git a/docs/04_Developer_Guides/03_Creating_a_New_Application.md b/docs/04_Developer_Guides/03_Creating_a_New_Application.md new file mode 100644 index 0000000..3fb7682 --- /dev/null +++ b/docs/04_Developer_Guides/03_Creating_a_New_Application.md @@ -0,0 +1,135 @@ +--- +title: Creating a New Application +--- + +Applications are: + +- Software designed to perform a specific task during a limited amount of time. +- Graphical interface allowing user to interact with. + +Applications are executed by `applaunchd`, the AGL +[application launcher service](../01_Application_Framework/02_Application_Startup/). + +# Basic requirements + +In order to be enumerated by `applaunchd`, applications must provide the a `.desktop` file, as +defined by the [Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html). + +The desktop entry file should be installed to `/usr/share/applications` (or the `applications` +sub-directory of any entry present in the `XDG_DATA_DIRS` environment variable) and have a +meaningful name. It is considered good practice to use reverse-DNS notation for the desktop +entry file name, following the recommendations of the [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names): +- this avoids potential name collisions with other desktop entry files +- it makes it easier to enable [D-Bus activation](#d-bus-activation) during the application + development cycle if needed +- for [graphical applications](#graphical-applications), it ensures the chosen Wayland `app-id` + will be unique + +Such a file must contain at least the following keys: +- `Type`: desktop entry type, must be set to `Application` +- `Name`: application name, as it should be displayed in menus and application launchers +- `Exec`: full path to the main executable + +Below is an example of a minimal desktop entry file: + +``` +[Desktop Entry] +Type=Application +Name=Example Application +Exec=/usr/bin/example-app +``` + +Graphical applications must also provide an `Icon` entry pointing to the application icon. +The value for this entry must either be the full path to the icon's file or, for icons part +of an existing [icon theme](https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html), +the name of an element of this theme. + +In addition, a number of optional fields can be used to change how `applaunchd` will consider the +application: +- `Version`: version of the Desktop Entry Specification the file conforms to, must be `1.5` +- `Hidden`: boolean value, if `true` the application is always ignored by `applaunchd` and + won't be listed nor executed +- `Terminal`: boolean value, if `true` the application is excluded when requesting the list of + graphical applications from `applaunchd` +- `DBusActivatable`: boolean value, must be `true` for [D-Bus activated applications](#d-bus-activation) +- `Implements`: list of D-Bus interfaces the application implements, only used for D-Bus activated + applications. + +Finally, graphical applications may also define the `StartupWMClass` key in some cases. Please +refer to the [graphical applications](#graphical-applications) section for more information. + +# D-Bus activation + +Similarly to [services](../2_Creating_a_New_Service/#d-bus-activation), applications can +also be activated through D-Bus. + +Such applications must name their `.desktop` file after the D-Bus name they register. In addition, +this file must contain the following entries: + +``` +DBusActivatable=true +Implements=IFACE1;IFACE2;... +``` + +Where `IFACEn` are the names of the D-Bus interfaces the application implements. + +In addition, they must provide a D-Bus service file named `NAME.service` and installed +to `/usr/share/dbus-1/services`. + +The contents of the D-Bus service file must be the following: + +``` +[D-BUS Service] +Name=NAME +Exec=/path/to/executable +``` + +For example, an application registering the `org.automotivelinux.Example` D-Bus name +and implementing the `org.automotivelinux.Example.Search1` and `org.automotivelinux.Example.Execute1` +interfaces would provide the following files: + +* Desktop entry (`/usr/share/applications/org.automotivelinux.Example.desktop`): + +``` +[Desktop Entry] +Type=Application +Version=1.5 +Name=Example Application +Exec=/usr/bin/example-app +Icon=example-icon +Terminal=false +DBusActivatable=true +Implements=org.automotivelinux.Example.Search1;org.automotivelinux.Example.Execute1 +``` + +* D-Bus service file (`/usr/share/dbus-1/services/org.automotivelinux.Example.service`): + +``` +[D-BUS Service] +Name=org.automotivelinux.Example +Exec=/usr/bin/example-app +``` + +*Note: in addition to their own D-Bus interface, D-Bus activated applications must also +implement the `org.freedesktop.Application` interface as defined in the +[Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html).* + +# Graphical applications + +In addition, graphical applications need to comply with a few more requirements: + +1\. Each application must set a Wayland application ID appropriately as soon as its main window +is created. + +2\. The `app-id` must be specified in the desktop entry file by adding the following line: + +``` +StartupWMClass=APP_ID +``` + +3\. The desktop entry file must be named `APP_ID.desktop`. + +Doing so will ensure other software can associate the actual `app-id` to the proper application. + +*Note: application ID's are set using the [XDG toplevel](https://wayland-book.com/xdg-shell-basics/xdg-toplevel.html) +Wayland interface.* diff --git a/docs/04_Developer_Guides/04_Creating_a_custom_recipe.md b/docs/04_Developer_Guides/04_Creating_a_custom_recipe.md new file mode 100644 index 0000000..f8650e8 --- /dev/null +++ b/docs/04_Developer_Guides/04_Creating_a_custom_recipe.md @@ -0,0 +1,49 @@ +--- +title: Creating a Custom Recipe +--- + + +For adding a custom linux software/service like cannelloni you have to do the following steps: + +1. Add repo via devtool (gitrepo stands for the url) + + ``` + devtool add gitrepo + ``` +2. Try to bitbake, if it is working go to step 3 + + ``` + bitbake packagename (gitrepo name) + ``` + If it is not working you can do (repeating) following steps until it is working + + 1. change/modify the recipe in /workspace/recipe/packagename + 2. change/modify the sources in /workspace/sources/packagename + 3. bitbake packagename + + Now update the recipe, if you do this the first time you have to adapt the license and the LIC-File-Checksum + + ``` + devtool update-recipce packagename + ``` + +3. Build the recipe and image with devtool + + ``` + devtool build packagename + devtool build-image agl-demo-platform + ``` + + If that is working you could add it to git/gerrit. You have to add your recipe to a layer. + + 1. Copy files to the recipe + 2. add recipe to a packagegroup + +4. Git + + ``` + git review + git review -s + git remote -v update + ``` +![Build recipe](images/AGL_add_recipe.png) \ No newline at end of file diff --git a/docs/04_Developer_Guides/05_Generic_devices_setup.md b/docs/04_Developer_Guides/05_Generic_devices_setup.md new file mode 100644 index 0000000..af05096 --- /dev/null +++ b/docs/04_Developer_Guides/05_Generic_devices_setup.md @@ -0,0 +1,94 @@ +--- +title: Generic devices setup +--- + +## Camera setup on RPi4 + +This assumes that you'll be using the Raspberry Pi Camera Module, which can +easily hooked on the board using the LVDS connector. Further more information +about how to connect it, could be found at +[Installing a Raspberry Pi camera](https://www.raspberrypi.com/documentation/accessories/camera.html#installing-a-raspberry-pi-camera) + +With the camera installed, you'll need to enable it by editing /boot/config.txt +file (if you're booting an AGL image over a sd-card it will be there by +default, otherwise -- in case of doing netboot, you'll have to create +manually) and add the following entry: + + + ## start_x + ## Set to "1" to enable the camera module. + ## + ## Enabling the camera requires gpu_mem option to be specified with a value + ## of at least 128. + ## + ## Default 0 + ## + start_x=1 + +And reboot your device. Afterwards, after logging it, make sure that you have +the /dev/video0 device created. You could also use v4l2-ctl to verify +that is indeed usable as a capture device: + + $ v4l2-ctl -d /dev/video0 --all + +In order to test out video playback, use the following gstreamer pipeline: + + $ gst-launch-1.0 v4l2src device=/dev/video0 ! \ + video/x-raw,width=640,height=480 ! waylandsink fullscreen=true + +Alternatively, using [camera-gstreamer](https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps/camera-gstreamer.git;a=summary) +application could might be another possibility, but you'll have to build it +yourself and add it in the image. + +This includes an example on how to create a xdg-toplevel surface and create a +gstreamer pipeline, instead of relaying on waylandsink to create one for you, +in a programmatic fashion. + +## Display setup on RPi4 + +This assumes that you'll be using the Raspberry Pi 7'' display. Installation +can be found at [Rpi Display page](https://www.raspberrypi.com/documentation/accessories/display.html). + +If booting over the network, the dtb should already contain the ft5406 dtb, +while booting over sd-card the following show be in the /boot/config.txt +file: + + dtoverlay=rpi-ft5406-overlay + +Once the board boots up, you should get a rainbow like effect and afterwards +booting up would display debug scrolling over. You'll need to adjust the +orientation as the 800x480 is in portrait. Edit /etc/xdg/weston/weston.ini and +add a new output entry, like the following: + + [output] + name=DSI-1 + transform=90 + +Note that for the Qt platform, the homescreen application, together with the +other demo applications, is tailored specifically for a 1080p display and it +will display incorrectly on such a smaller display. + +## Testing out video camera without a real device + +While the above requires having a real video camera device, one can use out +the [vivid module](https://docs.kernel.org/admin-guide/media/vivid.html?highlight=vivid#the-virtual-video-test-driver-vivid) +to try out your custom application or just testing out camera functionality in AGL. + +You should normally have the module present, not loaded, for either **rpi4** or for +**h3ulcb** boards. Load the module, like in the following command: + + modprobe vivid allocators=0x1 + +Have a look at the kernel ring buffer to see what capture devices are created +and use as source: + + $ gst-launch-1.0 v4l2src device=/dev/videoXX ! \ + video/x-raw,width=640,height=480 ! waylandsink fullscreen=true + +making sure to replace /dev/videoXX with correct capture device. You can check +that easily using the v4l2-ctl mentioned above. + +Note that using camera-gstreamer will attempt to find the first available +capture device, so if you happen to have to another one before the one created +by this module it might not work. You can bypass that, by just making a symlink +from /dev/videoXX to /dev/video0 to make first available capture device. diff --git a/docs/04_Developer_Guides/images/AGL_add_recipe.png b/docs/04_Developer_Guides/images/AGL_add_recipe.png new file mode 100644 index 0000000..07b44b6 Binary files /dev/null and b/docs/04_Developer_Guides/images/AGL_add_recipe.png differ -- cgit 1.2.3-korg