Developing Apps¶

The Ecosystem offers all users the possibility to develop their own Industrial Edge App.

App Classification¶

Not every app is the same, so therefore the rules and guides might also not apply to the given use case. We are separating between these different app types, never the less one app can be part of multiple classification:

Southbound Connector App:
The purpose of Southbound Connector Apps are to collect data from field level as well as to aggregate and provide information for further usage to other apps.
Northbound Connector App: An app with the purpose of forward a data (or a subset) to overarching systems (e.g. IT, Cloud) is classified as a Northbound Connector App.
Data Bridge App:
Data Bridge Apps act as data transport and exchange layer between apps to enable end-to-end solutions.
Data Historian: Apps designed to store data over extended periods, thereby providing historical records, are known as Data Historians.
Configurator App:
A Configurator App is an app designed exclusively to configure other apps.
Processing App:
An app with the main purpose of generating insights for processing data. Processing apps fetch data from Data Bridge Apps and generate additional customer value.
Independent App:
Apps for providing a complete End-to-End use case, are classified as Independent Apps.

Software Design Regulations¶

Software design regulations can never be completely specified, because there are too many variations in how technical challenges can be solved. Therefore, the following is a description of the minimum requirements for successful app development.

Containerization¶

[Must] All apps must be encapsulated in one or more containers. These containers must be based on the Open Container Initiative (OCI) image specification and be compatible with Docker implementation.

[Must] An app is defined as a bundle of such containers that are orchestrated and configured via a Docker Compose file.

Versioning¶

All components in the Industrial Edge Ecosystem are versioned.

[MUST] Application, provided software and documentation must be versioned follow the semantic versioning 2.0.

[Recommended] All other software components (e.g. Docker-Images) should be versioned follow the semantic versioning 2.0.

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Device-agnostic¶

[Must] Apps must be designed to run on any or minimum one Industrial Edge Device.

[Must] The partner has to ensure that the app is working on minimum one latest released Industrial Edge Device version.

[Must] If the previous Device version technically supports all necessary functionality to run the App, the App Developer has to ensure that the App is also capable to run on this n-1 version.

[Must] All components must be designed to run on an x86‑64 or/and arm64 architecture.

Communication Standards¶

The standard for communication within the Industrial Edge Ecosystem is based on IP networks and utilizes protocols such as HTTP, HTTPS, and MQTT. Each service is accessible via a specific URL address and corresponding ports.

[Must Not] Communication between apps is not allowed to occur via the shared memory feature. Communication between containers within a single app, or the official Realtime-Data Bridge is allowed to use this feature.

Data-Integration¶

Currently, the best usage of Edge is working with Data. To keep and improve these strengths, we need to streamline data and ensure that the user can get the maximum quality information out of their dataset. To ensure all apps are providing their piece, they must fulfill these rules.

In the Industrial Edge Ecosystem, there are three defined domains: "IoT Data Domain," "Realtime Data Domain," and "No Data Domain."

[Must] Apps must determine their affiliation to a domain (best if it would support IoT and Realtime). If an app is classified as a Connector App, it must be part of the "IoT Data Domain" or "Realtime Data Domain."

[May] Applications are allowed to use any communication standard to other apps, unless they also provide a "Gateway" to the corresponding Data-Domain and publish a payload format via this documentation.

Check out the Data Domains for more details.

[Must] All generated data, according to the Data-Types, must be shared via a Data Bridge App.

[Must] All Processing Apps must be capable of receiving data from all Connector Apps via the specified Data Bridge App.

[May] Additional communication can occur via Point-to-Point communication.

[Must Not] Inter-app communication must not be hard-coded and should be adjustable by the end-customer to maximize the value of the Industrial Edge Ecosystem.

[Must] Communication must be designed according to the specifications and it's payload format.

Data-Types¶

[Must] All generated data, according to the Data-Types, must be shared via a Data Bridge App.

Industrial Edge Data Classification:

[Must be shared] Operational data: Describes machine condition and performance during operation (e.g., temperature, pressure, speed).
[Can be shared] Event data: Informs about specific machine events (e.g., starting, stopping, alarms).
[Might be shared] Diagnostic data: Used for fault detection and troubleshooting (e.g., fault records, diagnostic results).
[Should not be shared] Operating logs: Documents machine activities (used for trend analysis, compliance).

Data-Domains¶

[May] The Data-Domain technology does need not to be provided by Siemens AG. Customer can choose their own technology or a different offering unless broker aligns with all requirements.

IoT Data Domain¶

The standard Data Bridge App for the IoT Domain is an MQTT-Databus.
Supported mechanism: Publish/Subscribe Model, Message Routing, Session Management, QoS0-2
Historical data is supported in the IoT Domain.
If an application wants to supply historical data, it must support and provide queries.
Realtime data is not supported.

Realtime Data Domain¶

The standard Data Bridge App for the Realtime Domain is RIB.
Historical data is not supported in the Realtime Domain.
Realtime data is supported.

No Data Domain¶

In the "No Data Domain," no communication rules are established.

[Must] To be part of this domain, the app must be classified as an Independent App.
[Must Not] To be part of this domain, the app must not be classified as a Connector App.

Dataflow¶

[Should] Apps should use the Data Bridge App of their domain to transport data to other apps.

[Must] Connector Apps have to offer their data (depending on the classification) via the related Data Bridge App.

[Must] Northbound Connector Apps must offer the possibility to use MQTT as their datasource.

Data Historian¶

[Must] Every Data Historian must belong to at least one Data Domain and be capable of receiving data in the specified payload format.

[Should] Additionally, the historical data should be accessible through one of the provided Data Domain.

Payload Formats¶

[Must] If a payload standard has already been defined here, the apps are enforced to use this standard.

[May] Additional payload standards (e.g. for Point-to-Point communication) can be suggested and added to the Framework.

[Must] To provide a payload standard, it needs to well-documented, published and aligned with Siemens Industrial Edge Ecosystem.

Already defined payloads:

Deprecated

Specification	Version
Vision Payload specification	V1.0.0

Backup & Restore¶

The Industrial Edge State Service is the Industrial Edge disaster recovery solution that backs up and restores your edge device’s states.

The Industrial Edge State Service supports the backup and restoring of app volumes of the following types: Host, Logs, Configs and Auth Service.

[Must] To backup an application’s data, the application’s volume types must be one of the types supported by the State Service.

Focus on App Strengths¶

Every application has a defined purpose and function.

This enables customers to combine apps from different parties to create solutions for specific end user needs, instead of creating monolithic systems.

Self-containing¶

[Must] Apps must be self-contained, providing all necessary components to deliver their services. This means that the app should operate independently, without mandatory dependencies on other apps within their classification. The value of Industrial Edge lies in its ability to dynamically combine and extend offerings based on the specific needs of end users.

Awareness of other application¶

[Must] Due to technical restrictions of the Industrial Edge software, some configurations of an application need to be unique across all applications present in the marketplace.

These unique app identifiers are:

Logos
App Name
Repository Name
Service names
App specific URL subdirectory path.
Exposed Ports

These rulesets help users avoid unwanted behavior and enable the independent purchase of two applications. They also ensure that both apps can run simultaneously on one device.

[May] The only exception to this would be: The same "service names" or "App specific URL subdirectory path" are knowingly provided by one application provider with the intention of preventing these applications from running at the same time on the same device.

Processes¶

Apps are designed based on the "share nothing" principle, with services that act independently of each other.

[Must] Whenever possible, platform services must be used for shared resources. Deviations from this standard are the responsibility of the app provider.

Caching¶

[Should] Apps should provide sufficient caching strategies so that resources from app-external components are used reliably and economically.

Logs¶

[Must] Apps must provide log information about their work and state changes. Apps log this information via the "standard out" of their containers. This information is handled by edge devices and enriched with meta information.

[Must] If an app provider decides to define their own log files without streaming it through std out, it must contain all parts of a common log format.

[Should] A common log format consists of a plain text file that’s named app name and the file extension is .log. For multi-container applications, the container name should also be added.

The file needs to be stored to the standard volume for logs. Within the file, each logging event is written as one line and should adhere to the following structure:

Timestamp
Level of message
Emergency
Alert
Critical
Error
Warning
Notice
Information
Debug
App name (+ container name)
Message text

Availability¶

[Should] Providers should focus their app development on a fast startup and smooth shutdown of all app components. Ideally, an app should start within seconds.

Prevent Disruptions¶

Robustness on industrial products has a high priority.

[Must] Components must be designed to handle errors with as little disturbance as possible to other components.

Nevertheless, errors can occur. Therefore, apps need to be fault-tolerant in order to provide a smooth user experience and workflow.
Following this, all container of an app must have on of the following restart policies: on-failure, unless stopped or always.
An only exception to this, are so called "Init-Container". These are described in the upcoming section.

[Should] When a process receives a SIGTERM signal (usually from a process manager), it shuts down in an orderly manner.

[May] Optionally, limit the number of times the Docker daemon attempts to restart the container using the :max-retries option.

Also see: Start containers automatically

Init-Container¶

A container is clarified as an Init-Container when the following requirements are met:

[Must] At least one other container is depended on this container.

[Must] The container is intended and designed to run once when the app is started but will not be re-started, even if it fails.

[Should] The Init-Container should not run longer than 10 seconds.

[Must] The container must be labeled as init_{container}

User Interface¶

Industrial Edge is supported by a plurality of devices, display sizes, and resolutions in manufacturing.

[Must]Application providers need to consider this requirement in order to create a responsive Web design.

[Must] All application and device user interfaces must be Web-based.

[Must] User interfaces must accessible via the system provided reverse proxies.

Therefore, standard http behavior is required.

[Must] To reach a wide range of potential end user, the application must be optimized for state-of-the-art browsers: for example, Chrome without plug-ins using HTML5 and related technologies.

[Recommended] The Siemens Industrial Experience is recommended in order to create a consistent user experience.

[Recommended] Integrating touch support for dedicated use cases is also recommended.

Configuration¶

[Must] The application is designed to operate seamlessly without initial configuration. In the absence of such configuration, it will not terminate; rather, it will prompt the user to provide the necessary settings. This notification should be delivered through the application’s Web UI. In the event that a Web UI is not available, the application will relay this information via its log files.

[Must] The management and configuration of the application are integrated within the standard IE environment, eliminating the need for separate processes or tools. All related utilities, such as configurator, are included with the application’s release, facilitating on-the-spot data migration and configuration. Additionally, if the application is engineering software, the configuration can be excluded from the Industrial Ecosystem, acknowledging its distinct configuration needs.

[Must] All Southbound Connector Apps must be designed to also be configured via the Common Configurator. A detailed description on how to implement this will follow in a future update.

[Must] All Northbound Connector Apps must have a central configuration system, although the Common Configurator is recommended.

For further insights on administration processes within applications, you may refer to the principles outlined at The Twelve-Factor App.

APIs¶

[Must] All APIs that are intended for public use need to be documented in the product’s Developer Documentation.

[Should Not] Internal APIs shouldn’t be accessible in order to minimize the risk of security attacks. Using the OpenAPI specification formerly known as Swagger is also recommended.

[Must] API specification must have a versioning to ensure backwards compatibility.

Compatibility¶

[Must] An app must be compatible with the latest device-kit and Industrial Edge Management version to ensure minimum compatibility.

[Must] The app can be updated from any previous version without loosing customer data or breaking the current use case. If it do so, the MAJOR version of the application must be increased to inform the customer about the breaking change!

Beyond the technical prerequisites, apps also need to deliver a certain level value, quality, and performance to end user, which is described in the next section.

End User Value Assurance¶

The Industrial Edge Ecosystem is focused on end user value and a seamless user journey for end user.

[Must] To achieve this, applications must provide the following before they’re published to the Industrial Edge Hub.

provide a minimum functionality,
be sufficiently tested by their development team
have collected and integrated feedback from real-world application scenarios

Unique Solution¶

[Must] Apps must deliver a minimum functionality to provide a unique solution.

[Must] App must provide value for end user or support them in accomplishing their tasks.

[Must] To validate an app’s unique solution, the Marketplace entry will be reviewed to determine the application's potential usage scenarios and to identify any alternative solutions available to the end user for completing their tasks without using the app in question.

[May] Apps that don’t provide a unique solution may not be accepted.

Executable Applications¶

[May] Applications created only for runtime purposes may subsequently load executable code (e.g. VPLC).

[Must Not] All other applications are prohibited from loading remote code and functionality automatically, after the initial installation. Only code provided directly by the end-customer is allowed to be added to the app (e.g. Custom written code as a Plugin).

Limit Authorizations¶

[Must Not] Authorization which are not mandatory for fulfilling the usecase are not allowed to be requested from the app.

[Required] An app’s required access rights need to be described in the Marketplace entry.

Extracting Offerings¶

[Must Not] Apps that monetize primary based on other ecosystems aren’t allowed in the Ecosystem.

[Must Not] Apps that focus primarily on the extraction of production or end user data to other ecosystems without delivering value for the Ecosystem aren’t allowed in the Ecosystem.

Spoiling Apps¶

[Must Not] Apps that disturb hardware, networks, Industrial Edge infrastructure, or other third-party apps aren’t allowed in the Ecosystem.

Deceptive Apps¶

[Must Not] Apps that are intended to trick end user or enable illegal unfair activities for end user or the Ecosystem aren’t allowed in the Ecosystem..

Infective Apps¶

[Must Not] Apps that contain or support malicious behavior, viruses, malware, or phishing aren’t allowed in the Ecosystem.

Device-changing Apps¶

[Must Not] Apps that change the settings of devices are only allowed if the user is receiving informed about them, has agreed to this, and can undo the changes.

Ecosystem Inside the Ecosystem¶

[Must Not] Apps that create a nearly closed ecosystem inside the Ecosystem or build a bridge to other ecosystems aren’t allowed in the Ecosystem.

Copycats¶

The Industrial Edge Ecosystem protects their app providers’ intellectual property.

App providers are entitled to the rewards of their work and investments.

[Should] Therefore, each app provider should use their own ideas and not simply copy other app providers’ successful products (for example an app provider uses another app as a template and copies it).

If you find suspect apps, you can report them to the Ecosystem orchestrator

Entitlements¶

Entitlements are entities that allow the app to validate and measure the user's purchased and allowed usage versus actual usage. Entitlements can be defined without a unit, functioning in an on/off manner, or with a unit, making them cumulative. Cumulative entitlements are designed to be allocated multiple times to one device. Any entitlement that depends on another entitlement must be included in the same License Package. Entitlements that grant the basic running feature of the app are prohibited from being included in an Addon.

License Enforcement¶

License Enforcement is a comprehensive technical and administrative mechanism designed to ensure strict adherence to software licensing agreements. It implements systematic controls to prevent unauthorized usage, protect intellectual property, and manage software access through predefined authorization protocols.

[Must] The License Enforcement must be implemented entirely by the app developer. [Must] Apps must follow our guidelines on enforcement levels to ensure a solid user experience, depending on the app.

There are three ways to enforce a license, categorized by different levels of "hardness." The app developer can choose the enforcement level for their app:

No Enforcement: The app does not enforce behavior at any point, only monitoring usage.
Soft Enforcement: After a period of 30 days without valid license communication, the app's main function will stop working.
Strict Enforcement: After a period of 7 days without valid license communication, the app's main function will stop working.

[Must] A product and all its addons must have the same level of enforcement behavior.

Enforcement Phases¶

The Ecosystem grants three different phases of app enforcement:

Default Running Phase (Soft: 0d-2d / Strict: 0d-0.5d)

Phase 2: Nagging (Soft: 2d-20d / Strict: 0.5d-5d)

Phase 3: Disabling some functions (e.g., providing new configuration, but not the main function of the app) (Soft: 20d-30d / Strict: 5d-7d)

Phase 4: Disabling all app functionality (Soft: 30d+ / Strict: 7d+)

[May] Intermediate phases do not need to be enforced.

App Prototyping¶

[Required] All applications submitted to the Marketplace must be the final version for end user use.

[Must] Therefore, providers need to ensure that it’s a sellable product. Demos, betas, Pre-Releases and similar offerings don’t belong on the Marketplace.

[Required] App Provider have to test their apps in-house in the latest released edge environment to ensure the compatibility and functioning of their app before publishing it.

App Developer Testing¶

[Must] App providers are responsible for developing, evaluating, and testing their apps in terms of technology, functionality, performance, security, and user interface.

[Must] They’re also responsible for establishing and maintaining the compatibility of their apps in the Industrial Edge environment (see also Ecosystem Agreement).

[Must] For X86-architecture applications, a Siemens IPC227e, and for ARM64-Architecture applications, a Siemens SCALANCE LPE9413, running the current and previous runtime versions is used as a reference device to test and ensure app compatibility. If the device does not meet the app's requirements, testing can be conducted with a different device, but this information must be transparent to all testers and users.

[Should] To ensure future a computability of your application with upcoming device versions, access to the Ecosystem-Prod environment should be requested and your application should be tested against the versions available on Ecosystem-Prod .

[Must] After app providers successfully test their applications in-house, they can set their version to the Ecosystem Review stage, with the "Public-Release" stage as goal.

Ecosystem Review¶

The Industrial Edge Test Center will check user key workflows, compatibility, performance, and other factors.

Every application intended for sale on the Marketplace must request the enablement of the Ecosystem Review stage.

If there are negative findings during the technical publication process at the Hub, the details will be provided to the app provider.

[Must] Apps that are submitted for technical review on the Industrial Edge Hub must be the final version with all necessary information. Ensure that an app has been tested for compatibility and bugs before submitting it.

[Must not] Apps that crash or have obvious technical problems won’t be accepted.

[Must] Large-scale tests are conducted for initial versions and major-change versions during the Ecosystem Review. For minor and patch versions, either small (automated) tests will be performed, or the Ecosystem Review will be skipped.

[May] Additionally, random samples of all version may be taken for compliance check.

[Must] All issue(s) need to be resolved before re-submitting the app to the Ecosystem Review.

During the technical review process, the following areas will be addressed:

Interaction between applications and Industrial Edge services
App file format and structure
Container state and health
Hardware demands
App security
Execution of individual process flow for every application
Application policies
etc.

The following needs to be provided for a successful technical review:

Application file in format “.app” (upload in Hub)
User manual (link to Web site)
Minimum hardware demand required for smooth operation (via Mail)
Public API specifications (link via Mail)
Description of core workflow of the application for testing purposes (via Mail)
etc.

[Must] The following needs to be provided for a successful onboarding on the marketplace:

OSS Readme file: can be .txt, .pdf, HTML and can be packed as archive mentioned below.

Additional information that can’t be provided in the Hub should be sent to the Ecosystem Orchestrator. For more details see:

After a successful technical review, the app will be validated as a technically approved app. Because technology and business are always interacting, the following chapter explains the rights and responsibilities of app providers from a commercial perspective.

Because an app provider’s goal is to be onboarded on the Marketplace, the next section describes the deliverables required for a successful Marketplace listing.