iot.md

Documentation for scw iot

This API allows you to manage your IoT hubs and devices.

IoT Device commands

IoT Device commands.

Add a device

Attach a device to a given Hub.

Usage:

scw iot device create [arg=value ...]

Arguments:

Name	Description	Argument Specifications
name	Device name	Required Default: <generated>
hub-id	Hub ID of the device	Required
allow-insecure	Defines whether to allow plain and server-authenticated SSL connections in addition to mutually-authenticated ones
allow-multiple-connections	Defines whether to allow multiple physical devices to connect with this device's credentials
message-filters.publish.policy	How to use the topic list	One of: unknown, accept, reject
message-filters.publish.topics.{index}	List of topics to accept or reject. It must be valid MQTT topics and up to 65535 characters
message-filters.subscribe.policy	How to use the topic list	One of: unknown, accept, reject
message-filters.subscribe.topics.{index}	List of topics to accept or reject. It must be valid MQTT topics and up to 65535 characters
description	Device description
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Remove a device

Remove a specific device from the specific Hub it is attached to.

Usage:

scw iot device delete <device-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
device-id	Device ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Disable a device

Disable an existing device, specified by its device ID.

Usage:

scw iot device disable <device-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
device-id	Device ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Enable a device

Enable a specific device, specified by its device ID.

Usage:

scw iot device enable <device-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
device-id	Device ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Get a device

Retrieve information about an existing device, specified by its device ID. Its full details, including name, status and ID, are returned in the response object.

Usage:

scw iot device get <device-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
device-id	Device ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Get a device's certificate

Get information for a particular PEM-encoded certificate, specified by the device ID. The response returns full details of the device, including its type of certificate.

Usage:

scw iot device get-certificate <device-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
device-id	Device ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Get a device's metrics

Get the metrics of an existing device, specified by its device ID.

Usage:

scw iot device get-metrics <device-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
device-id	Device ID	Required
start-date	Start date used to compute the best scale for the returned metrics	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

List devices

List all devices in the specified region. By default, returned devices are ordered by creation date in ascending order, though this can be modified via the order_by field.

Usage:

scw iot device list [arg=value ...]

Arguments:

Name	Description	Argument Specifications
order-by	Ordering of requested devices	One of: name_asc, name_desc, status_asc, status_desc, hub_id_asc, hub_id_desc, created_at_asc, created_at_desc, updated_at_asc, updated_at_desc, allow_insecure_asc, allow_insecure_desc
name	Name to filter for, only devices with this name will be returned
hub-id	Hub ID to filter for, only devices attached to this Hub will be returned
allow-insecure	Defines whether to filter the allow_insecure flag
status	Device status (enabled, disabled, etc.)	One of: unknown, error, enabled, disabled
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, all

Renew a device certificate

Renew the certificate of an existing device, specified by its device ID.

Usage:

scw iot device renew-certificate <device-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
device-id	Device ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Set a custom certificate on a device

Switch the existing certificate of a given device with an EM-encoded custom certificate.

Usage:

scw iot device set-certificate <device-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
device-id	Device ID	Required
certificate-pem	PEM-encoded custom certificate	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Update a device

Update the parameters of an existing device, specified by its device ID.

Usage:

scw iot device update <device-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
device-id	Device ID	Required
description	Description for the device
allow-insecure	Defines whether to allow plain and server-authenticated SSL connections in addition to mutually-authenticated ones
allow-multiple-connections	Defines whether to allow multiple physical devices to connect with this device's credentials
message-filters.publish.policy	How to use the topic list	One of: unknown, accept, reject
message-filters.publish.topics.{index}	List of topics to accept or reject. It must be valid MQTT topics and up to 65535 characters
message-filters.subscribe.policy	How to use the topic list	One of: unknown, accept, reject
message-filters.subscribe.topics.{index}	List of topics to accept or reject. It must be valid MQTT topics and up to 65535 characters
hub-id	Change Hub for this device, additional fees may apply, see IoT Hub pricing
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

IoT Hub commands

IoT Hub commands.

Create a hub

Create a new Hub in the targeted region, specifying its configuration including name and product plan.

Usage:

scw iot hub create [arg=value ...]

Arguments:

Name	Description	Argument Specifications
name	Hub name (up to 255 characters)	Required Default: <generated>
project-id	Project ID to use. If none is passed the default project ID will be used
product-plan	Hub product plan	Required Default: plan_shared One of: plan_unknown, plan_shared, plan_dedicated, plan_ha
disable-events	Disable Hub events
events-topic-prefix	Topic prefix (default '$SCW/events') of Hub events
twins-graphite-config.push-uri
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Delete a hub

Delete an existing IoT Hub, specified by its Hub ID. Deleting a Hub is permanent, and cannot be undone.

Usage:

scw iot hub delete <hub-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
hub-id	Hub ID	Required
delete-devices	Defines whether to force the deletion of devices added to this Hub or reject the operation
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Disable a hub

Disable an existing IoT Hub, specified by its Hub ID.

Usage:

scw iot hub disable <hub-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
hub-id	Hub ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Enable a hub

Enable an existing IoT Hub, specified by its Hub ID.

Usage:

scw iot hub enable <hub-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
hub-id	Hub ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Get a hub

Retrieve information about an existing IoT Hub, specified by its Hub ID. Its full details, including name, status and endpoint, are returned in the response object.

Usage:

scw iot hub get <hub-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
hub-id	Hub ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Get the certificate authority of a hub

Get information for a particular PEM-encoded certificate, specified by the Hub ID.

Usage:

scw iot hub get-ca [arg=value ...]

Arguments:

Name	Description	Argument Specifications
hub-id		Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

List hubs

List all Hubs in the specified zone. By default, returned Hubs are ordered by creation date in ascending order, though this can be modified via the order_by field.

Usage:

scw iot hub list [arg=value ...]

Arguments:

Name	Description	Argument Specifications
order-by	Sort order of Hubs in the response	One of: name_asc, name_desc, status_asc, status_desc, product_plan_asc, product_plan_desc, created_at_asc, created_at_desc, updated_at_asc, updated_at_desc
project-id	Only list Hubs of this Project ID
name	Hub name
organization-id	Only list Hubs of this Organization ID
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, all

Set the certificate authority of a hub

Set a particular PEM-encoded certificate, specified by the Hub ID.

Usage:

scw iot hub set-ca <hub-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
hub-id	Hub ID	Required
ca-cert-pem	CA's PEM-encoded certificate	Required
challenge-cert-pem	Proof of possession of PEM-encoded certificate	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Update a hub

Update the parameters of an existing IoT Hub, specified by its Hub ID.

Usage:

scw iot hub update <hub-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
hub-id	ID of the Hub you want to update	Required
name	Hub name (up to 255 characters)
product-plan	Hub product plan	One of: plan_unknown, plan_shared, plan_dedicated, plan_ha
disable-events	Disable Hub events
events-topic-prefix	Topic prefix of Hub events
enable-device-auto-provisioning	Enable device auto provisioning
twins-graphite-config.push-uri
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

IoT Network commands

IoT Network commands.

Create a new network

Create a new network for an existing hub. Beside the default network, you can add networks for different data providers. Possible network types are Sigfox and REST.

Usage:

scw iot network create [arg=value ...]

Arguments:

Name	Description	Argument Specifications
name	Network name	Required Default: <generated>
type	Type of network to connect with	Required One of: unknown, sigfox, rest
hub-id	Hub ID to connect the Network to	Required
topic-prefix	Topic prefix for the Network	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Delete a Network

Delete an existing network, specified by its network ID. Deleting a network is permanent, and cannot be undone.

Usage:

scw iot network delete <network-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
network-id	Network ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Retrieve a specific network

Retrieve an existing network, specified by its network ID. The response returns full details of the network, including its type, the topic prefix and its endpoint.

Usage:

scw iot network get <network-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
network-id	Network ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

List the networks

List the networks.

Usage:

scw iot network list [arg=value ...]

Arguments:

Name	Description	Argument Specifications
order-by	Ordering of requested routes	One of: name_asc, name_desc, type_asc, type_desc, created_at_asc, created_at_desc
name	Network name to filter for
hub-id	Hub ID to filter for
topic-prefix	Topic prefix to filter for
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, all

IoT Route commands

IoT Route commands.

Create a route

Multiple kinds of routes can be created, such as:

• Database Route Create a route that will record subscribed MQTT messages into your database. You need to manage the database by yourself.
• REST Route. Create a route that will call a REST API on received subscribed MQTT messages.
• Amazon S3 Routes. Create a route that will put subscribed MQTT messages into an Object Storage bucket. You need to create the bucket yourself and grant write access. Granting can be done with s3cmd (s3cmd setacl s3://<my-bucket> --acl-grant=write:555c69c3-87d0-4bf8-80f1-99a2f757d031:555c69c3-87d0-4bf8-80f1-99a2f757d031).

Usage:

scw iot route create [arg=value ...]

Arguments:

Name	Description	Argument Specifications
name	Route name	Default: <generated>
hub-id	Hub ID of the route
topic	Topic the route subscribes to. It must be a valid MQTT topic and up to 65535 characters
s3-config.bucket-region
s3-config.bucket-name
s3-config.object-prefix
s3-config.strategy		One of: unknown, per_topic, per_message
db-config.host
db-config.port
db-config.dbname
db-config.username
db-config.password
db-config.query
db-config.engine		One of: unknown, postgresql, mysql
rest-config.verb		One of: unknown, get, post, put, patch, delete
rest-config.uri
rest-config.headers.{key}
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Delete a route

Delete an existing route, specified by its route ID. Deleting a route is permanent, and cannot be undone.

Usage:

scw iot route delete <route-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
route-id	Route ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

Get a route

Get information for a particular route, specified by the route ID. The response returns full details of the route, including its type, the topic it subscribes to and its configuration.

Usage:

scw iot route get <route-id ...> [arg=value ...]

Arguments:

Name	Description	Argument Specifications
route-id	Route ID	Required
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par

List routes

List all routes in the specified region. By default, returned routes are ordered by creation date in ascending order, though this can be modified via the order_by field.

Usage:

scw iot route list [arg=value ...]

Arguments:

Name	Description	Argument Specifications
order-by	Ordering of requested routes	One of: name_asc, name_desc, hub_id_asc, hub_id_desc, type_asc, type_desc, created_at_asc, created_at_desc
hub-id	Hub ID to filter for
name	Route name to filter for
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par, all

Update a route

Update the parameters of an existing route, specified by its route ID.

Usage:

scw iot route update [arg=value ...]

Arguments:

Name	Description	Argument Specifications
route-id	Route id	Required
name	Route name
topic	Topic the route subscribes to. It must be a valid MQTT topic and up to 65535 characters
s3-config.bucket-region
s3-config.bucket-name
s3-config.object-prefix
s3-config.strategy		One of: unknown, per_topic, per_message
db-config.host
db-config.port
db-config.dbname
db-config.username
db-config.password
db-config.query
db-config.engine		One of: unknown, postgresql, mysql
rest-config.verb		One of: unknown, get, post, put, patch, delete
rest-config.uri
rest-config.headers.{key}
region	Region to target. If none is passed will use default region from the config	Default: fr-par One of: fr-par