Earth Resources

Quick Start: Connect a Device and View Data

This guide walks through one complete first-use flow: create a connection credential, send the first message, view it live in the console, and test data analysis. You do not need to understand the platform internals first.

For protocol-by-protocol tests of HTTP, MQTT TLS, MQTT over WebSocket, EarthMQTT WebSocket, and WebTransport—or for details about space, group, scope, and $earth/… topics—continue with the Resource and Protocol Integration Guide.

1. Create a workspace

After signing in, choose a workspace (tenant ID). The workspace is your data boundary: devices, messages, credentials, and analysis results belong to it.

If you do not have a device yet, use a test resource for this walkthrough. A resource ID can be demo-sensor or line-a-01.

2. Create a device connection credential

Open Credentials → Device or resource credentials, then expand Add a device or resource:

  1. Enter the device ID and name. Add latitude and longitude if the device should appear at a specific position on the globe.
  2. Select Create and generate device key.
  3. Copy the one-time device key (erk_…) and store it in secure device or test-script configuration.

A resource key represents one resource. If an application needs to send or receive data for an entire workspace, create an application credential (etk_…) under Credentials → Application credentials and grant only the capabilities it needs.

An application key is already bound to its workspace. For the default MQTT space, do not repeat the workspace ID. MQTT requires the Username Flag whenever a password is present, so configure an empty username string ("") in general-purpose clients. For a named space, use only the location suffix, such as @production. Omit Client ID to let the client library or broker generate one; configure a stable unique Client ID only when a persistent session and offline QoS state are required.

3. Send the first message

HTTP is the simplest test. Replace the platform host, workspace ID, resource ID, and resource key below:

curl -X POST 'https://<PLATFORM_HOST>/v1/telemetry' \
  -H 'Authorization: Bearer erk_YOUR_RESOURCE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"eventId":"demo-001","data":{"temperature":23.6,"humidity":48,"online":true}}'

eventId prevents network retries from creating duplicate events. After the request succeeds, the message becomes part of the device stream and its analysis data.

New resource keys carry tenant and resource identity, so HTTP no longer needs identity headers. MQTT username must be your own tenant ID (for example p2); there is no shared username, and the resource ID is no longer repeated. Client ID may be omitted; use earthmqtt-common-clientid when a client requires one. The server identifies the resource from its key and keeps one MQTT connection per resource credential. After creating a device, the console generates copyable examples using the current deployment endpoints.

4. View data in the console

  • Data & Trends → All Data groups history by type and updates each collapsed group while monitoring is enabled.
  • Data & Trends → Live Monitor shows newly arrived messages in every space the account may access. Monitoring can be paused and resumed.
  • Devices & Resources → View → Trends charts numeric fields for the selected device. You can select the latest 100, 500, 1,000, or 5,000 samples.
  • Globe shows a device position and live state when its metadata includes latitude and longitude.

Live monitoring includes all spaces in your workspace and shared-project spaces the account may access. Data from unauthorized workspaces is never shown.

5. Test AI data analysis

Open AI Analysis, locate the stream you just sent, and refresh. The platform assigns a usage label based on the stream structure, such as telemetry, location, state, or another category.

AI labels only help organize data. They do not change permissions, delete messages, or block ingestion. You can edit a label manually. If AI analysis is disabled on the deployment, manual labels remain available.

Start with stable JSON such as:

{"temperature":23.6,"humidity":48,"online":true}

A stable stream structure normally needs analysis only once, so keep field names and types consistent during testing.

6. Connect an existing external MQTT broker

If devices already connect to your own MQTT broker, you do not need to repoint them. Open Connect → External Broker and create a connection:

  1. Enter the broker URL, username, and password.
  2. Enter subscribed topics, such as plant/+/state.
  3. Choose whether the resource ID comes from the topic or a payload field.
  4. Save and connect.

Topic extraction example:

Topic:  plant/boiler-7/state
Rule:   plant/{resourceId}/state
Result: resourceId = boiler-7

Payload extraction example:

{"meta":{"deviceId":"boiler-7"},"temperature":71.2}

Use meta.deviceId as the field path. The platform writes broker messages into the workspace, where they are available to Live Monitor, Trend Analysis, and AI Analysis like directly connected data.

7. Troubleshooting

  • No live message: verify the resource key, workspace ID, resource ID, and protocol parameters, then select Start in Live Monitor.
  • Device appears offline: send a message containing "online": true. Sending "online": false marks it offline.
  • No chart data: charts use numeric fields only. Confirm that the payload contains JSON numbers rather than numeric strings.
  • Lost key: keys are never displayed again. Rotate the resource key, or revoke and recreate an application credential, then update the device or application configuration.