Edge
- Jeff Slavin (Unlicensed)
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.
# 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 $OSARCHConfiguration
There are two ways to configure an edge:
Configuration file
Get the latest version of the TOML file using edge -h.
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 | |
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:
edge -platform-ip=<PLATFORM_URL> -parent-system=<SYSTEM_KEY> -edge-id=<EDGE_ID> -edge-cookie=<EDGE_COOKIE>
Example:
Non-TLS config
TLS: False (not recommended)
Parameter | Type | Desc | Example |
|---|---|---|---|
|
|
| |
insecure | boolean | Connect MQTT over non-TLS | true |
Command:
Example:
Enhanced performance
Parameter | Type | Desc | Example |
|---|---|---|---|
|
|
| |
lean-mode | boolean | Drop code service logs, TODO | true |
Use with Web Console
Parameter | Type | Desc | Example |
|---|---|---|---|
|
|
| |
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 |
FAQ
1. What are the hardware requirements to run ClearBlade Edge?
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), 1883⁄1884 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.