WeOS
5.20.1

# Access External Media Devices Howto

## Introduction

This page aims to explain how external media devices are handled and made accessible for use in the system.

Currently it is only possible to utilize one external media device at a time. Most devices only have access to either a USB or a SD-Card, but some devices may have the possibility to connect both. In these situations only one of them will be accessible by the system, therefore it is recommended to only have one external media device connected at one time. In general, the system will try to prioritize SD-Cards, but it is more deterministic to only connect one device.

However, the system can support external media devices that have multiple partitions specified. In the eyes of the system each individual partition will be handled as a separate media. So if there is a need to have access to different devices this is how it can be achieved.

Each external media device that needs to be accessible on the device must be explicitly matched against a media definition. This definition specifies how a device will be known in the system and what physical external media it will be linked with. If no matching media definition is present for an external media or its individual partitions, they will not be mounted in the system.

This page will go through both how to format and partition a connected media device from the system itself, how to ensure that these medias are identified and made accessible for use.

For additional information on the Media tools and commands, refer to this page.

For additional information on the boot configuration commands, refer to this page.

## Partition and Format a Connected Media Device

It is possible to create up to four partitions on an external media device utilizing the systems built-in partitioning tool. This tool also allows the user to specify the wanted file system, selectable from the following file system types:

- vfat
- ext2
- ext3
- ext4

In addition, the size of the partitions needs to be set and an optional label can also be specified for the device. Later when we will set up the media definitions on the device this label can be used as a match indicator for the media. It is also possible to match a device’s partition number.

The dev names for a connected device will have the following naming convention when used in the media context for partition and formatting:

- Main disk device: sd[a-z]
- Partitions will be the same but with an added number for the partition instance: sd[a-z][1-9].

### Partitioning a Device Using the Partition Tool

This section will provide an example how an external media can be partitioned and formatted in a very simple and easy way using the built-in media tools. In this example we want to partition our device, named sdb, in the following manner:

# | Device Name | Partition Number | Label | Size | Filesystem
--- | --- | --- | --- | --- | ---
1 | sdb1 | 1 | default | 50% | ext3
2 | sdb2 | 2 | my-files | 20% | vfat
3 | sdb3 | 3 | - | 20% | ext2
4 | sdb4 | 4 | my-label | 10% | ext4

In order to partition the device in the manner described we enter the media context from the top level in the CLI:

    example:/#> media
    example:/media/#>

In order to partition the device we use the `partition` command on the correct device (this command is tab completable) to enter the partition context:

Tip

We can also check all the connected physical devices using the `show devices` command in the current context. We can only partition the devices of the type `disk`.

    example:/media/#> show devices
    NAME      TYPE  NUM  LABEL                      FORMAT   SIZE     MOUNT-MEDIA
    sda       disk  -    -                          -        16.0M    -

    example:/#> partition sdb
    Entering partitioning mode with dev sdb as target...

    No changes will be performed until the start-partition command is
    invoked. When invoked the entire device sdb will be fully re-partitioned
    and reformatted, any files on the device will be LOST/REMOVED, keep
    this in mind before proceeding.

    example:/media/partition-sdb/#>

In this context we can define how we want the device to be partitioned entirely before we start the operation by calling the `start-partitioning` command. Nothing will happen to the device before this is invoked, so it is possible to just leave the context without anything changing on the device.

In this case, since we want the fully re-partition the device, we remove any current partition configuration:

    example:/media/partition-sdb/#> delete all

Now we can add the definitions for the partitions we want to create, as we specified in the table above:

    example:/media/partition-sdb/#> add label default size 50% format ext3
    example:/media/partition-sdb/#> add label my-files size 20% format vfat
    example:/media/partition-sdb/#> add size 20% format ext2
    example:/media/partition-sdb/#> add label my-label size 10% format ext4

Before we initiate the partitioning and formatting of the device, it is best that we observe if the partitions we intend to create look as we expect:

    example:/media/partition-sdb/#> show
    Partition table for dev: sdb
    #  DEV-NAME      PART-NUMB  LABEL                          SIZE      FS
    1  /dev/sdb1     1          default                        50%       ext3
    2  /dev/sdb2     2          my-files                       20%       vfat
    3  /dev/sdb3     3          -                              20%       ext2
    4  /dev/sdb4     4          my-label                       10%       ext4

When we have verified that the setup is what we intended we can start the actual partitioning and formatting of the device:

Warning

When we start the partitioning we will also reformat the device, so any files will be removed. Ensure that the device does not contain any files that needs to be saved elsewhere.

    example:/media/partition-sdb/#> start-partitioning

    Understand that the content of media device will be lost during the
    partitioning and formatting of the device. Make sure that the device
    does not contain any files that needs to be saved elsewhere.

    Start partitioning and formatting of the device (y/N)? y
    Attempt to delete existing partitions on device /dev/sdb:
      1: /dev/sdb1 [Partition numb: 1]
      2: /dev/sdb2 [Partition numb: 2]
      3: /dev/sdb3 [Partition numb: 3]
      4: /dev/sdb4 [Partition numb: 4]

    Attempt to partition device /dev/sdb in the following manner:
      1: /dev/sdb1 [Partition numb: 1], [Size: 50%]
      2: /dev/sdb2 [Partition numb: 2], [Size: 20%]
      3: /dev/sdb3 [Partition numb: 3], [Size: 20%]
      4: /dev/sdb4 [Partition numb: 4], [Size: 10%]

    Initiate formatting of the partitions, this may take a while:
      1: /dev/sdb1 [Partition numb: 1] [Label: default], format with ext3 FS...
    Formatting: 100% \ [============================================================]

      2: /dev/sdb2 [Partition numb: 2] [Label: my-files], format with vfat FS...
    Formatting: 100% \ [============================================================]

      3: /dev/sdb3 [Partition numb: 3] [Label: -], format with ext2 FS...
    Formatting: 100% \ [============================================================]

      4: /dev/sdb4 [Partition numb: 4] [Label: my-label], format with ext4 FS...
    Formatting: 100% \ [============================================================]

    Device sdb successfully partitioned and formatted!
    example:/media/#>

If no error indications appeared, the device should now have been partitioned and formatted according to the specified configuration. We can verify this using the `show devices` command:

    example:/media/partition-sdb/#> show devices

    Connected Media Devices
    NAME      TYPE  NUM  LABEL                      FORMAT   SIZE     MOUNT-MEDIA
    sdb       disk  -    -                          -        3824M    -
      sdb1    part  1    default                    ext3     1912M    external
      sdb2    part  2    my-files                   vfat     764M     -
      sdb3    part  3    -                          ext2     764M     -
      sdb4    part  4    my-label                   ext4     382M     -

We can also get a comprehensive overview of the connected external media device in relation the media definitions specified on the system using the `show` command in the current context:

    example:/media/partition-sdb/#> show
    MEDIA       DEVICE      LABEL          FORMAT   RW     SIZE  USED  DESCRIPTION
    Active
    internal    mtd:Config  -              jffs2    Yes   15.0M    5%  config,cert
    external    sdb1        default        ext3     Yes    1.8G    0%  logging
    Inactive
    Available
    -           sdb2        my-files       vfat     -      764M     -
    -           sdb3        -              ext2     -      764M     -
    -           sdb4        my-label       ext4     -      382M     -

As we can see only the first of our partitions that we created is listed under the `Active` tab. This is because it matches one of the default matching rules for media definitions on the system, the one named external.

Note

The default external media match rule, aptly named `external`, is set to match on the first partition of a device. In case a device have no partitions it will match on that as well (No partition means the first partition, in the context of the match rule).

Further, we can see the other three of our partitions are listed as `Available`. This means that a physical device exist, but they have no matching media definition. Hence, this device is available for matching.

Lastly, we currently have nothing listed under `Inactive`. Any media definition that have been created that finds no matching physical device will be listed here.

The next step in order to make the additional external physical media devices accessible, is to create media definitions that can correctly match them. This is covered in the following section on this page.

### Format a Specific Device or Partition

It is possible to simply format a given device or partition as well, using the `format` command that is also located in the media context. In the example provided below we want to reformat one of our partitions, `sdb2`. It can be done in the following manner:

    example:/media/partition-sdb/#> format sdb2
    example:/media/format-sdb2/#>

After that we select the file system we want to format the device with, along with an optional label:

    example:/media/format-sdb2/#> filesystem vfat
    example:/media/format-sdb2/#> label my-files

Before we start the formatting we can check our intended configuration:

    example:/media/format-sdb2/#> show
    Format settings for device sdb2
    Filesystem : vfat
    Label      : my-files

When we are satisfied with the planned format options, we can initiate the actual formatting:

Note

No changes have actually been made to the device before we use the `start-formatting` command, it is still possible to exit the formatting context without any changes to the device.

Warning

Observe, that once the formatting starts all files on the device will be lost, so ensure that any files that should be saved have been so.

    example:/media/format-sdb2/#> start-formatting

    Warning: Formatting this dev will remove any files currently stored on it!
             Backup any data you want to keep before formatting the dev.

    Do you still want to proceed (y/N)?y

    Formatting: 100% \ [============================================================]

    Format successful!
    example:/media/#>

If everything went well we can use the `show devices` command to verify that the device was formatted with the correct options:

    example:/media/partition-sdb/#> show devices

    Connected Media Devices
    NAME      TYPE  NUM  LABEL                      FORMAT   SIZE     MOUNT-MEDIA
    sdb       disk  -    -                          -        3824M    -
      sdb1    part  1    default                    ext3     1912M    external
      sdb2    part  2    my-files                   vfat     764M     -
      sdb3    part  3    -                          ext2     764M     -
      sdb4    part  4    my-label                   ext4     382M     -

As we can see `sdb2` has been correctly formatted.

## Make Specific Media Accessible on the System

In order for an external media device to become mounted and accessible on the system, a media definition needs to be created. This media definition will specify a name that will be how to refer to a specific media when using it in the system. Furthermore, any media definition also have an associated match rule that will specify how a physical external media device will be linked with said media definition.

Only one match rule can be specified per media definition, and can be set to match on the following parameters:

- `partition`: Used to indicate a match based on a specific partition number on the physical media device. If no partitions exist on the device, that will count as a match for partition 1 (The first).

- `label`: Used to indicate a match based on a specific label possibly present on the physical media device.

### Default Media Definitions

By default the system will be configured with two media definitions. One is mean to represent the built-in flash memory and the other to serve as a general match rule for any potential connected media device. They are defined in the following manner:

Name | Match Rule | Description
--- | --- | ---
internal | System Internal | Special definition and representation of the built-in flash, this media definition CANNOT be changed or removed.
external | Partition: 1 | Base definition aimed to match the first partition located on any connected external physical media. If no partitions exist on the device this will also be a match in that case.

The `internal` media definition exist so that we can refer to the built-in flash in the same manner as we do any external media device.

The `external` media definition serve as the most simple way an external media can be matched and be made available. This definition is, in contrast to the previously mentioned, fully adjustable and even removable.

Note

Removing the `external` media definition in this case would effectively be disabling any connected external media device, since the device or any potential partition will not be mounted and be made available.

### Creating New Media Definitions

In this case we want to create additional media definitions in order to match all of the partitions we created during the example in the earlier section on this page.

In this case we will keep the default `external` media definition and create three additional definitions to match the other partitions. In this case we want to have the following media definitions configured to match the specific partitions.

Name | Match Rule | Intended Physical Device to Match
--- | --- | ---
external | Partition: 1 | sdb1
files | Label: my-files | sdb2
stuff | Partition: 3 | sdb3
things | Label: my-label | sdb4

All the media definitions on the system are created in the boot configuration context. These settings will also be stored in the boot configuration.

Note

These media changes will not become active until the next reboot of the system. Therefore, making changes here without a reboot will not cause the media definitions to be mounted, even though the physical external devices currently exist.

In order to start configuring the new media definitions we need to enter the boot configuration context:

    example:/#> boot
    example:/boot/#>

First we can check so that we do not already have any other media definitions except for the default ones:

    example:/boot/#> show media

    Media Configuration
    #  NAME                       R/O  TIMEOUT  MATCH
    1  internal                   No   -------  System Internal
    2  external                   No   30       Partition number: 1

If the output matches the above we currently only have unchanged default media definitions.

From here we can create our new media definitions in accordance with the table presented above:

    example:/boot/#> media files
    Creating new media definition...
    example:/boot/media-files/#> match label my-files
    example:/boot/media-files/#> end
    example:/boot/#>

    example:/boot/#> media stuff
    Creating new media definition...
    example:/boot/media-stuff/#> match partition 3
    example:/boot/media-stuff/#> end
    example:/boot/#>

    example:/boot/#> media things
    Creating new media definition...
    example:/boot/media-things/#> match label my-label
    example:/boot/media-things/#> end
    example:/boot/#>

Now with our new media definitions they should appear like this:

    example:/boot/#> show media

    Media Configuration
    #  NAME                       R/O  TIMEOUT  MATCH
    1  internal                   No   -------  System Internal
    2  external                   No   30       Partition number: 1
    3  files                      No   30       Label: my-files
    4  stuff                      No   30       Partition number: 3
    5  things                     No   30       Label: my-label

Now we exit the boot context so that we write our new settings into the boot configuration:

    example:/boot/#> end
    Saving bootloader configuration to FLASH
    100% / [====================================================================]
    example:/#>

In order for these new media definitions to have any effect and become active, we need to reboot the device:

    example:/#> reboot
    [...]

    Please press Enter to activate this console.

    example login: admin
    Password:

    example:/#>

Now after we have rebooted the device our media definitions should be active, if they indeed properly matched against any connected external media device and its partitions. We can check this with the show media command, from the top level context (not in the boot context, that is only the configuration):

    example:/#> show media
    MEDIA       DEVICE      LABEL          FORMAT   RW     SIZE  USED  DESCRIPTION
    Active
    internal    mtd:Config  -              jffs2    Yes   15.0M    5%  config,cert
    external    sdb1        default        ext3     Yes    1.8G    0%  logging
    files       sdb2        my-files       vfat     Yes  763.3M    0%
    stuff       sdb3        -              ext2     Yes  752.0M    0%
    things      sdb4        my-label       ext4     Yes  348.3M    0%
    Inactive
    Available

Now we can see that all combinations of media definitions and actual physical external media devices are all listed under `Active`. As mentioned earlier, this means that they fully match correctly and are now mounted and accessible in the system.

We can for instance access the media devices in the system’s VFS using the `media://MEDIA-NAME/FILE` format. For example we can use the `ls` command to list everything on the media:

    example:/#> ls media://files/
    /media/files/         MOD. DATE/LINK    SIZE  MD5
    bar                   2021-09-14 15:40     0
    foo                   2021-09-14 15:40     0
    hello-world.txt       2021-09-14 15:40     0

    Free: 763.3 MiB | Total: 763.3 MiB

For advanced users, these medias can also be accessed directly from the linux shell:

    example:/#> shell
    Domain shell started.
    admin@example:~ # ls /media/
    external  files     internal  stuff     things
    admin@example:~ #

« Previous Next »