Skip to main content
Version: 1.0

Storage

The Storage component manages the device's local media storage. It supports an SD card or a remote NFS network share, and exposes methods for listing recorded media, deleting files and managing the underlying filesystem.

Methods​

Storage.List​

Lists recorded media files stored on the device with pagination support.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the storage component

offset

number

Number of items to skip (for pagination)

Response​

Attributes in the result:

PropertyTypeDescription

total

number

Total number of media files available.

offset

number

The offset that was used to produce this page (echoed from the request).

rev

number

Storage revision counter. Incremented every time the contents of the storage change (new media added, media deleted, cleanup, etc.). Clients can use it to detect changes between calls.

items

array of objects

List of media items.

PropertyTypeDescription

media_id

string

Unique identifier (UUID) of the media file.

type

string

Type of media. See accepted values.

ts

number

Unix timestamp at which the media was created.

duration

number

Optional. Duration in seconds. Present only for video items with a known duration.

size

number

Optional. File size in bytes. Present when known.

url

string

Pre-signed URL pointing to the media file on the device. The embedded signature authorizes access; no additional HTTP authentication is required.

thumbnail_url

string

Optional. Pre-signed URL pointing to the thumbnail image. Present for video items with an associated thumbnail. The embedded signature authorizes access; no additional HTTP authentication is required.

trigger

object

Optional. The event that triggered the recording. Present only when the recording was created in response to an event (e.g. motion detection); absent for manually started recordings or for still images. Carries the source component (component, id), the event name (always "motion_detected") and the timestamp (ts).

Accepted values for `type`:
ValueDescription

"image"

Still image (JPEG).

"video"

Video file (MP4).

Storage.Delete​

Deletes a specific media file from the storage. Both the media file and its associated thumbnail (if any) are removed.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the storage component

media_id

string

Unique identifier of the media file to delete.

Response​

The result from this method is null.

Storage.GetStatus​

Obtain the current status of the storage.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the storage component

See the status section for the response shape.

Storage.GetConfig​

Obtain the storage configuration.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the storage component

See the configuration section for the response shape.

Storage.SetConfig​

Update the storage configuration. Only the fields included in the request are modified; omitted fields are left unchanged. Setting a field to null resets it to the device default.

If the new configuration changes the active mount, the storage is unmounted and re-mounted automatically; intermediate states are reflected in Storage.GetStatus.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the storage component

config

object

Configuration to apply (see the configuration section).

Response​

PropertyTypeDescription

restart_required

boolean

true if a device restart is required for the new configuration to take effect.

Storage.Format​

Erases and reformats the SD card to the expected filesystem. The operation is asynchronous: the call returns once formatting has been started, and progress is reflected in Storage.GetStatus (with errors containing "formatting" while in progress).

This method applies to SD card storage only and requires an SD card to be physically present. It has no effect on network-mounted (NFS) storage.

danger

This operation will permanently delete all data on the SD card.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the storage component

Response​

The result from this method is null.

Storage.Eject​

Unmounts the SD card to allow safe physical removal while the camera is running. Auto-mounting is disabled until the SD card is removed and re-inserted.

For network-mounted (NFS) storage this method is a no-op and returns successfully without unmounting.

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the storage component

Response​

The result from this method is null.

Configuration​

The Storage configuration controls the optional NFS network mount target. SD card parameters (device node, mount point, filesystem type) are device-specific and not user-configurable.

When both nfs.host and nfs.path are set, the device mounts the remote NFS share. When NFS is not configured, the local SD card (if present) is used instead.

Properties:

PropertyTypeDescription

id

number

Id of the storage component

name

string

Name of the storage.

nfs

object

NFS settings. Set to null to clear all NFS fields and disable NFS.

PropertyTypeDescription

host

string

Hostname or IP address of the NFS server. Set to null (or omit) to disable NFS.

path

string

Exported path on the NFS server. Set to null (or omit) to disable NFS.

NFS server requirements​

The camera firmware runs as UID 1000 / GID 1000, and the NFS client mounts the share as that user. Unlike the SD-card mount, ownership is not overridden on NFS — the server's filesystem permissions apply directly. Make sure the camera can create directories and files under the exported path:

  • Either make the entire exported path writable by UID 1000 / GID 1000, or
  • Pre-create a DCIM/ directory inside the export and make that directory writable by UID 1000 / GID 1000.

Each camera stores its media under DCIM/<hostname>/, where <hostname> is the device's hostname (e.g. shellycamera-068df8bc340f). This sub-directory is created automatically once the parent DCIM/ is writable, so multiple cameras can safely share a single NFS export.

Typical export configuration on the NFS server (Linux /etc/exports):

/export/shelly  192.168.1.0/24(rw,sync,no_subtree_check,all_squash,anonuid=1000,anongid=1000)

The all_squash + anonuid=1000/anongid=1000 options map every incoming request to UID/GID 1000 on the server, ensuring the camera always has the correct identity regardless of the local user numbering on the server. Alternatively, omit all_squash and simply chown 1000:1000 (or chmod appropriately) on the export root or its DCIM/ sub-directory.

Status​

The status of the Storage component reports the physical state of the storage medium, the available and total capacity, the current revision counter and any active error condition.

Properties:

PropertyTypeDescription

id

number

Id of the storage component.

rev

number

Storage revision counter. Incremented every time the contents of the storage change.

present

boolean

true if the underlying storage medium is detected. For SD card: the physical disk is present. For NFS: the network share is successfully mounted.

active

boolean

true if the filesystem is mounted and ready for reading and writing.

fs_free

number

Available free space on the storage in bytes. 0 when the storage is not active.

fs_size

number

Total size of the storage in bytes. 0 when the storage is not active.

errors

array of strings

Optional. List of currently active error/transient conditions. Absent when there are none. See accepted values.

Accepted values in `errors` (a single value at any time):
ValueDescription

"needs_formatting"

An SD card is present but its filesystem could not be mounted; the card likely needs to be formatted (see Storage.Format).

"mounting"

The SD card is currently being mounted.

"mount_failed"

Mounting the NFS share failed.

"mounting_nfs"

The NFS share is currently being mounted.

"unmounting_nfs"

The NFS share is currently being unmounted (e.g. after a network disconnection).

"unmount_failed"

Unmounting the storage failed.

"resolving_nfs_host"

DNS resolution of the NFS host is in progress.

"filesystem_error"

The storage was mounted successfully but the media database could not be initialized (e.g. directory creation or database open failed).

"formatting"

The SD card is currently being formatted.

"format_failed"

The most recent format operation failed.

"ejected"

The SD card has been ejected via Storage.Eject and will not be auto-mounted again until it is removed and re-inserted.

"eject_failed"

Ejecting the SD card via Storage.Eject failed.

Examples​

Storage.List example​

http://192.168.33.1/rpc/Storage.List?id=0&offset=0

Response

{
  "offset": 0,
  "total": 1,
  "rev": 42,
  "items": [
    {
      "media_id": "019abff8-3bfa-7475-af43-89b0a792d705",
      "type": "video",
      "ts": 1722887000.123,
      "duration": 30,
      "size": 20800000,
      "url": "/storage/019abff8-3bfa-7475-af43-89b0a792d705/<sig>/MOV_20240805_140320.mp4",
      "thumbnail_url": "/storage/019abff8-3bfa-7475-af43-89b0a792d705/<sig>/IMG_20240805_140320.jpg",
      "trigger": {
        "component": "camerazone:200",
        "event": "motion_detected",
        "ts": 1722887000
      }
    }
  ]
}

Storage.Delete example​

http://192.168.33.1/rpc/Storage.Delete?id=0&media_id="019abff8-3bfa-7475-af43-89b0a792d705"

Response

null

Storage.GetStatus example​

http://192.168.33.1/rpc/Storage.GetStatus?id=0

Response

{
  "id": 0,
  "rev": 42,
  "present": true,
  "active": false,
  "fs_free": 0,
  "fs_size": 0,
  "errors": [
    "needs_formatting"
  ]
}

Storage.GetConfig example​

http://192.168.33.1/rpc/Storage.GetConfig?id=0

Response

{
  "id": 0,
  "name": "SD card",
  "nfs": {
    "host": "nas.local",
    "path": "/export/shelly"
  }
}

Storage.SetConfig example​

http://192.168.33.1/rpc/Storage.SetConfig?id=0&config={"nfs":{"host":"nas.local","path":"/export/shelly"}}

Response

{
  "restart_required": false
}

Storage.Format example​

http://192.168.33.1/rpc/Storage.Format?id=0

Response

null

Storage.Eject example​

http://192.168.33.1/rpc/Storage.Eject?id=0

Response

null