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:~ #