AWS Setup

This guide assumes that you already have an AWS account, and have Foundry installed on it. If you do not, please refer to the setup guide found here.

Download the machine learning cloud formation template here
Log on to your AWS account. On the upper toolbar, click on services, and then CloudFormation.
Click on the "Create Stack" button. Under "Choose a template", upload the machine learning template that was just downloaded, and click "Next"
Specify the stack name as "MachineLearning". Under parameters, set Environment to be "dev". The foundry account id is the id number of the user account in foundry. To find this number, carry out the following steps:
1. Log on to your Foundry account here
2. On the left toolbar, click "Setup" and then "Accounts"
  - Note: the accounts tab may be under a different menu item, depending on your personal configuration. the format shown in this demo refers to the default Foundry configuration
3. Find your account name on the list shown, and click the info icon as shown in the picture below.
4. Look at the URL shown in your web browser. Everything after "subAccount=" is the account id, as shown in the image below. Copy this id. Navigate back to AWS CloudFormation, and paste this id into the parameters box labeled "FoundryAccountId"
The two parameters "FoundryApiid" and "FoundryRootResourceId" are found on your AWS account. To find them, complete the following steps:
1. Log in to your AWS account, by either navigating to the dashboard or by following the link here
2. Click the "Services" drop down menu, and search for and select "API Gateway"
3. You will see a list of the current APIs available to you. If you do not see any listed, make sure that the region in the top right corner of the window is set to "Oregon", or "us-west-2".
4. Select the API named FoundryCustomerSideV2Dev, and then "Resources".
5. A list of the API methods will be shown. Click the method named "/foundry". The two needed id's will be shown. Refer to the image below to find them.
Click the "Next" button on the current window. The next window will have three "Options" sections: "Tags", "Permissions", and "Advanced" Leave these three blank, and click "Next".
On this final window, scroll to the bottom of the window and check the box that is labeled "I acknowledge that AWS CloudFormation might create IAM resources" and click "Create".
You will be brought back to the CloudFormation dashboard screen. You should see your machine learning stack being created, with the status of "CREATE_IN_PROGRESS". After a few minutes, refresh the page and verify that the status has changed to "CREATE_COMPLETE". Once this has been done, the machine learning capability has been installed on your Foundry account.

Machine Learning Usage Guide

After the necessary programs have been installed to a Foundry account, objects can now be tagged for machine learning. Machine learning has to be enabled for user specified device types on a Foundry account. The user makes a control panel object, which displays information about the machine learning model, and is used to make predictions with and update the existing machine learning model.

Create a Control Panel Object

To create and control the machine learning model, a control panel object must be created. There is a user interface that will help you add the necessary attributes to this model.

Navigate to the machine learning page, either through the menu side bar, or by following this link
Select your account from the "Account Name" dropdown menu. You will now see more fields become available on the page. The required fields are:
1. Object Type: the object type of the devices that you would like to enable machine learning on.
2. Control Object Name: the name that the resulting control panel object will be called. Name it something descriptive, so you can easily manage multiple models if needed.
3. S3 Bucket Name: the name of the s3 bucket that the machine learning data files will be stored in. If you would like to access them in the future, they are stored under the filepath /machineLearningModels/year/month/day/timestamp/
4. Target Attribute: the attribute whose value is to be predicted by machine learning
5. Data Type: the data type of the target attribute. This will be one of the following three options:
  1. NUMERIC: the target attribute's value is a number
  2. BINARY: the target attribute's value is either 1 or 0, yes or no, or true or false
  3. CATEGORICAL: the target attribute's value falls into preset categories
6. Prediction Type: specifies the type of value the resulting machine learning prediction will be. The options are:
  1. REGRESSION: the prediction value is a number. Must be paired with a target data type of "NUMERIC"
  2. BINARY: the prediction value is a binary output, 1 for "true" and 0 for "false". Must be paired with a target data type of "BINARY".
  3. MULTICLASS: the prediction value falls into preset categories. These categories are the same categories the target attribute falls into. Must be paired with a target data type of "CATEGORICAL" or "BINARY"
Below the six data entry fields, a list named "Available Attributes" is shown. This list has every attribute type that the previously specified object type has. Select the attributes whose values are to be used to train the machine learning model to form predictions. These attributes will not have their values predicted by machine learning. Machine learning uses these current values initially to build the prediction model. Every time a prediction is made in the future, machine learning will receive these values from the specified object and use them as the basis for its outgoing prediction.
1. Select the right arrow for any attribute that you want to include in the model. The attribute will be added to a separate list on the right. If a attribute was selected by mistake, click the left arrow to undo the action. You can also search for attributes using the included search bar.
2. For each attribute added, its data type must be specified using the drop down menu next to each attribute on the right side list. The available data types are:
  1. NUMERIC: the attribute's value is a number
  2. BINARY: the attribute's value is either 1 or 0, yes or no, or true or false
  3. CATEGORICAL: the attribute's value falls into preset categories
  4. TEXT: the attribute's value is text
A fully filled out example of this page can be see in the image below. When all the previous fields have been filled out, click "Create Machine Learning Model". If all the parameters were correct, the message "Machine learning model creation initiated!" should appear below the button. If an error occurred, an error message will appear instead.

When the successful message appears, the machine learning control panel object will have been created. Using this object, you are able to view what device type this model is made on. This object is a group, so all the devices that are part of this model will be shown under "Object List". The attributes used to build this model are also listed under the "Attributes" tab, as well as the target attribute and prediction type. When this obect was created, the machine learning model training process was automatically started. This can take around ten minutes to complete, depending on how large the data set is. Machine learning models are made in two phases: the data source creation, and the model training process. Both can be monitored by viewing the "Data Source Status" and "Model Status" attributes. They will progress from "PENDING" to "IN PROGRESS" to "COMPLETED". The data source has to fully complete creation before the model will start. The data source and model ids are both listed, so if there is an error in the creation of either, you can navigate to the machine learning page in AWS and view the error message. The model will be fully complete once the attribute "Model Status" reads "COMPLETED".

Using the Control Panel Group

Before predictions can be made, the model's live prediction endpoint must be enabled. This is done through a global action. To do so, navigate to the search page through Foundry's menu side bar, or by following this link
Search for the control panel object by selecting "typeId" from the drop down menu titled "Object Type Attribute Fields", and select the control panel object type from the "Enter Value" drop down. the control panel object type will be named " - ML Control Panel. For example, if the object type being predicted on is "Heaters", the control panel type will be called "Heaters - ML Control Panel". Click "Add Search Criterion", and then "Search". This search configuration is shown in the image below.
The endpoint is enabled by invoking a global action on the control panel object. Select the checkbox next to your control panel. On the drop down labeled "Action", select "Lambda Invoke", and under the "Type" pick list, select "Enable Machine Learning Endpoint". The configuration can be seen in the image below. Click "Send Now".
After the action is sent, the endpoint takes about one minute to update. To track its progress, go to the control panel object and look at the attribute "Endpoint Status". It will progress from "UPDATING" to "READY". After the endpoint is ready, the model is available to make predictions. If the endpoint ever needs to be disabled, invoke the action "Disable Machine Learning Endpoint". The endpoint can be re-enabled at any time.
To update the objects' predictions, return to the search window. Select the control panel object from the search results, and this time set the "Type" pick list to be "Update ML Prediction". Sending this action will make a new prediction for all of the devices used to make this model, and write that prediction back to each object. This action can be scheduled to run on an interval. To do so, instead of clicking "Send Now", click "Schedule". Choose the date and time of the first desired invocation, and then check the "Recurring" box. Choose the desired invocation interval, and click "Save Schedule". The configuration can look similar to the one shown in the image below.
Each prediction will be stored on its source object, in a field titled as the name of the attribute, plus the word " Prediction". For example, if the target attribute is called "Error Chance", then the prediction will be stored in an attribute titled "Error Chance - Prediction".