Franka World user manual

Table of Contents

1 Introduction

Welcome to Franka World, the center of the ecosystem around Franka Emika robots and users. The goal of this document is to provide you with an overview of all the Franka World features and how to access them. If you want to know how to get started as fast as possible, continue reading the Quickstart section.

1.1 What is Franka World?

Franka World is an online platform that interconnects customers, partners as well as software and hardware developers, whose activity revolves around Franka Emika’s products and services. Franka World provides tools for managing Panda robot, access to an online store which features a continuously growing portfolio of software and hardware products, and the possibility to become part of an active and passionate community.

2 Quickstart

  1. Login: When accessing Franka World the first time, you are asked to login using a username and password.

    login.png

    Figure 1: Login form of Franka World.

    In case you have been invited, you can use the link in the mailing to login and set a password. Any account administrator can invite new users, so check with your colleagues, whether your company already has an account and let them invite you with your e-mail. This can be done under Manage > Users and more detailed instructions can be found here.

    If not, start by registering a new account and user using the "CREATE ACCOUNT" button. Provide necessary details about your company and yourself. Also, if you are already a customer of Franka Emika, please also provide the customer id as printed on quotes or invoices.

    In any case, after this step you will have a registered user with email and password, which has access to (a newly created) account. For an detailed explanation about registration and the difference between a user and an account, refer to section User & account management.

  2. Device registration: To register your first robot to Franka World, proceed on the device, typically reached when connected to the robot base using https://robot.franka.de. Ensure that the system version is > 4.0.0, by optionally installing the upgrade from here.

    The robot will then try to connect to Franka World to provide an easy way of registering and synchronizing as seen in Settings > Franka World page on the robot user interface. If this is not possible, your device can be registered and updated by uploading files manually. Just follow the step-by-step instruction in Settings > Franka World.

    register-device.png

    Figure 2: Registration screen in the robot user interface.

    More details about the registration process can be found in Robot management.

  3. Synchronize: After registration, your device shows up in Franka World in the Manage > Devices list. In the device detail page, the current device status like connectivity, installed system version or installed apps as seen by Franka World is displayed. On this screen you also see previously purchased Apps & Features. By ticking the check boxes next to Apps or Features you mark them for installation onto the device, which needs to be saved by pressing "APPLY" and "CONFIRM" in the dialog.

    device-detail-apply.png

    Figure 3: Changing app assignments on the Franka World device detail page.

    If the device is online, you can finalize synchronization of new and updated software directly on the robot's Settings > Franka World page.

    synchronize-device.png

    Figure 4: Download new and updated apps directly from the robot user interface (robot is online).

    If the device is offline or you are not sure, download an update file from Franka World in the synchronize dialog by clicking on "SYNCHRONIZE" on the Franka World device detail page and use it on the robot.

    device-detail-synchronize.png

    Figure 5: Synchronization instructions in Franka World (robot is offline).

    If you are missing Software you have already purchased, don’t hesitate to contact our Support (support@franka.de).

3 User & account management

This section explains features related to users and accounts, including registration and login. To explain these parts of Franka World, we need to get some terminology out of the way first:

In Franka World there are users and accounts. A user represents a person which is identified by a unique email address and can log in using a password. An account is a logical organisation unit owning robot devices and licenses. Users may have access to one or more accounts and in each they have a user role. For example, a common situation is that a company has an account in Franka World, where individual employees have users with access to this account.

3.1 Login and registration

As also described in the Quickstart section, users need to login to Franka World using their email address and password. After successful login, the user's first name and their (currently selected) account is shown in the top right corner of Franka World:

profile-account.png

Figure 6: Logged in user name and selected account with logout and account switch buttons.

Note that credentials are remembered automatically until the user explicitly logs out using the logout button logout-icon.png. Should you do not have a user and account already, there are two ways to get access to Franka World:

  1. Get invited by an account administrator, who can add you as a new user to an already existing account. Instructions to this can be found here.
  2. Create a new user and account using the "CREATE ACCOUNT" button on the login screen and filling in the registration form.

    registration-form.png

    Figure 7: Registration form to create a new company account and user.

    The company name will serve as the account name and a VAT (tax) id is required because Franka World is a B2B platform, while the provided first and last name, as well as the email address are used to create a new user, the first account administrator. If you are already a customer of Franka Emika, please also provide the customer id as printed on quotes or invoices.

    Please also carefully read and accept our linked terms of use. After submitting the form by click on "CREATE ACCOUNT", an e-mail will be sent to the e-mail address provided with further instructions to set a password and logging in.

3.2 Password reset

If you have forgot your password or you want to change it, you can request a password reset from the login screen. This will send you an e-mail with a link, from which you can set a new password.

password-reset.png

Figure 8: Password reset screen in Franka World

3.3 User profile / change language

When logged in, you can access your own user profile by clicking the user name in the top-right corner of the navigation bar ("Sebastian" in this example). On this page you can change your personal details or change the language of Franka World to your liking.

3.4 Switching accounts

A single user can have access to multiple accounts. This, for example, is useful to organize a company's robots in one account, but manage robots of their customers in individual other accounts.

After login, the last used account is automatically selected current account is displayed next to your user name in the top-right corner of the navigation bar ("Franka Emika GmbH" in this example). All actions within the Manage and Store areas are performed using this account, i.e. Manage> Devices lists the devices of this account, while Store > Order history shows past orders of this account.

To switch the account "scope", first click on the account switch icon account-switch-icon.png, and simply select one of the listed accounts. Note that you also see your user role within those accounts here. To find out more about user roles and managing users, proceed to the next section Manage account users and their roles.

account-switch.png

Figure 9: Example list of accounts available to switch into

3.5 Manage account users and their roles

Conversely to a user having access to multiple accounts, an account can provide access to its robots and inventory to multiple users. Moreover, each user has a specific role in an account. Currently this role is either an "Account Admin" or an "Account User". The following table lists the differences:

Account functionality Account User Account Admin
View account details yes yes
Edit account details no yes
View users yes yes
Change user roles no yes
Add new users no yes
Register devices no yes
Manage devices yes yes
View inventory yes yes
Order products no yes
View order history no yes
(partners only)    
View own products yes yes
Manage own products no yes

To list all users of an account and also see their current roles, switch into the account of interest, and navigate to Manage > Users. If you are an Account Admin, you can also change the role of any user on this page using the respective dropdown.

manage-users.png

Figure 10: Manage users of an account (as Account Admin)

On this page you can invite new users to your account by entering their e-mail address into the text box on the top-right and clicking on "ADD USER". If there is already a user with the provided e-mail address, the existing user is simply invited to your account. However, if the e-mail address is not known to Franka World, you are prompted to enter some more information and upon clicking "SAVE" a new user is created and invited to your account.

manage-users-add-new.png

Figure 11: Add a new user to Franka World

NOTE: Removing users is currently not possible using the user interface. Feel free to contact support@franka.de for this.

3.6 Account details

Analogous to the user profile, account details can also be accessed by clicking on the (currently selected) account name.

account-details.png

Figure 12: Full account details page, viewed as Account Admin of an already verified account

Note that editability of individual fields depends on your user role, and if your account is marked as a verified customer. While account users can view all details here, account admins can edit account name, addresses and contact details.

In the first section you can see and update the account name as it is also shown throughout the platform. Here you also find the account ID and, if already given, the customer ID of this account.

Providing a VAT ID and billing address is required if you want to place an order in the store using this account. Also during the order process, your account is verified and assigned a new or existing customer id (that's why we ask you for your customer id during registration). After this, any updates to your VAT ID or billing address needs to be requested via support@franka.de updates to your account.

An account's contact details are initially filled with name and e-mail address of the first user, however they do not need to match with any of the users, so feel free to update as required. The given e-mail address will receive order confirmation, license delivery and other e-mail notifications.

4 Robot management

Keeping an overview, adding, removing and updating software of Franka Emika robots is one of the main pillars of Franka World functionality. More specifically, not the robots themselves, but the Control is registered with an account in Franka World. Thus, the robot systems are identified by the Control serial numbers (S/N in short) and are always managed within an account.

Besides operating system updates, software can also be added and removed from robot systems using an account's inventory of App & Feature licenses. Apps are re-usable robot programs available in the Desk robot user interface, while Features are extensions to the operating system of Franka Emika robots typically enabling new communication protocols or functionality. To find out how you can find and purchase more software licenses, refer to chapter Browsing and ordering in the Store.

4.1 Robot device registration

Before a robot shows up in your Manage > Devices list in Franka World, it needs to be registered to your account. This connects the robot's and your account's inventory and allows you to decide what software packages are desired on each robot.

To register your robot, connect to the robot user interface as you would be using Desk, for example when directly connected to the robot's base using the https://robot.franka.de URL - see robot user manual for details. In the Settings page of the robot's user interface you can see the currently installed system version. If your system version is lower than < 4.0.0, you need to first install the upgrade from here.

Starting from version 4.0.0, Franka Emika robots are cloud enabled and can be registered with Franka World in the Settings > Franka World tab. On this page you can see the control serial number, the Franka World account owning this robot ("-" before registration), as well as the connection status to Franka World.

4.1.1 Franka World connection

The robot tries to connect to Franka World directly to simplify registration and software installation by contacting our IoT servers (hosted by AWS in Frankfurt) using an end-to-end TLS encrypted TCP connection. More specifically, the robot tries to connect to hostname a3bcm7vfvlv56h-ats.iot.eu-central-1.amazonaws.com on port 8883. This is currently not configurable, so if you want the robot to come online, please ensure that it can reach this endpoint via the shop-floor connection. The robots send information about their status and identity as well as currently installed Apps & Features to the Franka World servers. We take great care that these information is only provided to your account's authorized users and is not shared with other parties. More information about this can be found online in our privacy policy.

4.1.2 Online registration

When the robot is online, registration is as simple as clicking the "REGISTER DEVICE" button on Settings > Franka World page.

register-device-online.png

Figure 13: Robot Settings page of an online, but unregistered device

This will navigate you to Franka World with a special link which proofs ownership of your robot. If required, do log in with your e-mail address and password. You should end up on a page where you can choose into which of your accounts the robots shall be registered. After clicking "REGISTER" the device will show up in the selected accounts' Manage > Devices page.

register-device-account.png

Figure 14: Account selection as final step of device registration

4.1.3 Offline registration

When the device is offline, the Settings > Franka World page shows detailed instructions about the three-step process of registration using a registration file.

register-device-offline.png

Figure 15: Robot Settings page of an offline, but unregistered device

The first step will provide you with this device-specific registration file, which is named like register-200000-0000003-2020-09-08-13-05-16. As your pc is likely not connected to the internet as well when the robot is offline, you need to connect to the internt now or transfer this file to an online computer.

As described in step two, the registration file needs to be uploaded to Franka World here: https://world.franka.de/accounts/assign-controller-offline. Using the "UPLOAD" button, pick the registration file which will take you to the same screen as in the online workflow, where you can "REGISTER" the device.

Important: Although your device does show up now in the device list, the robot itself does not yet know about it's registration and you need to perform an offline synchronization before the device is fully registered and ready to use.

4.2 Device details

All registered robots of an account are listed on the Manage > Devices page. Here you can already see some identifying information about your robot systems like serial number, given name and location, as well as installed software version and online status.

manage-devices.png

Figure 16: Device list of an account.

Known issue: The updates indicator in the full device list page is sometimes reporting "false positive" that there are updates, even though everyting is up-to-date. The device detail page or the Settings > Franka World page on the robot are correct.

By clicking on any of the robot devices, you are taken to a detail page which also allows customization of the robot's name and location attributes. Furthermore, this page shows currently assigned software licenses and their installation status.

manage-devices-detail.png

Figure 17: Device detail page of an online robot with some apps installed.

4.3 Adding & removing software / Synchronization

The Features & Apps areas of the device detail page do list all respective licenses from the account's inventory, which can be viewed also separately under Manage > Inventory. If you owned your robot before Franka World was launched, already installed and purchased software will show up in your inventory when registering the robot to your account.

Using the checkboxes next to the entries, you can select which Apps & Features should be installed on a robot system. A changed selection needs to be confirmed with "APPLY" and in a pop-up dialog. When adding "available" apps to the device, later synchronization will download and install them on the robot. Removing apps on the other hand will mark a license as "removal pending" and synchronization will have the robot uninstall the software. After that, the license will become "available" again.

Whenever different software is selected or there are updates for your device, the "SYNCHRONIZE" button becomes enabled and (i) marks indicate that you should synchronize your device. Depending on whether the device is currently online or not, instructions are shown how to synchronize changes from Franka World to your robot.

4.3.1 Online synchronization

Connected robots do see confirmed changes in the Apps & Features list of the device page in real-time. Thus, whenever synchronization is required, you see available changes in in Settings > Franka World on the robot user interface and can have the robot conveniently download updates for you using "DOWNLOAD CHANGES".

sync-available-changes.png

Figure 18: Available changes as seen from an online robot.

Note: Should the available changes include a system update, this can take a couple of minutes depending on the robot's connection quality to our servers in germany. If you want you can also use an update file like in the offline synchronization workflow to get a download progress.

After transferring the necessary files, you can review and either "DISCARD" or "APPLY" them. Depending on changes to be applied, the robot system might also need to reboot but will ask for further confirmation in a pop-up. If all pending changes have been applied, your system should be up-to-date as indicated by the following screen.

sync-clean.png

Figure 19: Fully synchronized, online robot.

4.3.2 Offline synchronization

To synchronize license changes made in Franka World or to get system updates on offline devices, so-called update files and status files are used to new & updates software and status updates forth and back between Franka World and the robot. The Settings > Franka World page, as well as the "SYNCHRONIZE" dialog in the Manage > Devices detail page shows instructions on how to perform this.

sync-offline-dialog.png

Figure 20: Dialog shown in Franka World how-to synchronize offline robots.

An update file can be downloaded from the device detail page in the "SYNCHRONIZE" dialog. After clicking the corresponding button, a device-specific file named like update-290839-2413422-2020-09-08-12-53-59 is saved to your computer. This file needs to be transported to the robot, either by taking your pc there or by uploading the file from a computer connected to the robot.

sync-offline-robot.png

Figure 21: Instructions at the robot to synchronize when offline.

In the Settings > Franka World page of the robot user interface, update files can be uploaded via the "USE UPDATE FILE" button. This is also needs to be done as last step within the offline registration process. Using an update file is very similar to downloading changes when the device is online, such that new & updated apps as well as software marked for removal is pending and needs to be "APPLY"-ed afterwards.

Important: After applying the changes of an update file, older update files cannot be used anymore. This is necessary to be able to move apps from one robot to another.

As a final step, a status file needs to be transported the other way from the robot to Franka World to report back on newly installed or removed Apps & Features. Status files are named like status-295341--0000003-2020-09-08-15-04-31 and can be uploaded into the synchronization dialog of the device's detail page. A status file needs to be retrieved and uploaded to Franka World whenever licensese are in "removal pending" or the world needs to know about the current robot state, e.g. that no apps are installed after a factory reset to get an update file to reinstall apps.

5 Browsing and ordering in the Store

The Franka World comes with an online store where you can buy more robots, selected end-effectors and most importantly software extensions, so-called Features, and of course Apps for your robots.

Important: Ordering through the online store is currently only available for customers in the European Economic Area, Switzerland, Liechtenstein and Norway. However, placing orders through sales@franka.de is possible worldwide.

In the Store > All products area, you will find the full list of available or "coming soon" products, which you can sort or filter using the "Search products" input field. While the full product listing page (PLP) will give you an overview, clicking on any entry will take you to the corresponding product's detail page (PDP). Here you will find a detailed description, videos and images showcasing the product.

plp-search.png

Figure 22: Product listing page filtered using the search input.

Pressing "ADD TO CART" on either the PLP or any of the PDPs, will add the product with selected quantity to your cart. The cart is not shared between users and also unique per account, so make sure you have selected the right account before filling your cart.

When progressing to the checkout, either by clicking on the notification or anytime in the navigation Store > Cart, you are first asked to fill in your billing address if not already set. An account's billing address can be set and edited until verified by FE staff on the account details page. The same billing address will be used on any order placed by this account. The shipping address to be used however, can be either changed in the account details or on the checkout page. When done in the checkout, the shipping address details are only used for this particular order and changes can be reset to account defaults using "DISCARD CHANGES" on the left side.

checkout.png

Figure 23: Full example of a filled checkout page.

Note to partners only: While the shipping address describes the place where hardware is to be delivered, the shipping account defines which Franka World account receives ordered software licenses. As a partner, you can order software which is to be delivered to your client's Franka World account by entering a Franka World ID and thus changing the shipping account here. The picked account will see this order in their order history without price information and receive the software licenses upon delivery.

On the checkout page you can also find some more fields to specify your own, external reference for this order, as well as any additional information you want to pass on to Franka Emika when placing this order. Also you can pick from available payment and shipping options.

Note: Currently only pre-payment is selectable as a payment option, even though you might have done business with us in the past and are eligible for payment by invoice. This is a temporary technical issue and you are welcome to let our employes know via the additional notes field.

At the bottom you can review the order contents and change quantity or remove positions as needed. When you also have read and accept our terms and conditions we are happy to receive and review your order. After placing it, you can see the status of this and previous orders in your account's Store > Order History page.

6 Product management (partners only)

As an app developing partner in Franka World, your account is unlocked to create new App products. An app product is basically extending one or more app bundles with presentational and sales related information, while the app bundle is the actual artifact holding the robot program(s) and gets deployed onto your or your clients robots. This means with app products you can make single apps purchasable on Franka World, create packages of all your developed apps as a single license, or simply ready-up your app bundles for individual distribution as "private" app products.

Note: You will eventually be able to also manage App bundles of your partner account as soon as we have the tooling ready for preparing app bundles for Franka World. Until then, new or updated app bundles need to be prepared and uploaded by FE admins. Contact products@franka.de if you have new or updated app bundles.

When unlocked, you can list an account's app products in Manage > App Products. This list shows already some important information about products in the overview. Simply clicking on the entry takes you to a preview of the possibly modified product, while the pen icon on the right will open the product edit page. Using the top right button "CREATE APP PRODUCT" you can create and directly edit a new product in Unpublished state.

manage-products.png

Figure 24: Part of the Franka Emika product list with private and public products.

6.1 Product status

A product can be in one of three different states:

  • Unpublished: Initial state which allows free editing and the product is only visible to the creator.
  • Published: Verified product where changes are tracked and require approval. If the "private" property is not set, this product is visible in the public Store > All Products list.
  • Modified: The product is Published, but there are staged changes which require confirmation. Until then, the staged version can be previewed.

Furthermore, only published app products can be delivered as licenses, but once in an inventory / in use on a robot, the product status has no effect on license usage. This means, after creating a new product or when changing an already Published product (making it Modified), you need to request publishing when you want your changes to come into effect. For this, contact products@franka.de.

Besides the publishing status, there are two more important properties which define a product's availability:

  • coming soon: Instead of specifying a price, a product can be marked as "coming soon" to have it listed without a price and thus not orderable.
  • private: Products marked as "private" can still be used to create licenses, but they are only visible in the Manage > Products list, not in the Store > All Products PLP. This feature is intended for so-called "custom" apps, where an app developer wants to develop / deliver highly specialised apps to individual clients.

6.2 Included Apps

Other than, every app product is required to have a name and needs to include one or more app bundles. The latter defines what's "in" the product and may list any numer of app bundles from your account. Note that dependencies are handled automatically, so the resulting number of apps might be higher, e.g. if your picked app bundle requires another App to be installed as dependency.

Note: Should "Select App Bundle" drop down list be empty, we need to add your app bundles first to your account. As this currently can only be done by FE admins, contact products@franka.de if you have new or updated app bundles.

manage-products-edit.png

Figure 25: Fully filled edit product page including a linked video and description HTML markup (boilerplate).

6.3 Media and description

To present an app product throughout Franka World, you can add a product image, several gallery images, link youtube videos and provide a product description. If you want your app to be publicly listed and purchasable, most of these things are required or at least recommended.

The main product image is used whenever we show your product and should serve as the main identifying icon of your app (package). PNG or JPG are supported and it should have a square 1:1 aspect ratio with a minimum of 128x128 pixels resolution. If you have a single app product, we can generate this image also from the app bundle on your request.

If specified, added images and linked videos will be contained in a gallery "carousel" on the product detail page. These media is commonly used to demonstrate use of the app and/or show how to teach it. The aspect ratio of the gallery is 16:9 and images, as well as video is recommended to be full HD (1920x1080). PNG or JPG formats are supported for images, and videos need to be hosted on youtube, but can be private/unlisted - simply provide the video id or youtube link.

Finally, the product description is shown on the PDP to desribe the product in detail. The input field takes directly HTML markup and thus common "typography" elements like sections <section>, paragraphs <p>, headlines <h5>, etc. can be used. As for content, typical sections are a description of functionality, whats contained (for packages of multiple apps), the teaching workflow, example use cases and limitations. Just have a look at other products.

Note: All product descriptions currently require a template to be used for some basic styling "resets" and the developer information section. Please use this as a starting point and fill in your company details:

<div class="fe-description">
  <style>
   .fe-description {
     line-height: 1.5;
     font-weight: 300;
     font-size: 18px;
   }
   .fe-description section {
     margin-bottom: 30px;
   }
  </style>

  <section>
    <p>...Some intro text, followed by more sections and paragraphs if desired..</p>
  </section>

  <section>
    <h5>Teaching workflow</h5>
    <p>...one of the common sections describing your app...</p>
  </section>

  <section>
    <h5>Developer information</h5>
    <b>Franka Emika GmbH</b>
    <p>
      Frei-Otto-Straße 20<br/>
      DE-80797 München<br/>
      <a href="https://www.franka.de/" target="_blank" >www.franka.de</a>
    </p>
  </section>
</div>

7 Getting Help

We try to keep this manual up-to-date with the current version of Franka World. If you need further assistance, are missing something or find any mistakes please don't hesitate to contact our Support (support@franka.de).

Author: Sebastian Nagel

Created: 2020-10-08 Thu 12:05