Skip to content

Getting Started With AppSDK

This documentation can be followed to prepare a development environment for developing Edge applications and learn how to run those applications on SINUMERIK Edge.

Set up operating system

Debian 10 (Buster) is recommended to be used to run AppSDK without any problems. Debian 11 (Bullseye) and Ubuntu can also be used where AppSDK can work.

  • Firstly download and run Debian 10 (Buster) Environment.
  • Make sure that this Debian 10 (Buster) environment connects to the internet.

Warning

Debian 10 (Buster) strongly recommended to be used for VM

Instructions on creating development VM

Following instructions can be used for setting up a development VM. If you already know how to create a Debian 10 (Buster) VM you can skip this section.

First, install a hypervisor of your choice.

VMWare Player

VirtualBox

Following description relates to usage of VMWare player or commercial VMWare Workstation with Debian Live.

After installation of the virtual machine, player download the operating system from Debian.org

This tutorial was issued with debian-live-10.4.0-amd64-lxde.iso Set up your virtual machine within your player by creating a new guest.

Once the virtual machine is started the Debian installer menu will pop up. Choose the Debian installer of your choice in this case ´debian installer´ (navigate with arrow keys, select with the space bar).

  • Language: my language
  • Location: my country
  • Keyboard Layout: my keyboard layout
  • Network Configuration:
  • Host Name: my hostname
  • Domain: my domain; e.g. siemens.net
  • Input Root Password: leave that empty at best (you will be granted sudoer rights with the standard user)
  • Confirm Root Password: leave that empty at best
  • Issue user account
  • Full Name For User: your full name (You can just leave blank)
  • Account Name: your account name
  • Input User Password: your user password
  • Confirm User Password: confirm your user password
  • Configure the clock
  • Select your timezone: Select your timezone
  • Partitioning
  • Partitioning method: Guided - use entire disk
  • Select disk to partition: Select shown disc
  • Partitioning schema: Select all files in one partition (recommended for new users)
  • Confirm partitioning : Finish partitioning and write changes to disk
  • Confirm partition flashing: Select yes - This will take some minutes
  • Confirm to use a network mirror: yes
  • Choose your country: from list
  • Choose your server: from list
  • Configure Proxy: http://[user:password]@IP-Addr:port (if needed if not leave empty)
  • Install GRUB Bootloader: yes
  • Install Bootloader on disk: choose /dev/sda
  • Finish installation: this will actually take some time so... be patient

Installing Open VM tools

To interact with your VM (copy/paste, shared folders etc.) following packages should be installed 

sudo apt-get install open-vm-tools open-vm-tools-desktop

Installing Docker

Following dependencies are needed to develop or run applications with AppSDK.

  • Docker
  • Docker-compose

Docker and docker-compose should be installed from the internet to your local Debian 10 (Buster) environment.

For more info please refer to

Official docker install documentation.

Official docker-compose install documentation.

Download AppSDK Development Environment

Download AppSDK development environment packages from Manage MySINUMERIK Edge /App Publishing Insights Hub application.

Step by step instructions for downloading AppSDK packages from Manage MySINUMERIK Edge /App Publishing can be found here.

Extract AppSDK Development Environment Package

Extract supplied AppSDK development environment files to a directory of your choice.

AppSDK Development Environment packed in tar.gz format. To extract them execute the following command in the same directory with the downloaded package. 

tar -zxvf appsdk_development_environment_<version>.tar.gz

Install AppSDK Development Environment

The extracted directory contains a folder and a bash script called 'install.sh'. install.sh script installs all required dependencies for AppSDK, indapp-build and AppSDK Development Environment.

Warning

Due to external package changes in Python packages, old AppSDK development environment versions for images v3.0.0/v3.0.2 (1.6.2) and v3.1.0 (1.8.2) may fail to install. In case of error, users can obtain patched files for previous version from most recent AppSDK development environment release. The most recent package contains patched install.sh files for 1.6.2 and 1.8.2. Users can replace old files with backported versions.

Warning

Due to certificate expiration, the simulator environment of old AppSDK development environment versions for images before v3.3.3 fail to execute. In case of error, users can obtain patch script from most recent AppSDK development environment release. The most recent package contains patch.sh script and patched files under backport folder. Users can execute patch.sh script under this folder to update certificates of AppSDK development package and patch failing modules. For script usage, please refer to instructions in patch.sh --help.

Execute install.sh script with the following command. 

./install.sh

Warning

During installation, new certificates are created and installed in AppSDK development environment. For existing projects, update_appsdk_cert <project_folder> command is needed to be executed in order to update new certificates in appconfig.json files.

Creating your first project

Run appsdk init command in an empty directory of your choice to initialize new AppSDK project.

appsdk init
  • Select your desired programming language by typing the language name
  • Enter your application name with no space
  • Select your sample application type
    If you wish to follow this documentation step by step please choose HF Data Sync App (4)
  • Select miniweb configuration type
  • Select fileuploader configuration type
  • Enter GPU configuration
  • Enter VNC configuration

miniweb, fileuploader, GPU and VNC configuration will not be used in this getting-started documentation and can be selected as no. More information can be found on relevant sections.

Once the steps above are finished, your application folder will be created with the following file structure. 

.
├── appsdk-project.yaml
├── config
│   └── delta.json
├── misc
│   └── ...
├── package
│   ├── docker-compose.yaml
│   ├── Dockerfile
│   ├── OSS_README_sample.txt
│   └── Sample_document.pdf
├── scripts
│   └── buildProject.sh
└── source
    ├── appconfig.json
    ├── EdgeAPI
    │   ├── include
    │   │   ├── edge.py
    │   │   └── _edge.so
    │   └── libs
    └── Sample.py

Building your project

You can build your project with the following command 

appsdk build

Once appsdk build command is executed, a build folder is created with required files for indapp creation.

Running Edge Service Mocks Locally

You can always run your application with supplied service mocks on your local development VM. 

appsdk start all

Once execution finishes you can check the status of mock services from using the command below. 

docker ps

The similar output should be observed after execution finishes.

CONTAINER ID        IMAGE               COMMAND                   CREATED             STATUS              PORTS               NAMES
2724bf2dec07        simulator           "/bin/sh -c /usr/bin…"    4 seconds ago       Up 3 seconds                            simulator
863945a0f452        databus             "/bin/sh -c \"/usr/sb…"   3 minutes ago       Up 3 minutes                            databus

Test your environment

Once AppSDK Edge Service Mocks start to run, you can execute and test your application locally.

Go to build directory inside your project with the following command 

cd build

For C++

"Sample" executable can be executed with the following command. 

./Sample

For Java

"Sample" executable can be executed with the following command. 

java -cp ./EdgeAPI/include/edge.jar:. -Djava.library.path=./EdgeAPI/libs/ Sample

For Python

Sample.py can be executed with the following command. 

python3 Sample.py

What to expect when HF Data Sync App is executed

When HF Data Sync App app is up and running, Mosquitto connection information should be written as follows;

Connecting to broker on port 8883...using TLS version tlsv1.2 and CA /tmp/ca.crt...Connected to broker.
SUCCESS
DatabusManager: Channel has been initialized

Warning

Logs on SINUMERIK Edge and local tests are the same. Same logs can be excepted to be seen while running application on SINUMERIK Edge.

If these steps are validated, Simulator can be started with the browser on the following address:

http://localhost:20000

When this address is launched, Simulator UI will be shown.

Now data simulation can be started as described here

More detailed description regarding Data Simulator functionalities can be found here

Warning

Before starting simulator, it should be checked that simulator is running in Standalone mode.

After starting simulator, received data should appear on running HF Data Sync App terminal.

Up to this point connectivity to databus is validated and HF Data Sync App runs without any problems. From now on, using detailed AppSDK API documentation, sample application can be modified according to development needs.

Develop your application

Edge application can be developed in three languages. Usage of AppSDK methods are explained extensively on the following pages.

Programming Language Documentation
Python GO TO PAGE
Java GO TO PAGE
C++ GO TO PAGE

Configure your application based on your development

Metaconfig file is used to configure your application and should be provided along with application artifact named indapp during publish an application to Insights Hub.

appsdk package command creates a default metaconfig file.

Default metaconfig file has to be modified for the features which are used in the application.

delta.json file under config directory of your project is automatically merged with created default metaconfig file. In order to append created metaconfig file manually, any addition can be added to delta.json file so that while creating indapp these additions are inserted into created default metaconfig.

You can modify this default metaconfig file or detla.json file according to your application needs as decribed in detail here.

During development, you will need to execute your application in your local environment for debugging or test purposes. That means you will need application instance config files named appconfig.json for AppSDK libraries in runtime.

appconfig.json is normally created by SINUMERIK Edge Platform by processing metaconfig file and placed in the right location for the application to access in runtime. appconfig.json file that you use in your local development environment is just for development purposes, you will not need this file in any other further steps except for your development.

Every created project also comes with appconfig.json file. This appconfig.json file works with provided sample application for local testing.

So you can run your application with your local environment without SINUMERIK Edge Platform components. Please find details regarding appconfig.json file here. You can modify these files according to your application needs during the development phase.

In case of you make modifications in appconfig.json in development, you need to reflect those changes to default metaconfig file as well when you publish application to Insights Hub. Reflecting changes to metaconfig file can be done automatically with editing delta.json file as described previously.

To reflect changes to metaconfig file, please go through Create the Metaconfig section in developer manual here and configure every section as described.

Packaging Your Application For Deployment

In order to deploy your application, you need to create indapp package (containerize) of your application first. You can create indapp package of the project using the following command. 

appsdk package

After executing this command, indapp, swu and metaconfig.json files will be created.

Publish your application to Insights Hub with ManageMySINUMERIK Edge /App Publishing

After building your application with appsdk build command and then packaging your application with appsdk package command you can publish your application using appsdk publish command.

Please note that appsdk publish command requires some information regarding your application.

This information is supplied under deploy_config section of appsdk-project.yaml

Please refer here for more information.

Deploy your application to SINUMERIK Edge

Check that SINUMERIK Edge is onboarded

To operate deployment, it should be checked if your SINUMERIK Edge is onboarded. Document here explains how to check onboarding status and how to onboard your SINUMERIK Edge.

Check that SINUMERIK Edge is connected to the Internet

It should be checked if your device can connect to the internet and connection status is online. Detailed information about connection status can be found in Document here.

How to Deploy your application to SINUMERIK Edge

At this point, the release of an application needs to be deployed to an asset. In Document here process steps about deployment are explained. After deployment, application needs to be installed to SINUMERIK Edge as axplained in Document here.

Run your application on Manage MySINUMERIK Edge

Your application can be run after finishing all previous steps, with the guidance of Documentation as explained here.

App Management on Diagnostic Dashboard Application

After publishing to Insights Hub and running your application on SINUMERİK Edge, the current status of the application can be checked by accessing Diagnostic Dashboard Application. On Diagnostic Dashboard Application; status of the application can be seen. Also, Application Logs can be checked and application UI can be accessed on Diagnostic Dashboard Application. Further information can be found in Documentation here.

Warning

As soon as application is running on SINUMERİK Edge, the same logs as explained in What to expect when HFDataAsyncApp is executed should be seen in application logs.

Activate Adapter Apps

In order to get data from SINUMERIK NCU adapter apps must be installed and active. To do that, explanation in Documentation here can be followed.

Certificate renewal of AppSDK development environment

User can renew certificates that are used in simulator and local debugging environment.

In order to renew certificates, execute following command

renew_appsdk_cert [<project_folder>]

If project folder is provided, after certificates are renewed and updated in simulator environment, certificates for connecting databus in project folder is also updated.

Certificates for connecting databus in project folder can also be updated later by following command :

update_appsdk_cert <project_folder>

Any questions left?

Ask the community

Except where otherwise noted, content on this site is licensed under the The Siemens Inner Source License - 1.1.