Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Cleanup user-guide pages l-mi #586

Merged
merged 1 commit into from
Aug 24, 2023
Merged

Cleanup user-guide pages l-mi #586

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 28 additions & 46 deletions source/user-guide/lmp-auto-hostname/lmp-auto-hostname.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,32 +3,24 @@
Auto Hostname
=============

This section shows how to enable the ``lmp-auto-hostname`` recipe. This recipe customizes
device hostnames at runtime, either by appending the **serial** number
from the device tree of the hardware, or the **mac address** to the hostname.
This section shows how to enable ``lmp-auto-hostname``.
This utility customizes a device's hostname at runtime, by appending it with either the **serial** number from the device tree, or the **mac address**.

The recipe lmp-auto-hostname_ is provided by meta-lmp_ and can be added by
customizing your ``meta-subscriber-overrides.git``.
The recipe for lmp-auto-hostname_ is provided by meta-lmp_ and can be added by customizing ``meta-subscriber-overrides.git``.

Check failure on line 9 in source/user-guide/lmp-auto-hostname/lmp-auto-hostname.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'", "location": {"path": "source/user-guide/lmp-auto-hostname/lmp-auto-hostname.rst", "range": {"start": {"line": 9, "column": 16}}}, "severity": "ERROR"}

Enabling Recipe
---------------
Adding the Recipe
-----------------

Clone your ``meta-subscriber-overrides.git`` repo and enter its directory:

.. prompt:: bash host:~$

git clone -b devel https://source.foundries.io/factories/<factory>/meta-subscriber-overrides.git
git clone https://source.foundries.io/factories/<factory>/meta-subscriber-overrides.git
cd meta-subscriber-overrides

Edit the ``recipes-samples/images/lmp-factory-image.bb`` file and add the recipe on the ``CORE_IMAGE_BASE_INSTALL`` list:
Edit ``recipes-samples/images/lmp-factory-image.bb``, adding the recipe to the ``CORE_IMAGE_BASE_INSTALL`` list:

.. prompt:: bash host:~$, auto

host:~$ gedit recipes-samples/images/lmp-factory-image.bb

**recipes-samples/images/lmp-factory-image.bb**:

.. prompt:: text
.. code-block:: diff

diff --git a/recipes-samples/images/lmp-factory-image.bb b/recipes-samples/images/lmp-factory-image.bb
--- a/recipes-samples/images/lmp-factory-image.bb
Expand All @@ -52,37 +44,34 @@

.. option:: serial

appends the serial number of the device.
Appends the serial number of the device:

**Example Result:** ``raspberrypi4-64-100000008305bbc3``
``raspberrypi4-64-100000008305bbc3``

.. option:: mac

appends the MAC address of a chosen network interface.
Appends the MAC address of a chosen network interface.

**Example Result:** ``raspberrypi4-64-dca6321669ea``
``raspberrypi4-64-dca6321669ea``

.. confval:: LMP_HOSTNAME_NETDEVICE=<interface>
:default: ``eth0``

*if* using ``mac`` mode, provide the device network interface to retrieve
a MAC address from.
If using ``mac`` mode, provide the device network interface to retrieve a MAC address from:

**Example Value:** ``eth0`` or ``wlan0``
``eth0`` or ``wlan0``

Configuring the LmP Auto Hostname
---------------------------------

According to your needs, select the tab serial or MAC.
Select the Serial or MAC tab below, according to your needs.

.. tabs::

.. group-tab:: Serial

Serial is configured by default in the ``lmp-auto-hostname`` recipe,
no need for extra changes.

Add the ``recipes-samples/images/lmp-factory-image.bb`` file, commit and push:
Serial is configured by default in the ``lmp-auto-hostname`` recipe, no need for extra changes.
Add the ``recipes-samples/images/lmp-factory-image.bb`` file, commit, and push:

.. prompt:: bash host:~$, auto

Expand All @@ -91,20 +80,18 @@

.. group-tab:: MAC

Edit the ``conf/machine/include/lmp-factory-custom.inc`` file and add the variables:
Edit ``conf/machine/include/lmp-factory-custom.inc``, adding the variables:

.. prompt:: bash host:~$, auto

host:~$ gedit recipes-samples/images/lmp-factory-image.bb

**conf/machine/include/lmp-factory-custom.inc**:

.. prompt:: text
::

LMP_HOSTNAME_MODE = "mac"
LMP_HOSTNAME_NETDEVICE = "eth0"

Add the changed files, commit and push:
Add the changed files, commit, and push:

.. prompt:: bash host:~$, auto

Expand All @@ -113,17 +100,16 @@
host:~$ git commit -m "lmp-auto-hostname: Adding recipe"
host:~$ git push

The latest **Target** named ``platform-devel`` should be the CI job you just created.
The latest Target named ``platform-devel`` should be the CI job you just created.

When FoundriesFactory CI finishes all jobs, if your device is already registered,
wait until the Over-the-Air update finishes, otherwise download and flash the image.
If your device is already registered, when all jobs finish, wait until the Over-the-Air update completes.
Otherwise download and flash the image.

Testing Auto Hostname
---------------------

Log in to the device via SSH and check the new hostname right after ``fio@``.

Check also the file ``/etc/hostname`` to confirm the new hostname.
Log in to the device via SSH and check the new hostname (right after ``fio@``).
You can also check ``/etc/hostname`` to confirm the new hostname.

.. tabs::

Expand All @@ -133,9 +119,7 @@

cat /etc/hostname

**Example Output**:

.. prompt:: text
::

raspberrypi3-64-51ca7875

Expand All @@ -145,11 +129,9 @@

cat /etc/hostname

**Example Output**:

.. prompt:: text
::

raspberrypi3-64-b827ebca7875
raspberrypi3-64-b827ebca7875

.. _meta-lmp: https://github.com/foundriesio/meta-lmp/tree/main
.. _lmp-auto-hostname: https://github.com/foundriesio/meta-lmp/tree/main/meta-lmp-base/recipes-support/lmp-auto-hostname
2 changes: 1 addition & 1 deletion source/user-guide/lmp-customization/lmp-customization.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
LmP Customization
======================

This page covers some common ways that the Linux® microPlatform (LmP) can be modified.
This page covers common ways that the Linux® microPlatform (LmP) can be modified.
This includes kernel options, startup services, user and group configuration,
and other options related to the platform build.

Expand Down
117 changes: 40 additions & 77 deletions source/user-guide/lmp-device-auto-register/lmp-device-auto-register.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,39 +3,34 @@
Auto Register
=============

This section shows how to enable the ``lmp-device-auto-register`` recipe. This
recipe creates a systemd oneshot service that will automatically register the
device on first boot once it has internet connectivity.
This is done by providing an API Token that has **devices:create** scope.
This section shows how to enable ``lmp-device-auto-register``.
This utility creates a systemd oneshot service that registers the device on first boot—once it has internet connectivity.
This is done by providing an API Token with **devices:create** scope.

.. warning::
Do not use the API Token in production. The use of an API Token is only intended for
usage in a development environment. For more information, read
:ref:`ref-factory-registration-ref`.
As customers move closer to production, do not hesitate to contact Foundries.io
to discuss the best practices to automatically register devices.
Do not use the API Token in production.
They are intended only for usage in a development environment.
For more information, read :ref:`ref-factory-registration-ref`.
When close to production, do not hesitate to contact Foundries.io™ to discuss best practices for automatically registering devices.

The recipe lmp-device-auto-register_ is provided by meta-lmp_ and can be added by
customizing your ``meta-subscriber-overrides.git``.
The recipe for lmp-device-auto-register_ is provided by meta-lmp_ and can be added by customizing your ``meta-subscriber-overrides.git``.

Check failure on line 16 in source/user-guide/lmp-device-auto-register/lmp-device-auto-register.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'", "location": {"path": "source/user-guide/lmp-device-auto-register/lmp-device-auto-register.rst", "range": {"start": {"line": 16, "column": 16}}}, "severity": "ERROR"}

Prerequisites
-------------

To follow this section, it is important to have:

- Completed the :ref:`sec-learn` until the :ref:`gs-flash-device` section.
- Completed the getting started guide up to :ref:`gs-flash-device`.

Creating Token
--------------

Go to `Tokens <https://app.foundries.io/settings/tokens>`_ and create a new **Api Token** by clicking on
:guilabel:`+ New Token`.
Go to `Tokens <https://app.foundries.io/settings/tokens>`_ and create a new **Api Token** by clicking on :guilabel:`+ New Token`.

Complete with a **Description** and the **Expiration date** and select :guilabel:`next`.

Select the :guilabel:`device:create` token and
select your **Factory**. You can later revoke this access and set up a new
token once you are familiar with the :ref:`ref-api-access`.
Select the :guilabel:`device:create` token and select your **Factory**.
You can later revoke this access and set up a new token once you are familiar with the :ref:`ref-api-access`.

.. figure:: /_static/userguide/lmp-device-auto-register/lmp-device-auto-register-token.png
:width: 500
Expand All @@ -46,22 +41,16 @@
Enabling Recipe
---------------

Clone your ``meta-subscriber-overrides.git`` repo and enter its directory:
Clone your ``meta-subscriber-overrides.git`` and enter its directory:

.. prompt:: bash host:~$

git clone -b devel https://source.foundries.io/factories/<factory>/meta-subscriber-overrides.git
git clone https://source.foundries.io/factories/<factory>/meta-subscriber-overrides.git
cd meta-subscriber-overrides

Edit the ``recipes-samples/images/lmp-factory-image.bb`` file and add the recipe on the ``CORE_IMAGE_BASE_INSTALL`` list:
Edit ``recipes-samples/images/lmp-factory-image.bb``, adding the recipe to the ``CORE_IMAGE_BASE_INSTALL`` list:

Check failure on line 51 in source/user-guide/lmp-device-auto-register/lmp-device-auto-register.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'", "location": {"path": "source/user-guide/lmp-device-auto-register/lmp-device-auto-register.rst", "range": {"start": {"line": 51, "column": 31}}}, "severity": "ERROR"}

.. prompt:: bash host:~$, auto

host:~$ gedit recipes-samples/images/lmp-factory-image.bb

**recipes-samples/images/lmp-factory-image.bb**:

.. prompt:: text
.. code-block:: diff

diff --git a/recipes-samples/images/lmp-factory-image.bb b/recipes-samples/images/lmp-factory-image.bb
--- a/recipes-samples/images/lmp-factory-image.bb
Expand All @@ -78,42 +67,25 @@
Configuring the LmP Auto Register
---------------------------------

Create the required directory structure for this recipe:
Create the required directory structure for the recipe:

.. prompt:: bash host:~$, auto

host:~$ mkdir -p recipes-support/lmp-device-auto-register/lmp-device-auto-register

host:~$ mkdir -p recipes-support/lmp-device-auto-register/lmp-device-auto-register
Create the ``api-token`` file and replace ``<YOUR_API_TOKEN>`` with the scoped token created in the previous steps:

Create the ``api-token`` file and replace ``<YOUR_API_TOKEN>`` with the scoped token
created in the previous steps:
``recipes-support/lmp-device-auto-register/lmp-device-auto-register/api-token``:

.. prompt:: bash host:~$, auto

host:~$ gedit recipes-support/lmp-device-auto-register/lmp-device-auto-register/api-token

**recipes-support/lmp-device-auto-register/lmp-device-auto-register/api-token**:

.. prompt:: text
::

<YOUR_API_TOKEN>

Create ``lmp-device-auto-register.bbappend`` in order to give the recipe access to the ``api-token`` file.

.. note::

If the process of auto registration is following the :ref:`ref-fully-detached` mode, then API
token filled here can be a bogus value. It only needs this because otherwise the
``lmp-device-register`` will try to do the OAuth flow still.

Create the file ``lmp-device-auto-register.bbappend`` in order to give the recipe
access to the ``api-token`` file.

.. prompt:: bash host:~$, auto

host:~$ gedit recipes-support/lmp-device-auto-register/lmp-device-auto-register.bbappend
``recipes-support/lmp-device-auto-register/lmp-device-auto-register.bbappend``:

**recipes-support/lmp-device-auto-register/lmp-device-auto-register.bbappend**:

.. prompt:: text
::

FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"

Expand All @@ -127,40 +99,33 @@
host:~$ git commit -m "lmp-device-auto-register: Adding recipe"
host:~$ git push

The latest **Target** named ``platform-devel`` should be the CI job you just created.
The latest Target should be the CI job you just created.

When FoundriesFactory CI finishes all jobs, download and flash the image.
When the CI finishes, download and flash the image.

.. note::

To get a better understanding of what is going on, one can look at the repository
lmp-device-auto-register_. In there is the Systemd Service file and the corresponding
shell script that all can be customised just like the API token file is being overwritten.
To get a better understanding of what is going on, one can look at the lmp-device-auto-register_ repo.
The Systemd Service file and corresponding shell script can be customized, just like the API token file is being overwritten.

Testing Auto Register
---------------------

After booting the new image, if connected to the internet, the device
will automatically register to your FoundriesFactory.
It should be visible by navigating to the `web interface <https://app.foundries.io/factories>`_, clicking your **Factory** and
selecting the **Devices** tab.
After booting the new image—if connected to the internet—the device will automatically register to your Factory.
It should be visible by navigating to the `web interface <https://app.foundries.io/factories>`_ and selecting the **Devices** tab.

.. figure:: /_static/userguide/lmp-device-auto-register/lmp-device-auto-register-device.png
:width: 900
:align: center
:alt: FoundriesFactory Device Auto Registered

FoundriesFactory Device Auto Registered

On your device, use the following command to list the ``lmp-device-auto-register``
service:
On your device, use the following command to list the ``lmp-device-auto-register`` service:

.. prompt:: bash device:~$

systemctl list-unit-files | grep enabled | grep lmp-device-auto-register
device:~$ systemctl list-unit-files | grep enabled | grep lmp-device-auto-register

**Example Output**:

.. prompt:: text
::

lmp-device-auto-register.service enabled enabled

Expand All @@ -170,15 +135,13 @@

device:~$ systemctl status lmp-device-auto-register

**Example Output**:

.. prompt:: text
::

lmp-device-auto-register.service - Script to auto-register device into Factory
Loaded: loaded (/usr/lib/systemd/system/lmp-device-auto-register.service; enabled; vendor preset: enabled)
Active: active (exited) since Sun 2021-09-12 17:34:06 UTC; 5min ago
Process: 774 ExecStart=/usr/bin/lmp-device-auto-register (code=exited, status=0/SUCCESS)
Main PID: 774 (code=exited, status=0/SUCCESS)
Loaded: loaded (/usr/lib/systemd/system/lmp-device-auto-register.service; enabled; vendor preset: enabled)
Active: active (exited) since Sun 2021-09-12 17:34:06 UTC; 5min ago
Process: 774 ExecStart=/usr/bin/lmp-device-auto-register (code=exited, status=0/SUCCESS)
Main PID: 774 (code=exited, status=0/SUCCESS)

.. _meta-lmp: https://github.com/foundriesio/meta-lmp/tree/main
.. _lmp-device-auto-register: https://github.com/foundriesio/meta-lmp/tree/main/meta-lmp-base/recipes-support/lmp-device-auto-register
Loading
Loading