Samsung IoT Cloud

It can take it

Overview

This is a hands-on narrated tour on how to make use of Samsung’s IoT cloud.

It helps if you have already absorbed the tutorial about IoT ideas.

I want you to feel confident that you’ve mastered this skill. That’s why this takes a hands-on approach where you type in commands and we explain the responses and possible troubleshooting. This is a “deep dive” because all details are presented.

Like a good music DJ, I’ve carefully arranged the presentation of concepts into a sequence for easy learning, so you don’t have to spend as much time as me making sense of the flood of material around this subject.

Sentences that begin with PROTIP are a high point of this website to point out wisdom and advice from experience. NOTE point out observations that many miss. Search for them if you only want “TL;DR” (Too Long Didn’t Read) highlights.

Stuck? Contact me and I or one of my friends will help you.

Explore

In an internet browser, look at the various businesses described at
https://www.artik.io/overview
- Samsung’s modules (IoT device hardware)
- Samsung’s TIZEN operating system
- IoTivity communications
- Samsung’s ARTIK Cloud, which Samsung calls an “open data exchange platform that enables any device or sensor to push its data to the cloud”.
QUESTION: What does ARTIK stand for? It’s rebranded from SAMI in 2016.
In a new tab/window, look at Samsung’s home product page:
https://artik.cloud
Click PRICING to see that Hobbyists get free access, but data is kept only 3 months.

PROTIP: Part of the design and task of any system is analytics over time. Many organizations extract the information for display using Tableau or other corporate-standard analytics tool to more easily integrate other corporate data into a single “pane of glass” common among Marketing, Finance, Operations, etc.
Click SIGN-UP and type your email to get their newsletters.
Click DEVELOPER on the right side of the menus for
https://developer.artik.cloud
https://developer.artik.io/documentation/tutorials/
artik.io/blog/cloud has lots of great articles about applications.

The above you only need to do once.

Samsung projects

demo on hackster.io

Samsung’s Challenge sends winning participants $100

Add Samsung device type

You need to do this for each type of device you use.

If you select DASHBOARD > DEVICE TYPES from the website, you get to click another button to really add NEW DEVICE TYPE at
https://developer.artik.cloud/dashboard/devicetypes/new

This is for adding types of devices.

There is also a list at
https://artik.cloud/works-with

The wish list of device types to include:
https://artik.cloud/challenge/most-wanted-devices
To select a known device type, open a new tab/window at
https://artik.cloud/my/new_device
to look at the many device types ARTIK already supports.

QUESTION: Is there a menu from the website that takes you here?
Scroll to select SAMI Gear Fit.

The device is used in
https://developer.artik.cloud/documentation/introduction/hello-world.html
which steps you through connecting a “SAMI Gear Fit” type device even though one doesn’t need a physical device.
PROTIP: Add a number in the name suggested. You may have more than one, or want different variations later.
Click CONNECT DEVICE…

This takes you to
https://artik.cloud/my/devices

Samsung API console
Open yet another tab/window
https://developer.artik.cloud/api-console
PROTIP: You’ll come back to this often, so bookmark it on your browser.

Click “Accept” to allow Samsung the permissions listed:

The application API Console is requesting the following permissions to be granted:
 
Read all your data.
Write and modify all your data.
Read data from devices of types:
Send data to devices of types:
Read your profile information
Internal use only. Edit your profile information

Click “Accept” to dismiss the cookie message at the bottom.

API List in SDKs

The Java/Android SDK has these classes making API calls:
- DeviceTypes of manifests with versions and properties
- Devices have their tokens
- Export of messages
- Messages
- Registrations
- Rules
- Tags
- Tokens
- Users and their devices and device types and properties
For example, “UsersApi.java” is equivalent to “users_api.py” in Python. Swift, Scala, Ruby, PHP, C#, JavaScript, etc. have their own variation of name.

Additional classes in the Console but not in client samples:
- notifications by subscription
- trials for applications
- trial devices and devicetypes
- trial invitations to participants by administrators
- scenarios ???
- manifests are used to interpret the content so that it can be stored properly, or be sent to targeted devices correctly. Libraries of manifest models:
- import cloud.artik.model.ManifestVersionsEnvelope;
- import cloud.artik.model.DeviceTypeEnvelope;
- import cloud.artik.model.DeviceTypesEnvelope;
- import cloud.artik.model.ManifestPropertiesEnvelope;
The libraries that operate on the classes in the Java SDK are:
- import cloud.artik.client.ApiCallback;
- import cloud.artik.client.ApiClient;
- import cloud.artik.client.ApiException;
- import cloud.artik.client.ApiResponse;
- import cloud.artik.client.Configuration;
- import cloud.artik.client.Pair;
- import cloud.artik.client.ProgressRequestBody;
- import cloud.artik.client.ProgressResponseBody;
A full description of Samsung’s REST API is here.

Swagger definitions are supposed to be at
https://catalog.artik.cloud but there is a 503 error at time of writing.

API Map

Let me know if this artwork helps you visualize Samsung’s API:

Words in bold are the first level names in the path. Words in italics are variables.

TODO: Create illustration programmatically using http://apispots.com/projects/swaggered/

Get Samsung user access token

Click the “GET” associated with /users/self.

Service end-point
Click TRY IT! button for the website to issue a request using the API endpoint shown:
```
https://api.artik.cloud/v1.1/users/self
```
BTW, there are other end-points for other protocols:
```
COAP://
MQTT:
```
TROUBLESHOOTING: If you get the following message, it means you need to login again:
```
{"error":{"code":401,"message":"Please provide a valid authorization header"}}
```
The request’s HTTP header contains the OAuth2 calculated by the client JavaScript:
```
"Content-Type": "application/json",
"Authorization": "Bearer 471dd09f20f140888a650f3aeec70xxx"
```
The docs say messages sent to ARTIK Cloud may not be bigger than 1 KB.

QUESTION: How long does the 32-character token live?

A access token can be used (refreshed) for up to 14 days.

The response HTTP header:
```
{
 "allow": "*",
 "content-type": "application/json; charset=utf-8",
 "x-rate-limit-limit": "100/1000",
 "x-rate-limit-reset": "1472315008/1472342400",
 "x-rate-limit-remaining": "99/999",
 "access-control-allow-origin": "*",
 "access-control-allow-headers": "Origin, X-Requested-With, Content-Type, Accept, Referer, User-Agent, Authorization",
 "access-control-allow-methods": "POST, GET, PUT, DELETE, OPTIONS",
 "date": "Sat, 27 Aug 2016 16:22:28 GMT",
 "content-length": "249",
 "connection": "close"
 }
```
PROTIP: Have your client read the “x-rate-limit-remaining”: (“99/999”) and not send more traffic if it’s down to zero.

THANK YOU Samsung. Many other API services do not have this useful feature.

userId

The response HTTP body reflects information about the user:
```
{
 "data": {
     "id": "075fddff2a984cda87f2d718f4d04xxx",
     "name": "sa4fb30b78564a73884af4e03dcc40xx",
     "email": "wilsonmar@gmail.com",
     "fullName": "WILSON MAR",
     "saIdentity": "pigg1dynic",
     "accountType": "SAMSUNG",
     "createdOn": 1470056152000,
     "modifiedOn": 1470056152000
 }
}
```
The “createdOn” and “modifiedOn” are the number of milliseconds since 1/1/1970 (the epoch). The last 3 of the 13 digits are always zeros.

PROTIP: Convert back to human-readable date/time using the online tool at http://www.epochconverter.com

PROTIP: The userId is a persistent value. Once assigned, it is not changed. The system’s reference to the userId enables the user fullName to change.
Highlight the id’s value from the response for use later in this tutorial.

Developers working on API client code would copy the id to a properties file such as the one in folder src/test/resources/artik.properties
```
user1.id=04ddbd35d57d4d7b8f07f219c44457b2
user1.name=maneesh
user1.fullname=Maneesh Sahu
user1.token=fa460261b858484583097ecb331faaa8
user1.email=maneesh.sahu@ssi.samsung.com
user1.aid=b6951bf387b84f63b38911ae35d65e28
user1.createdon=1406839290000
```
The same file also contains id and tokens for each device.

BLAH: Samsung’s API does not make use of the “HATEOS” pattern, which returns with each request a list of calls next permissible.

Samsung User Properties
Highlight and copy into your Clipboard (with Ctrl+C) the value of “id” (“075fddff2a984cda87f2d718f4d04xxx” in the example above).

This is what the API calls your userId.

The application ID is specified in the JSON payload.

Samsung’s own IoT Device modules

Samsung manufacturers IoT devices sold online by electronics distributor Digikey

The $150 ARTIK 10’s quad-core ARM video and image processors are powerful enough for autonomous vehicle navigation, intensive 3D graphics or large immersive displays. All in a form factor of 29 x 39 x 1.3 mm. More importantly, its hardware works with the ARM TrustZone® and Trustonic’s Trusted Execution Environment (TEE) to provide “bank level” security end-to-end for 5GHz WiFi 802.11a/b/g/n/ac, Bluetooth 4.1 + LE, ZWave, and ZigBee 802.15.4 Thread planned radios.

(No snooping the snoopers for you!)

The $99 ARTIK 5 has the same radios, but in a 30 x 25 mm footprint.

Ships with Fedora 22.

https://developer.artik.io/documentation/getting-started-beta/
https://vimeo.com/151092340?from=outro-embed
https://www.hackster.io/stephanick/let-s-get-started-the-artik-5-beta-development-board-14f458

The devices Samsung offers have a microphone and speaker port, so make it speak.
https://www.youtube.com/watch?v=Wsj9pZml_18 Introduction to Eclipse Che: Customizable, RESTful Developer Workspaces Eclipse Foundation
OpenHAB.org platform for Home Automation

Samsung Device Simulator

Docs about this is here.

Make sure you have Java JDK v8 update 77 or higher. In a Terminal shell window:

java -version

The response (30 Aug 2016):
```
java version "1.8.0_102"
Java(TM) SE Runtime Environment (build 1.8.0_102-b14)
Java HotSpot(TM) 64-Bit Server VM (build 25.102-b14, mixed mode)
```
Upgrade if necessary. See my Java install on Mac tutorial.
Download Samsung’s Device Simulator Java program from
https://developer.artik.cloud/documentation/downloads/device-simulator.jar
into your Downloads folder.
Open a new Terminal window, navigate to the Downloads folder to construct the command:

cd ~/Downloads java -jar device-simulator.jar -token=

Temporarily return to the API webpage to copy and paste the 32-character user id token highlighted earlier.

PROTIP: Move the jar file to a separate folder and create a shell script to do this if you’ll be doing this.

TROUBLESHOOTING: If you get the message “Error: Unable to access jarfile device-simulator.jar”, do a pwd to see if the jar file is there to use.

The response begins with this ASCII art:

 _         _   _ _  __   ____ _                 _ 
/ \   _ __| |_(_) |/ /  / ___| | ___  _   _  __| |
  / _ \ | '__| __| | ' /  | |   | |/ _ \| | | |/ _` |
 / ___ \| |  | |_| | . \  | |___| | (_) | |_| | (_| |
/_/   \_\_|   \__|_|_|\_\  \____|_|\___/ \__,_|\__,_|
Welcome to ArtiK Cloud Device Simulator console

An example of the rest of the response:

Hello sa4fb30b78564a73884af4e03dcc40xx! your UID is 075fddff2a984cda87f2d718f4d04xxx and your email is wilsonmar@gmail.com :)
Please enter a valid command or ? for help.
java.io.UnsupportedEncodingException: utf-
  at sun.nio.cs.StreamEncoder.forOutputStreamWriter(StreamEncoder.java:61)
  at java.io.OutputStreamWriter.<init>(OutputStreamWriter.java:100)
  at jline.console.ConsoleReader.<init>(ConsoleReader.java:231)
  at jline.console.ConsoleReader.<init>(ConsoleReader.java:221)
  at jline.console.ConsoleReader.<init>(ConsoleReader.java:209)
  at simulator.Console.init(Console.java:64)
  at simulator.Main.main(Main.java:14)

QUESTION: If the “data: id” token was entered, the response is:

cloud.artik.client.ApiException: Unauthorized
  at cloud.artik.client.ApiClient.handleResponse(ApiClient.java:838)
  at cloud.artik.client.ApiClient.execute(ApiClient.java:773)
  at cloud.artik.api.UsersApi.getSelfWithHttpInfo(UsersApi.java:115)
  at cloud.artik.api.UsersApi.getSelf(UsersApi.java:102)
  at simulator.Console.whoami(Console.java:203)
  at simulator.Console.init(Console.java:59)
  at simulator.Main.main(Main.java:14)
The access token is not valid or expired.
Please enter a valid command or ? for help.
java.io.UnsupportedEncodingException: utf-
  at sun.nio.cs.StreamEncoder.forOutputStreamWriter(StreamEncoder.java:61)
  at java.io.OutputStreamWriter.<init>(OutputStreamWriter.java:100)
  at jline.console.ConsoleReader.<init>(ConsoleReader.java:231)
  at jline.console.ConsoleReader.<init>(ConsoleReader.java:221)
  at jline.console.ConsoleReader.<init>(ConsoleReader.java:209)
  at simulator.Console.init(Console.java:64)
  at simulator.Main.main(Main.java:14)

Device Emulator commands

If successful, commands can be entered.

?

Samsung cloud connectors

At time of writing, the clouds at https://artik.cloud/works-with/ include most of the early cloud APIs:

OpenWeatherMap
Nettamo (France) elegant indoor face recognition cameras and CO2 sensor stations
Twitter
Foursquare
Instagram ?
FitBit
iHealth
Jawbone
Moves
Runkeeper
Withings.com smartwatches and scales
Nest Thomstate (Google)
Philips Hue

https://developer.artik.cloud/documentation/introduction/authentication.html#authorization-code-method

### OpenWeatherMap #

https://www.artik.io/blog/2016/08/make-iot-weather-station-artik-cloud/ using an Arduino Uno running Sketch collecting from a DHT11 Temperature sensor and a Raspberry Pi running Node.js.

Rules

Trials

An ARTIK Cloud trial is a way for a trial administrator (user) to invite other users to share their data for a controlled amount of time and set of device types.

https://github.com/samsungsamiio/sami-trials-webapps by http://developer.samsungsami.io/ now redirects to https://developer.artik.cloud/

Docs about this are under the “Advanced” section.

View charts

Check it out

Export from ARTIK

Check it out

Twitter: @ARTIKCLoud, @SamsungIoT,

Email: developer@artik.cloud
answered by Developer Evangelists
Jeanine (Swatton) Jue of the Samsung Strategy and Innovation Center.

LinkedIn jobs shows Samsung America being based in Seattle and Bellevue, Washington. Smart Home in Mountain View, California. Home Appliances in Rigefield Park, New Jersey and Minneapolis, Minnesota.

artik.io/blog/cloud is the user forum.
https://github.com/artikcloud/sample-iot-weatherstation

Dan Gross, Director of Technical Support, Samsung

Wei Xiao, Tech Evangelist, Sr. Staff Engineer, Samsung

More on IoT

This is one of a series on IoT:

NOTE: Pages about GE’s Predix have been removed.

Wilson Mar

Samsung IoT Cloud

Explore

Samsung projects

Add Samsung device type

Samsung API console

API List in SDKs

API Map

Get Samsung user access token

Service end-point

userId

Samsung User Properties