Edge

ClearBlade Edge is an application for synchronizing, configuring, managing, and deploying IoT systems. It performs well on a constrained hardware platform and is managed and updated remotely post-deployment.

The ClearBlade Edge contains all the same ClearBlade Platform features. It can be deployed in remote networks to interact with sensors, controllers, and industrial systems.

Click here for the Edge tutorial.

Purpose

The projected IoT scale is in the magnitude of billions of devices creating and consuming data. ClearBlade has a solution built upon distributed systems to accomplish this:

Distributed system: Software system whose components are located on different computer networks.

A system can have one or more edges.

An edge is deployed to a particular network to capture, consume, and relay IoT data close to the source. Moving the computation closer to the data enables data processing that is magnitudes faster than what purely cloud-based IoT platforms can offer.

Learn about creating and installing an edge.

Requirements

Edge requires Linux and runs on nearly every CPU available. See Supported Linux distros.

OS	RAM	Storage
Linux	64MB	64MB

CPUs supported

x86	ARM	PowerPC	MIPS	s390x
AMD64 (x86_64)	ARM64	ppc64le	mips64le	s390x
i386	ARMv7	ppc64	mips64
	ARMv6	mipsle
	ARMv5 (TEJ only)	mips

Functionality

Strong edge security: Encryption, authentication, and authorization of API access, including tokens and certificates.
Sync and state management: User and device states are synced with IoT systems as devices go on and offline.
Offline continuity: Devices continue real-time behaviors and 100% uptime, even when the Internet connection is lost.
Strong integration capabilities: Connectivity via MQTT, REST, sockets, and prebuilt patterns for BLE, Zigbee, MQTT-SN, etc.
Data filtering and streaming: Store, modify, analyze, manage, and route data at the edge.
Business rules and events: Implement business rules, trigger and react to events, and analyze results locally via business logic.
Messaging: Scalable, secure message brokering between devices and users at the edge.
Deployment flexibility: ClearBlade Edge can be deployed onto various gateway devices.

Installing Edge

The Edge has a web frontend (data visualization, portals, and developer console).

Select one of the popular OS / CPU architecture combinations (see the full list below):

OSArch
linux-amd64
darwin-amd64
linux-arm64
linux-armv7
linux-armv6
linux-armv5

Verify which version needs to be installed. The edge, platform, and console versions should match.

Refer to the below script to perform the installations.

CODE

# Replace OSARCH if needed
OSARCH=linux-amd64
curl -fsSL https://get.clearblade.com -o get-clearblade.sh
sh get-clearblade.sh edge $OSARCH
sh get-clearblade.sh cb_console $OSARCH

Configuration

There are two ways to configure an edge:

Configuration file

Get the latest version of the TOML file using edge -h.

CODE

Title = "ClearBlade Configuration File"

[Debug]
DevelopmentMode = false # (boolean) Enables debug messages and triggers. Used only for development.
DisablePprof = true # (boolean) Disables pprof output file creation and web-server creation if set to true.
PprofCPUInterval = 10 # (int) The length of time, in minutes, to wait between successive pprof CPU profile generations.
PprofHeapInterval = 10 # (int) The length of time, in minutes, to wait between successive pprof heap profile generations.
PprofMaxFiles = 30 # (int) The maximum number of CPU and heap profiles to retain. 0 indicates keeping all of them.
PprofMaxFileAge = 1440 # (int) The maximum time, specified in minutes, to retain CPU and heap profile data files. 
DumpRoutes = false # (boolean). Dump the routes being served for diagnostic purposes.

[LeanMode]
LeanMode = false # (boolean) Stop storing analytics, message history, and code logs if set to true.
StoreAnalytics = true # (boolean) Stop storing analytics if set to false.
StoreMessageHistory = true # (boolean) Stop storing message history if set to false.
StoreCodeLogs = true # (boolean) Stop storing code logs if set to false.
MaxPageSize = 1000 # (int) Maximum page size for analytics calls.

[Logging]
Logfile = "" # (string) Logfile location. It will forward to its respective file handles if stderr or stdout are supplied.
MaxLogFileSizeInKB = -1 # (int64) The log file's maximum size before rotation in KB. It must be greater than 100 KB. -1 indicates no limit.
MaxLogFileBackups = 1 # (int) Maximum log file backups. It must be greater than 1.
LogLevel = "info" # (string) Raise minimum log-level (debug,info,warn,error,fatal).

[Edge]
EdgeID = "" # (string) Edge name.
PlatformIP = "" # (string) The Platform IP address without a port.
PlatformPort = "8951" # (string) RPC Platform port. Defaults to 8951 for TLS.
EdgeCookie = "" # (string) The edge session's cookie.
ParentSystemKey = "" # (string) The edge's parent system.
EdgeIP = "localhost" # (string) The edge's IP. Defaults to localhost.
EdgePrivateIP = "localhost" # (string) The edge's IP. Defaults to localhost.
  [Adaptors]
  AdaptorsRootDir = "" # (string) Directory storing adaptor files. Defaults to ./
  [Provisioning]
  ProvisioningMode = false # (boolean) Need to provision (point at a platform) before the edge is functional (default: false).
  ProvisioningSystem = "" # (string) The provisioning system's key (default: '').
  ProvisionalSqliteAdmin = "./prov_clearblade.db" # (string) The provisioning SQLite admin DB file location.
  ProvisionalSqliteUserdata = "./prov_clearblade_users.db" # (string) The provisioning SQLite userdata DB file location.

[FileHostingConfig]
URL = "http://localhost:8915" # (string) URL with the file hosting server's port. Defaults to http://localhost:8915.
EdgeBinaryLocation = "/edge/" # (string) Location where the edge binaries are stored on the file hosting server.

[Triage]
PerformTriage = (bool) Turns triaging on and off (default on).
TriageDays = (int) Number of days to keep triage information in the database.
TriageIntervalMinutes = (int) How often in minutes to report triage information.

[HTTP]
HttpPort = ":9000" # (string) The HTTP server's listen port.
HttpURL = "https://platform.clearblade.com" # (string) External Platform URL.
TimeProfile = -1 # (int64) Enables time profiling of HTTP requests (in ms). Default is disabled (-1).

[KVStore]
Store = "local" # (string) Specifies which KVStore to use. Supported stores are local and Redis.
Address = "" # (string) The Redis server address. Empty if using a local store.
Port = "" # (string) Redis port. Empty if using a local store.
Password = "" # (string) Redis username. Empty if using a local store.

[Security]
Tls = false # (boolean) Enable TLS.
Key = "" # (string) The TLS key file location.
Cert = "" # (string) The TLS cert file location.
ExpireTokens = true # (boolean) Set to invalidate user/device tokens issued more than the system's tokenTTL (defaults to 5 days). Dev tokens will not be removed.
InsecureAuth = false # (boolean) Disables password hashing if set to true. Used only for development.
Insecure = false # (boolean) Disables edge-to-platform TLS communication if set to true. Used only for development.

[MQTT]
BrokerTCPPort = ":1883" # (string) The MQTT broker's listen port.
BrokerTLSPort = ":1884" # (string) The MQTT broker's TLS listen port.
BrokerWSPort = ":8903" # (string) The MQTT broker's WebSocket listen port.
BrokerWSSPort = ":8904" # (string) The MQTT broker's TLS WebSocket listen port.
MessagingAuthPort = ":8905" # (string) The MQTT auth broker's listen port.
MessagingAuthWSPort = ":8907" # (string) The MQTT auth broker's WebSocket listen port.
UseTLSMessagingAuth = false # (boolean) Use TLS for MQTT auth broker.
MaxPublishSize = 1e9 # (unit64) Maximum MQTT publish packet size.
MessagingURL = "messaging.clearblade.com" # (string) Used to configure the external messaging Platform URL. May be proxied.

[Bus] # Deprecated.
ScoringFunction = "" # (string) The scoring function to use's name.
ClusterNodes = "" # (string) Overrides nodes in bus config filer.
BusConfFile = "" # (string) The bus's configuration file.

[Database]
DBStore = "postgres" # (string) Database store to use. Postgres for platform and SQLite for edge.
DBHost = "127.0.0.1" # (string) The database server's address.
DBPort = "5432" # (string) Database port.
DBUsername = "myUser" # (string) Username for connecting to the database.
DBPassword = "myPassword" # (string) Password for connecting to the database.
Local = false # (boolean) Use only local cache for storage. Used only for development.
SqliteAdmin = "" # (string) Location for storing SQLite admin database file.
SqliteUserdata = "" # (string) Location for storing SQLite admin database file.
DBType = "postgres" # (string) Postgres for platform and SQLite for edge.
Logging = false # (boolean) Additional logging for Postgres.
MaxMySQLDBConnections = 5 # (int) Max # of connections to MySQL to open, per collection.

[License]
PKey = "" # (string) Platform key issued by ClearBlade.
RegistrationKey = "" # (string) Key required for creating a new developer account.

[Sync]
SyncTransport = "mqtt" # (string) (Deprecated)
E2PInsertOnDeploy = true # (boolean) Disables or enables e2p insert behavior when only deploy is set in a deployment.
SyncOptimize = false # (boolean) Optimizes the syncing process if set to true.
SyncOptimizeExceptions = "" # (string) Exceptions for the sync optimization process.
SyncOptimizations = "" # (string) List specific optimizations to run. Default is all.
SyncDistributeWaitTime = 1 # (int) How long to wait before distributing asset sync events.

[MessageHistory]
DeletionEnabled = false # (boolean) Sets the default setting for message history autodeletion for new systems.
ExpirationAgeSeconds = 1209600 # (int64) Sets the default setting for new systems for the age at which a message should be deleted.
MaxRowCount = 10000 # (int) Sets the default setting for new systems for maximum rows after message history deletion.
MaxSizeKb = 15000 # (int) Sets the default setting for message history maximum size for new systems.
TimePeriodDeleteMsgHistory = 120 # (int) Set the time interval to erase msgHistory and analytics{Time.seconds} periodically.

[RPC]
RPCTransport = "tcp" # (string) RPC communication transport layer.
RPCPort = "8950" # (string) The external RPC server's listen port. Used for edge-to-platform communication.
RPCPortInternal = "8952" # (string) The internal RPC server's listen port. Used for node-to-node communication.
RPCTimeout = 30 # (int) Timeout for all RPC calls within the platform or from the platform to the edge.
RPCKeepaliveInterval = 60 # (int) The RPC connections keepalive internal.

[Cluster]
HostAddress = "" # (string) The IP address for other clustered nodes to contact this platform.

Flags

Default config, required flags

TLS: Enabled

Parameter	Type	Desc	Example
platform-ip	string	ClearBlade Platform URL	https://platform.clearblade.com/
parent-system	string	System key for this edge’s parent system	f49bf79f0b9ac5eda5aba4e08c17
edge-id	string	Edge name aliased as edge-id in the config	my-edge
edge-cookie	string	Edge token	5eda5aba4e08c17

Command:

CODE

edge -platform-ip=<PLATFORM_URL> -parent-system=<SYSTEM_KEY> -edge-id=<EDGE_ID> -edge-cookie=<EDGE_COOKIE>

Example:

CODE

edge -platform-ip=platform.clearblade.com -parent-system=f49bf79f0b9ac5eda5aba4e08c17 -edge-id=my-edge -edge-cookie=5eda5aba4e08c17

Non-TLS config

TLS: False (not recommended)

Parameter	Type	Desc	Example
see required
insecure	boolean	Connect MQTT over non-TLS	true

Command:

CODE

edge -platform-ip=<PLATFORM_URL> -parent-system=<SYSTEM_KEY> -edge-id=<EDGE_ID> -edge-cookie=<EDGE_COOKIE> -insecure=true -platform-port=<NONTLS_PORT>

Example:

CODE

edge -platform-ip=platform.clearblade.com -parent-system=f49bf79f0b9ac5eda5aba4e08c17 -edge-id=my-edge -edge-cookie=5eda5aba4e08c17 -insecure=true -platform-port=8950

Enhanced performance

Parameter	Type	Desc	Example
see required
lean-mode	boolean	Drop code service logs, TODO	true

CODE

edge -platform-ip=<PLATFORM_URL> -parent-system=<SYSTEM_KEY> -edge-id=<EDGE_ID> -edge-cookie=<EDGE_COOKIE> -lean-mode=true

CODE

edge -platform-ip=platform.clearblade.com -parent-system=f49bf79f0b9ac5eda5aba4e08c17 -edge-id=my-edge -edge-cookie=5eda5aba4e08c17 -lean-mode=true

Use with Web Console

Parameter	Type	Desc	Example
see required
edge-ip	string	The selected interface’s IP address (0.0.0.0 for all interfaces)	192.168.0.34

By default, an edge is only accessible via the localhost interface, localhost, or 127.0.0.1. For other IP-enabled devices to interact with the ClearBlade Edge, set this value to the edge’s IP address or 0.0.0.0 to expose the edge to all interfaces.

Syncing

When an asset is updated on the Platform, it is sent to all edges if the deployment declares it. When you update an asset on one edge, it occurs on the other edges and the Platform. In a disconnection, the Platform stores the sync updates and is queued for when the edge reconnects.

REST API endpoints can view the sync status for a single or all available edges.

Advanced

Supported OSArch list

OSArch
linux-amd64
linux-386
linux-armv7
linux-arm64
linux-armv6
linux-armv5 (TEJ only)
linux-mipsle
darwin-amd64
darwin-386
linux-ppc64le
linux-s390x
linux-mips
linux-mips64
linux-mips64le

Supported Linux distros

OS	Compatible
Darwin	yes
DragonFly	yes
FreeBSD	yes
Linux	yes
NetBSD	yes
OpenBSD	yes
Plan 9	yes
Solaris	yes
Windows	no

Distros	Minimum Required	Release Date	Details
Linux (Kernel)	2.6.23	2007-10-01	Details
RHEL	6.0	2010-11-09	Details
Debian	5.0 (Lenny)	2009-02-14	Details
Fedora	8 (Werewolf)	2007-11-08	Details
CentOS	6.0	2011-07-10	Details
SUSE	11.0	2009-03-24	Details
Ubuntu	8.04	2008-04-24	Details

More…

FAQ

1. What are the hardware requirements to run ClearBlade Edge?

See Hardware requirements.

2. How does a ClearBlade Edge connect to the ClearBlade Platform?

It makes an outbound encrypted MQTT connection to the Platform, enabling bidirectional data transport.

3. Should I modify my private network’s firewall to run a ClearBlade Edge?

Firewall changes are required to run the ClearBlade Edge as long as the Platform instance and devices it connects to are in the same private network.

4. What firewall changes do I need if I am trying to access ClearBlade Edge from an outside network?

Ensure the edge network’s firewall allows ports 9000 for HTTP(s), ¹⁸⁸³⁄₁₈₈₄ and 8905-8906 for MQTT, and 8903-8904 and 8907-8908 for WebSockets (if using them, usually the web console attempts to connect to the edge using WebSockets).

5. How do I forward an MQTT message from an edge client up to the ClearBlade Platform?

The ClearBlade Message Relay allows edge MQTT messages to relay messages up to the Platform’s MQTT broker or other edge brokers.

6. How do I configure ClearBlade Edge to start up on boot?

See our Service management repo to set up systemd or init.d with the Edge.

7. What are the features available on the ClearBlade Edge?

The ClearBlade Edge Platform is the lite version of the ClearBlade Platform. All the Platform features are available at the edge.

8. How can I create a collection that is only on the edge?

Log into the edge you want to create a collection on. Follow the process to create a collection as you would on the Platform. There is no way to sync collections on the edge to the cloud.

9. How can I create a trigger that only runs on the edge?

Go to Deployments in the Platform. Ensure the Deploy and Sync checkboxes next to Name under Triggers are unchecked. Then log into the edge you want the trigger to run on and create a service or choose an existing one. In the code service, create a trigger. The trigger should only run on that edge.

10. How do device updates on an edge get updated on other edges and the Platform?

Go to the Devices section under Assets in Deployment. Select Sync Table and choose all edges for deployment. Verify by changing data on one edge and see if it updates on the other edges and Platform. Refer to Syncing to how the mechanism works.

11. How can I transfer collection data to the edge?

Go to Deployments and click Collections. Choose Sync Table on the collection(s) you want the data to transfer to the edge. Mark the checkbox for the edge(s) you want the data to transfer. Learn more about collection deployment and the syncing mechanism.

12. Are ClearBlade SQL calls written dependent on whether they run at the edge or in the cloud?

Our Platform uses the Postgres database, and the Edge uses a SQLite database. We must use different databases to match the available environment infrastructure. If you are using our collections API, we abstract away the differences. If you use the SQL calls interface, you may have to handle the differences yourself.