Resin SDK v6 released: OS metadata, browser support, custom locations and more

The resin SDK provides a familiar and well-documented wrapper around the resin.io API, allowing you to automate your fleet's operations from JavaScript. It's a great way to coordinate and connect your fleet's behavior to external API's in just a few lines of code.

We're very excited to announce a major new release of the SDK: after a couple of months in beta, the SDK is now officially stable at version 6.0.0, which comes with a whole range of exciting new features and bug fixes, along with a few breaking changes (hence the major bump) that we've been preparing for a little while.

Highlights

Browser Support

The SDK now works in browsers, so you can now write client-side code that interacts with the resin.io API to register applications and devices, query the status and details of your fleet, stream device logs, and even reconfigure devices and applications directly, all from inside your web page.

Use this to build your own resin.io dashboard or control panel, create your own interface for other teams to setup and configure devices, or analyze and graph live device data with standard web tools.

If you're using a bundler like webpack or browserify, you can simply pick up our npm package (resin-sdk) and get going straight away. If you're not, the package includes minified UMD-compatible builds with AMD, CommonJS and global support in build/resin-browser.min.js, with an unminified version at build/resin-browser.js too.

Take a look at the installation guide for more setup details.

More OS lookup features and resinOS 2.0 support

Want to know more about the OS versions available? There's now a few methods for this:

  • resin.models.os.getSupportedVersions(deviceType)
  • resin.models.os.getMaxSatisfyingVersion(deviceType, [semverVersionRange])
  • resin.models.os.getDownloadSize(deviceType, [version])

In addition, the existing os.getLastModified and os.download methods now support an optional version parameter, so you can download and query for images other than the latest stable release.

This gives you much more information and fine-grained control if you're automating OS downloads or device provisioning yourself, and you could also use this to automatically stay notified of new OS versions for your device, at the exact moment they become available.

This ties into resinOS 2.0 support too: SDK v6 includes support for querying metadata and downloading images for the latest resinOS releases, so you can keep up with all the exciting new features from there as well.

Custom location support

Resin.io allows you to view your fleet on a map and see the location of your devices all around the world. This was originally done by IP geolocation, but we recently added the ability to specific the location yourself via the API and the dashboard, to make this feature more precise and controlled.

The SDK now has support for custom locations too. Call resin.models.device.setCustomLocation(deviceId, { lat: X, long: Y }) and the location for your device will be updated everywhere, overriding IP geolocation entirely.

You can retrieve this metadata from every method that queries for device data, such as resin.models.device.get, as custom_longitude and custom_latitude.

Combine all this together, and you have a built-in store for device location data. Track your exact device locations each time they're known, or update them constantly if you have GPS available, and use the new browser support to follow their paths around the globe.

ID overloads for device and application parameters

Until now, all device and application methods took the device's UUID, and the application's name. This made things easy to get started with, but is inconvenient and not performant for larger applications, where you're running a series of queries and storing information yourself. In these complex cases it's often preferable to store only the raw application and device IDs in your application, and to query using those IDs directly. Doing this keeps your code simpler, and would also allow the SDK to avoid making some extra requests, making it faster.

That wasn't easily possible, until now. With version 6, these methods are all overloaded. If you pass a string, as previously required, it'll be treated as a UUID or application name as before. If you pass a number, however, the SDK interprets that as an ID and avoids the extra request, making everything faster for you, and easier for managing a large number of applications.

Putting this into use in your code can allow you to simplify larger codebases that use the SDK extensively, while also improving their performance en route.

Low-level API Helpers

For users who need to make calls to our API that the SDK doesn't support, or who want to use special OData parameters, we now expose our PineJS client as .pine.

For users who want more direct control of the underlying authentication and token management process, we now expose our resin-token instance as .token.

For users who want to make direct HTTP requests to the API without having to worry about authentication, we now expose our resin-request instance as .request.

Most users shouldn't need to use these, but if you're trying to use the SDK in unusual ways, or to use our API to do queries that don't have built-in support, then this should make your life a lot easier. Do consider filing an issue against the SDK to support your use case as a first class citizen though - we're always keen to support to more users' needs!

Breaking changes

All this work does come with a few major breaking changes you should be aware of:

  • The SDK now exports a factory function, not a built SDK instance, to allow configuration for different environments. You can call this with no arguments to get a sensible default, or see the documentation for the full list of options supported.
  • As part of supporting some changes to our device registration flow, models.device.register() now returns device registration information, not an entire device object, and models.device.generateUUID() has now become generateUniqueKey()
  • Device-specific environment variable objects (e.g. from resin.models.environmentVariables.device.getAll(deviceId)) now return their names as .name, not .env_var_name. This means they're now consistent with application-wide environment variables.

There's some other smaller breaking changes; see the changelog for full details.

Try it for yourself

If the above catches your interest, this is all available on npm right now:

npm install resin-sdk  

Check out the the full SDK docs at https://docs.resin.io/tools/sdk/, and let us know what you think in the forums!

comments powered by Disqus
Terms of Service | Privacy Statement | Master agreement | Copyright 2019 Balena | All Rights Reserved