smart-events

An unofficial SmartThings websocket API library (alpha)

💾 Installation

This is a Node.js module available through the
npm registry.

$ npm i -S smart-events

🔌 Quick Start

``javascript
const EventService = require('smart-events');

const st = new EventService();

// Initiate Connection
st.connect('', '');

// Connected via Websocket
st.on('connected', data => {
console.log('Connected!', data);
st.fetchUser(); // Fetch User Info
st.fetchLocations(); // Fetch Hub Locations
st.fetchRooms(''); // Fetch Rooms @ Location
st.fetchDevices(''); // Fetch All Devices @ Location
st.subscribe(''); // Subscribe to Device Events @ Location
});

// Authenticated
st.on('authenticated', data => {
console.log('Authenticated:', data)
});

// User Info
st.on('user', data => {
console.log('User:', data);
});

// Hub Locations
st.on('locations', data => {
console.log('Locations:', data);
});

// Rooms
st.on('rooms', data => {
console.log('Rooms:', data);
});

// Devices
st.on('devices', data => {
console.log('Devices:', data);
});

// Device Events
st.on('event', data => {
console.log('Device Event:', data);
});

// Unknown message received
st.on('unknown', evt => {
console.log('Unknown Event', evt);
});

// An API error occured
st.on('error', err => {
console.log('An Error:', err);
});

`

🔮 Features

- Asynchronous event driven API
- Does not require long/short polling, webhook endpoints or a SmartApp
- Detailed location, room, device and event information
- Built in data validation (limited)
- Easy integration into other projects (custom dashboards, automations, monitoring, logging, etc)

👓 Transparency

- This is an early stage, alpha level project and may be unstable for some time
> If you would like an official library, reach out to SmartThings / Samsung, mention this project & express your interest!
- Should not be considered 'production ready' or used in critical implementations
- Subject to unpredictable changes which can break this implementation without notice
- Some security concerns & known vulnerabilities may exist and should be reviewed prior to using the package
- Needs a refactor to align to best practices and OOP principles

🛠 Setup & Getting Started

$3

> The current authentication approach has some security concerns which should be reviewed and acknowledged.

> If anyone from SmartThings / Samsung reads this, please consider adding additional authentication schemes (OAuth, bearer token, etc) for better safety & usability.

The current implementation relies on a csrfToken & session cookie from the SmartThings Web App.

In order to get that information, the following steps must be performed in Google Chrome:

1. Open the web browser and navigate to https://my.smartthings.com
2. Enter your Samsung credentials to log into the web app
3. Select the main location for which you plan on subscribing to events (it may be possible to monitor multiple locations but it has not been tested or documented)
4. Open the Settings menu and enable Keep me signed in
> Note, there is currently a bug in the UI which makes it appear as if the setting did not work (even though it did). You can confirm this worked later on via the authenticated event's output.
5. Open the Developer Tools menu in Chrome and navigate to the Network tab
6. Enable Preserve Log, select the WS filter and refresh the page
7. Open the Console tab and copy/paste the following script to copy a JS object to your clipboard
`javascript
copy({
cookie: '',
csrfToken: window._app.csrfToken,
locationId: window.location.pathname.split('/')[2]
});
`
8. Store the values somewhere secure & accessible by your code (see env.js or .env sections for general ideas)
9. Open the Network tab, select the websocket request and under Headers right click the cookie and select Copy value
10. Paste the value of the cookie somewhere secure & accessible by your code


#### env.js (optional)

This file may be created to store persistant environmental variables.

This file must be added .gitignore & never published. See security concerns for more details.

Example of storing information in this file:

`javascript
module.exports = {
cookie: 'abc123',
csrfToken: 'abc123',
locationId: 'abc123'
}
`

Example of getting information from this file:

`javascript
const {csrfToken, cookie, locationId} = require('./env.js');
console.log(csrfToken, cookie, locationId);
`

#### .env (optional)

This is a commonly used way to store persistant environmental variables.

In your code, you can use the dotenv package to access the stored values at runtime.

This file must be added .gitignore & never published. See security concerns for more details.

Example of storing information in this file:

`BASH
CSRFTOKEN=abc123
COOKIE=abc123
LOCATIONID=abc123
`

Example of getting information from this file:

`javascript
require('dotenv').config()
console.log(process.env.CSRFTOKEN, process.env.COOKIE, process.env.LOCATIONID);
`

💡 Methods

$3

- Initiates the websocket connection
- csrfToken: string
- cookie: string
- Emits the connected event

$3

- Requests information about the user
- Emits the user event

$3

- Requests the list of locations available to the user
- Emits the locations event

$3

- Requests the list of rooms at the specified location
- locationId: string
- Emits the rooms event

$3

- Requests the list of devices at the specified location
- locationId: string
- Emits the devices event

$3

- Subscribes to receive all device events at the location
- It may be possible to subscribe to events from multiple locations but it has not been tested or documented
- locationId: string
- Emits the event event for all device updates

$3

- Retrieves the user object for the specified user from memory
- principal: string

$3

- Retrieves the location object for the specified location from memory
- locationId: string

$3

- Retrieves the room object for the specified room from memory
- roomId: string

$3

- Retrieves the device object for the specified device from memory
- deviceId: string

🌐 Events

$3

- The websocket connection has been opened
`javascript
{
sid: '',
upgrades: [],
pingInterval: 25000,
pingTimeout: 5000
}
`

$3

- The server has authenticated the websocket connection

`javascript
{
userId: '',
sessionLength: 28800,
stayLoggedIn: true // Can be used to confirm the "Authentication" step in the docs was performed correctly
}
`

$3

- Provides information about the user which is authenticated
- Reminder, this information is likely sensitive and should not be shared

`javascript
{
principal: 'user_uuid:',
samsung_account_id: '',
countryCode: 'USA',
user_name: 'user_uuid:',
scope: [ 'mobile' ],
fullName: '',
access_tier: 0,
exp: 1623210310, // Unix Timestamp
uuid: '',
email: '',
authorities: [ 'ROLE_DEVELOPER', 'ROLE_USER' ],
client_id: '',
impersonation: false, // Anyone know what this means?
permissions: [
'installedapp.read',
'installedapp.edit',
'scene.read',
'scene.edit',
'location.read',
'location.edit',
'event.read',
'global.read',
'global.edit',
'error.read'
],
featureFlags: {
'cake.camera': true,
'cake.customAuth': true,
'cake.deviceRoomAssignment': true,
'cake.feedbackLink': { hidden: true },
'cake.languagePicker': false,
'cake.cookiepolicy': true,
'cake.debugview': false,
'cake.nativeLogLevel': 'info'
},
session: { stayLoggedIn: true, sessionLength: 28800 }
}
`

$3

- To Be Determined

$3

- Provides a list of locations attached to this account

`javascript
[{
locationId: '',
name: '',
parent: { type: 'ACCOUNT', id: '' }
},
...
]
`

$3

- Provides a list of rooms at the location

`javascript
[{
roomId: '',
locationId: '',
name: '',
backgroundImage: null,
created: 1602298686032,
lastModified: 1602298686032
},
...
]
`

$3

- A list of all devices at the location
- The full extent of possible values is unknown but there is a lot of data about each device
- Some fields/values may be omitted in the following object for brevity

`javascript
[
{
locationId: '',
icon: 'https://client.smartthings.com/icons/oneui/x.com.st.d.sensor.multifunction',
inactiveIcon: 'https://client.smartthings.com/icons/oneui/x.com.st.d.sensor.multifunction/off',
plugin: { uri: 'wwst://com.samsung.one.plugin.stplugin' },
lottieData: {
icon: 'https://client-assets.smartthings.com/lottie/ic_device_multipurpose_sensor_1.json',
scenes: []
},
deviceId: '',
roomId: '',
componentId: 'main',
deviceName: '',
deviceTypeData: { type: 'NONE' },
states: [
{
capabilityId: 'contactSensor',
attributeName: 'contact',
componentId: 'main',
value: 'open',
label: 'Open',
active: true,
type: 'activated',
icon: 'https://client.smartthings.com/icons/oneui/x.com.st.d.sensor.multifunction/on',
arguments: []
},
{
capabilityId: 'contactSensor',
attributeName: 'contact',
componentId: 'main',
value: 'closed',
label: 'Closed',
active: false,
type: 'inactivated',
icon: 'https://client.smartthings.com/icons/oneui/x.com.st.d.sensor.multifunction/off',
arguments: []
},
{
capabilityId: '*',
attributeName: '*',
componentId: '*',
value: '*',
label: 'Connected',
active: true,
type: 'activated',
icon: 'https://client.smartthings.com/icons/oneui/x.com.st.d.sensor.multifunction/on',
arguments: []
}
],
actions: []
},
...
]
`

$3

- This is called when any device at the location issues an update
- The stateChange field is used to determine if this is a new value or just a generic update/ping
- This event handler is called many times so be mindful about how it is used
- Some events for the same device will be fired in close succession based on similar attributes
- The device object will only be populated if .getDevices('') was previously called
- This should be done if the device name is needed as it is not provided by the event itself

`javascript
{
event: {
data: {
eventType: 'DEVICE_EVENT',
eventId: '',
locationId: '',
deviceId: '',
componentId: 'main',
capability: 'powerMeter',
attribute: 'power',
value: 9.2, // Many devices will use a string value, such as 'on' for switches
valueType: 'number', // Other types are possible
unit: 'W',
stateChange: true,
time: '2021-06-09T04:16:03.854Z'
},
subscriptionId: ''
},
device: {} // Same structure as previously defined
`

$3

- Can be used to handle events generated from a specific device rather than all events
- Provides the same object as the event` handler

$3

- To Be Determined

$3

- To Be Determined

$3

- To Be Determined

$3

- Error messages from the websocket API
- It is unknown if there is any standardization of the format

$3

- This is called when any unrecognizable messages are received
- Also provides a way to extend the capability of this library for currently unsupported messages

👤 Author

Stephen Mendez

- Website: https://www.stephenmendez.dev
- Twitter: @stephenmendez\_
- Github: @401unauthorized

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page. You can also take a look at the contributing guide.

😃 Show your support

Give a ⭐️ if this project helped you!

Consider making a donation of any amount!

📝 License

Copyright © 2021 Stephen Mendez

This project is MIT licensed.

---
SmartThings is a registered trademark of SmartThings, Inc.

Samsung is a registered trademark of Samsung Electronics Co., Ltd.

Google Chrome is a registered trademark of Google LLC

_Part of this README was generated with ❤️ by readme-md-generator_