ArchFX Cloud Tutorial: Getting Machine Data via API

 Topics covered in this article:

1. Introduction
2. ArchFX Cloud API Basics
    2.1 Example: Curl command to login
    2.2 Browsable API
    2.3 Basic Database Models
    2.4 Arch IDs or Slugs
3. How to get factory machine data?

1. Introduction

The ArchFX Cloud has an extensive Restful API that give the user access to every database record. The ArchFX WebApp is 100% driven by this API. Therefore, any information that the user sees on the Web App can be extracted via an API call. But the fact is that the Web App only accesses a small (but important) set of API calls.

This document will focus on how to easily access stream data, which is the raw data that comes directly from Arch PODs or any ArchFX Broker Connector. This document will also show how to access the higher level Global KPI aggregations.

With this document, a user can either get raw data and compute its own KPIs, and send to a different system, or it can access the computed Global KPIs (e.g. OEE, LU, etc.). This document is not intended to give a complete view of everything that is possible via the API, but simply to give a basic set of examples for how to get factory machine data.

Note that within this document, each time we refer to "https://arch.archfx.io" you should replace "arch" with whatever your specific ArchFX Cloud company domain is, usually something like" https://your-company.archfx.io"

2. ArchFX Cloud API Basics

The ArchFX Cloud API uses JWT tokens to authenticate, so the first thing to learn is how to authenticate. The following API call can be use to authenticate:

POST: https://arch.archfx.io/api/v1/auth/api-jwt-auth/

PAYLOAD: application/json
{
"username": "email",
"password": "string"
}

This API call will respond with a token, which you will need to use for all subsequent API calls described in this document. You will add the following to your API header:

'Authorization': 'JWT ' + _token_you_just_got
'Content-Type': 'application/json'

2.1 Example: Curl command to login 

$ curl https://arch.archfx.io/api/v1/auth/api-jwt-auth/ -d username=joe@acme.com -d password=secret
{"token":"very.big.token"}

$ curl -X GET https://arch.archfx.io/api/v1/org/ -H 'Authorization: JWT very.big.token'
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "email": "joe@acme.com",
            "username": "joe",
            "name": "I am a user",
            "avatar": {
                "tiny": "https://secure.gravatar.com/avatar/...",
                "thumbnail": "https://secure.gravatar.com/avatar/...",
                "medium": "https://secure.gravatar.com/avatar/..."
             },
             "slug": "joe",
             "is_staff": false
         }
     ]
}

2.2 Browsable API

For debugging and learning what each API can do, ArchFX Cloud has a browsable API which allows you to:

• copy and paste any GET API call on the browser to see results (assuming you are logged on into your account), or to
• browse the API

Just go to https://arch.archfx.io/api/docs/ to browse the API. (Note that not all API calls are displayed.)

2.3 Basic Database Models

At the highest level, ArchFX Cloud is based on the following database models:

• A User is a member of one or more Organizations (or Orgs)
• An Org has a number of Sites usually representing geographical company sites
• A Site contains a number of Areas or Lines
• A Line represents an assembly line, and has a sequence of Machines building one or more products.
• An Area represents either a group of Lines or a group of Machines (if the machines are not part of an actual assembly line).
• Machines have data grouped in Streams.
• Each Stream represents time-series data from a given sensor or connector for a given machine. Streams are represented with a Variable ID that represents the type of data the stream stores. For example, a machine product_ready signal uses 5051 as its variable ID.

2.4 Arch IDs or Slugs

The ArchFX Cloud uses the concept of globally unique Arch IDs as a way to represent most critical records (i.e. they are the primary keys on the database). This unique Arch IDs (also known as Slugs within the documentation). An experienced user can tell what type of record a slug represents by just looking at the first few characters. The following shows the basic prefixes for each of the records used in this document:

• Sites: Factory sites are represented with a ps-- (e.g. ps--0000-0001)
• Areas: Factory areas within a site are represented with a pa-- (e.g. pa--0000-0001)
• Lines: Factory lines within an area (or within a site) are represented with a pl-- (e.g. pl--0000-0001)
• Machines: Factory machines are represented with a d-- (e.g. d--0000-0001-0000-1234). Note that d-- is also used to represent a Device (which represent Arch PODs or ArchFX Connectors), but devices always use d--0000-0000-. We won't talk about devices in this document.
• Streams: Machine data streams are represented by building a slug based on the machine's parent (area or line), the machine itself, and a variable ID representing the type of data. Streams are represented with sa-- (for an area stream) or sl-- (for a line stream). e.g. sl--0000-0001--0000-0001-0000-1234-5051).

 So, if we want to get details for a particular site (e.g. ps--0000-0123), we would use the following API:

GET: https://arch.archfx.io/api/v1/site/ps--0000-0123/

For a machine, we would use:

GET: https://arch.archfx.io/api/v1/machine/d--0000-0001-0000-1234/

There is also a useful universal API to get any record based on its slug, regardless of type:

GET: https://arch.archfx.io/api/v1/util/obj/ps--0000-0123/
GET: https://arch.archfx.io/api/v1/util/obj/d--0000-0001-0000-1234/

3. How to get factory machine data?

ArchFX Cloud uses the concept of DataViews to group different data into a combined table. A DataView is equivalent to a worksheet in an Excel spreadsheet. For something as simple as OEE or LU calculations, this DataView may only have a single column with the machine "product_ready" signal, which represents when a unit is built by the given machine.

When machines are grouped into a factory line or factory area, the concept of DataViews is still used to output data for all machines in that line or area. In this case, an additional column is added to represent the machine that is outputting the data.

For OEE and LU calculations, the following DataView names are available:

• Lines have an oee-line-view which groups all data in 15min buckets (to reduce the amount of data returned)
• Areas have an oee-area-view which groups all data in 15min buckets (to reduce the amount of data returned)
• Machines have an oee-view which groups all data in 15min buckets (to reduce the amount of data returned)

Given a DataView name, you can access the data using the following URL:

<sub-domain>.archfx.io/api/v1/data/df/?view=<view>&target=<arch id>&start=<start>&end=<end>&format=<format>

where:

• sub-domain is the specific server subdomain associated with your company, or "arch" if you are using the general purpose Arch Server.
• view is one of the DataView names described above.
• arch_id is the ID for the Area, Line or Machine you want to get data from. You can get this ID from multiple places. Usually referred to as "Arch ID", "Slug" or as part of the page URL (e.g. "domain/org/org-name/machine/d--0000-0001-0000-1234" where the Machine Arch ID is "d--0000-0001-0000-1234"). The Machine Arch ID always starts with "d--" while the Area start with "pa--" and the Line with "pl--".
• start is the start time for the time range you want to get data for. This time is in UTC and requires a string in the form of "2020-01-01T10:00:00Z".
• end is the end time for the time range you want to get data for. This time is in UTC and requires a string in the form of "2020-01-01T10:00:00Z".
• format is the return payload format. The options are "csv" (the default), "json", or "txt". Note that this is an API call, intended to be called from a script, so it was not intended to be used from a browser. The "json" and "txt" formats always work from a browser, but depending on your browser, the "csv" may work in different ways (for example, Google Chrome will not show any error messages). If you want to download a CSV from the browser, it is recommended you use "format=txt" and then use the browser's "Save As" menu option to save as a "your-filename.csv".

The CSV will be formatted with the following columns

• row contains the timestamp for the reading (or if grouped, the time of the grouping)
• device represents the Machine Arch ID. You can copy and paste this ID to any of the search bars in archfx.io or app.archfx.io to get information about that machine. Or you can also use the <subdomain>.archfx.io/api/v1/machine/ API to get a list of machines in your Organization.
• The rest of the columns represent data for that target based on the given area, line or machine type and the DataView you use.

The following is an example of a what you get on an SMT Line with a PnP and AOI connector.

This same API call can be called from a script or using a utility like "curl". See How to authenticate via the API to learn how to get the required JWT token to access this API call.