Turn your hardware into a customer SaaS product

This guide is for a hardware company building a service around a connected Linux device. You begin with one working unit. You finish with:

• a repeatable product definition
• a secure connection from every device
• a customer-facing page with live product data
• a branded portal for each customer's users and sites
• a support and release process your team can operate after shipment

Your engineering team works in Dataplicity. Your customers use your branded portal at the permanent hosted https://your-vendor.dvcmgr.com address created for your organisation. The current OEM UI does not provide self-service custom portal hostnames. Customers do not enter your engineering workspace.

The product you will build in this guide

Use this example to keep the roles of each part clear:

You manufacture a refrigerated-storage monitor. A customer buys monitors for two warehouses. Their operations team signs in to your portal, sees which monitors are online, opens the Bristol warehouse, and checks the temperature reported by each unit. Your support team uses the separate engineering workspace to diagnose faults and release device software.

In Dataplicity, that becomes:

Your real-world thing	Dataplicity model	Example
Your company	Vendor organisation	Northstar
A model of hardware you sell	Device Class	Cold Room Monitor
One manufactured unit	Device	Monitor CRM-0042
A value produced by the unit	Class stream	temperature_c
The page your customer opens	Class UI	Temperature, connection state, identity
A company that bought your product	Portal customer	Polar Freight
One customer location or deployment	Network	Bristol Distribution Centre
A person at the customer	Portal user	Bristol site operator

The finished customer experience: product inventory is separated by customer and site, while engineering controls remain in your Dataplicity workspace.

Understand what Dataplicity supplies

Dataplicity supplies the connected-product operating layer:

• device identity and outbound connection
• product classes and compatible software releases
• delivery of product values from the device
• customer and site separation
• a branded customer portal
• engineering tools for fleet operations and remote support

You still own the commercial product around it: hardware, pricing, contracts, payment collection, warranty terms, customer onboarding policy, and first-line support. The portal is the application your customer uses after they buy. It is not a storefront or a substitute for your billing system.

Confirm that your organisation has the required product access

Do this before integrating hardware. The workflow crosses several separately controlled parts of Dataplicity.

Plan tier alone is insufficient: the suite remains beta-gated, and the organisation must use the required release channel or be enrolled in the beta programme.

Subject to that requirement, the current package is:

• Free: connect and evaluate a device; no Customer Portal suite.
• Standard: the full basic suite for exactly one Customer Portal and one downstream customer organisation.
• Business+: unlimited portals and customer organisations.

Ask an Organisation Administrator to open Settings, then Configuration, and confirm:

• your subscription includes the customer and engineering capabilities you intend to use
• your organisation is enrolled in the Beta program where the required capability is still gated
• you can open Customer journey > Customer Portal
• you can open Customer journey > Customers
• you can create a Device Class under Engineering > Device classes
• the class exposes UI Components and UI Designer
• Software is available if Dataplicity will manage your device application

The current suite checks whitelabel, customers, device_class_ui, microservices, and firmware independently. Different capabilities can have different plan, beta, feature, and role gates. Seeing Device Classes does not prove that Customer Portal, Customers, class UI, class containers, or firmware sets are enabled. Device Class Inventory is separately beta-gated on Business+; claim bundles are separately gated to Enterprise.

If one of these surfaces is absent, resolve access with your Organisation Administrator before continuing. Do not design a delivery process around a control that your production organisation cannot use.

Before you configure anything

Write down these decisions for one product and one customer:

1. Product: which hardware model are you selling?
2. Customer job: what should a customer be able to learn or do?
3. Product data: which readings or states are required for that job?
4. Deployment unit: does a network represent a site, vehicle, cabinet, or another customer boundary?
5. Support boundary: what can the customer do, and what remains restricted to your engineering team?

For the cold-room monitor, the first version might promise only:

• see all monitors at each warehouse
• know whether each monitor is connected
• read the current temperature
• identify the physical unit when calling support

That is enough for a first sellable service. Add alerts, charts, remote actions, and automation only after the basic path works end to end.

Learn the complete path without waiting for hardware integration

If your device application or sensor driver is not ready, use an example simulator first. It exercises the same class Software, UI Components, firmware, stream, and UI Designer path with generated values.

Use the simulator to learn Dataplicity. Replace the generated value with your hardware adapter only after you can follow one value from the device to the customer page.

The build path

Complete these milestones in order:

Milestone	You have succeeded when
1. Connect one unit	Representative hardware appears online in Dataplicity
2. Define the product	The unit belongs to the correct Device Class
3. Publish one value	A real reading reaches its class stream
4. Build the product page	A non-engineer can understand the unit's state
5. Create the customer boundary	A customer, network, and portal user exist
6. Hand over one unit	The customer can open only their assigned device
7. Make it repeatable	Manufacturing, release, support, and offboarding are tested

Do not begin with a fleet. Prove every milestone with one staging device, one test customer, and one customer-scoped user.

1. Connect one representative device

Use the same hardware architecture and operating-system image that you intend to ship.

1. Sign in to your Dataplicity engineering workspace.
2. Open Engineering > Devices, choose Add a new device, and copy the supplied install command.
3. Run it on the staging device.
4. Confirm the device appears in inventory and becomes online.
5. Reboot the device and confirm it reconnects without manual intervention.

At this point you have secure device connectivity and engineering access. You do not yet have a customer product.

If the device cannot connect, stop here and use the first-device guide and firewall requirements.

2. Define the hardware product

A Device Class is the model of hardware you sell. It is not a customer, site, or temporary group.

Create one class for the cold-room monitor and record:

• a customer-readable product name
• supported CPU architectures
• whether you manage the complete appliance or install beside a customer's OS
• the hardware profile and capabilities
• the software and page configuration shared by every unit of this model

Assign the staging device to this class. Do not use one class for unrelated models simply because they report similar data. The class becomes a durable product contract used by provisioning, software, streams, page layouts, and potentially licensing.

A Device Class represents a model you ship, not a customer's site or a temporary fleet filter.

3. Decide how your device application runs

Dataplicity does not require you to rewrite the application already controlling your hardware. Choose one path:

Starting point	What to do
Existing systemd service, Docker workload, Greengrass component, balena service, or supervisor	Keep it and add a small publisher that sends selected product values to the local Dataplicity broker
No suitable application runtime yet	Start from a Dataplicity example container, replace the simulated input with your hardware adapter, and let class software install and version it
Connectivity and inventory are enough for version one	Skip product streams and class software; the portal can still show identity, assignment, and connection state

The customer portal does not require a Dataplicity-managed container. Class software is useful when Dataplicity should install and release an OCI image across this product line.

If you choose class software:

1. Open the Device Class Software tab.
2. Choose Add container.
3. Start with Use an example, or upload your own image version.
4. Test the image on the staging device.
5. Release a pinned version through the class firmware workflow.

See Build a class container for the image contract, architectures, environment, and release process. Use an example simulator if real sensor integration is not ready. Keep the class container, Dataplicity firmware set, agent, OS, and device firmware boundaries explicit in the release plan.

Class Software is an optional deployment mechanism for your device application. It is not the customer portal itself.

4. Turn a hardware reading into product data

A customer page cannot consume an arbitrary process variable. Give each customer-facing value a stable product contract.

For the cold-room monitor:

Meaning	Stream ID	Type	Unit
Current air temperature	temperature_c	Number	°C
Door state	door_open	Boolean	n/a
Temperature outside the configured range	temperature_alarm	Boolean	n/a

On the Device Class UI Components tab:

1. choose Add stream
2. enter the stable ID
3. give it a customer-readable Name
4. select its Data type and Unit
5. enable history only where the customer experience needs it

Your on-device application posts readings to the agent's loopback broker. The agent authenticates and delivers them to Dataplicity:

hardware sensor
  -> your device application
  -> local agent broker (`temperature_c = 4.2`)
  -> Dataplicity
  -> customer device page

The application does not need a Dataplicity cloud API key. Keep stream IDs stable after shipment; they are the API between your device software and the customer page.

Follow Device class streams to publish and verify the first sample. Before production, implement and test the complete device data and control contract, including version qualification, rate handling, restart, offline, stale, and duplicate behaviour.

UI Components separates values a device publishes from one-off actions and lasting settings. The screenshot shows the current section structure while its records are loading.

5. Build the page your customer is buying

Do not start by adding every available widget. Start with the customer's job. For a cold-room operator, the page should answer:

1. Which physical monitor is this?
2. Is it connected now?
3. What temperature is it reporting?
4. Is the reading normal or actionable?
5. Which warehouse contains it?

Open the Device Class UI Designer and:

1. add identity and connectivity context
2. add a metric widget for temperature_c
3. add explicit state for temperature_alarm rather than asking the customer to interpret a raw number
4. arrange the page in the order the customer diagnoses a problem
5. preview current, missing, stale, and offline states
6. save the class layout

Keep Remote Shell, fleet-wide logs, firmware rollout, and engineering diagnostics out of this page. Those remain in your engineering workspace.

The class layout is the product page shared by every unit of this hardware model.

See Design a device class page for widget and state design.

6. Create the branded customer service

Open Customer journey > Customer Portal. Create the portal before you create customer accounts:

1. Choose the hosted Subdomain carefully. It is the permanent tenant address and cannot be renamed later.
2. Enter the customer-facing Portal title.
3. Turn on Enable customer portal.
4. Use Edit branding to configure logos and colours.
5. Configure the sign-in, portal, and support copy.
6. Use Open live preview before inviting anyone.

Then open Customer journey > Customers and model the buyer:

1. Choose Add customer.
2. Enter the Organization name and the first Org admin email.
3. Grant access to the intended Customer Portal.
4. In the customer portal, create a Network for each site or deployment boundary they should operate.
5. Invite operator and read-only test users as needed.
6. Assign the smallest role and network scope that supports each person's job.

Create downstream customer organisations in the OEM workspace before allocating their devices.

For the example:

• portal customer: Polar Freight
• networks: Bristol Distribution Centre and Leeds Cold Store
• user: a Polar Freight operator, not a member of your OEM engineering team

Customer separation is part of the product. A network groups a customer's devices. A Device Class describes the model of hardware. Do not use classes as customer boundaries or grant customers OEM roles.

In the current portal, network assignment is the technical placement step that makes a claimed device active. The name need not describe a literal computer network: model the customer-facing concept as a warehouse, farm, vehicle, cabinet, or other operating location, and explain that meaning consistently in your onboarding.

The customer signs in to your product experience, not to the Dataplicity engineering workspace.

Read Customer portal for the portal navigation, role boundary, and operator pages.

7. Onboard the first customer device

Use one staging unit to rehearse the exact handoff you will perform after a sale:

1. Confirm the device has the intended identity and Device Class in your engineering workspace.
2. For a staff-managed first delivery, open Engineering > Devices and choose Allocate to customer.
3. For a customer self-service shipment, create a claim bundle and securely provide its code and auth key. Claim bundles have separate feature, plan, and permission requirements.
4. As the customer Org owner or Admin, assign the device to the correct Network in the portal.
5. Sign out of the engineering workspace.
6. Sign in through the branded portal as the customer-scoped test user.
7. Open Inventory and confirm the device appears.
8. Open the customer network and confirm its online count.
9. Open the device and confirm identity, connectivity, class widgets, units, and stale states.
10. Confirm no other customer, network, device, or engineering control is visible.

A claimed device that has not been assigned to a network is unassigned, not broken. Make network assignment an explicit step in your fulfilment process.

Allocation also changes the support boundary. If your engineers must continue opening customer-allocated devices, an Organisation Administrator must review Settings > Configuration > Allocated device access. Enable it only when your support agreement and access policy require that capability.

8. Turn the prototype into a repeatable service

One working portal device proves the design, not the business process.

Manufacturing and commissioning

• install the agent through a controlled image or first-boot process
• give every physical unit its own Dataplicity identity
• assign the correct Device Class automatically or through a checked procedure
• retain a manufacturing asset ID that links the physical label to the device record
• protect provisioning material from public images, logs, and source control

Software release

• test application and class-software changes on staging hardware
• verify the target architecture
• pin released versions
• roll out to a bounded cohort before the whole fleet
• preserve compatibility when changing stream IDs or page layouts

Customer fulfilment

• create the customer and networks from the signed order or authoritative CRM record
• assign serialised devices to the correct customer
• invite named users rather than sharing accounts
• provide portal, support, warranty, and escalation information
• rehearse replacement, reassignment, return, and decommissioning

Operations and support

• monitor device connectivity and the product signals that affect customers
• collect the logs your support team needs before the first incident
• define who handles a customer report and who may use engineering access
• test recovery after network loss, reboot, and stopped application publishing
• keep customer communication separate from engineering-only evidence

Use Installing for mass production and Production rollout to build this operating process.

Launch gate for a sellable first version

Do not onboard a real customer until all of these are true:

Product

• [ ] A representative unit reconnects after power and network loss.
• [ ] Every unit resolves to the intended Device Class.
• [ ] The device application resumes publishing after interruption.
• [ ] The publisher contains no Dataplicity API key.
• [ ] Customer values use stable IDs, correct units, and understandable states.
• [ ] The released software matches the device architecture.

Customer experience

• [ ] Branding, domain, sign-in, and support links are correct.
• [ ] A new device can be assigned to the right customer and network.
• [ ] The customer page distinguishes offline, missing, stale, and abnormal.
• [ ] A customer user sees only their own customer, networks, and devices.
• [ ] Viewer and operator roles expose only their intended actions.
• [ ] No engineering-only control appears in the portal.

Business operations

• [ ] Sales or fulfilment provides an authoritative customer and site record.
• [ ] Manufacturing records the physical asset-to-device identity.
• [ ] Support can find a unit from the information printed on it.
• [ ] Your team has tested software rollout, replacement, reassignment, and decommissioning.
• [ ] Pricing, invoicing, warranty, support, and data responsibilities are documented outside the portal.

Related

• Connect your first device
• Connected-product company workflow
• Device classes
• Build a class container
• Software and firmware boundaries
• Device data and control contract
• Device class streams
• Design a device class page
• Example simulators
• Choose a customer surface
• Complete camera and CCTV walkthrough
• Complete level-monitor walkthrough
• Complete numeric-telemetry walkthrough
• Expand devices already online beyond remote access
• Customer portal
• Teams and roles
• Provision and claim
• Installing for mass production
• Production rollout
• Customer lifecycle and automation
• Production limits and service behaviour
• Ship the first customer unit you can still support
• Hand support to a real queue
• Keep your runtime