Best Practices for Production-Ready Projects

This guide contains a list of practices we've found useful as we've helped our users take projects from prototypes, to real, production deployments.

For readers early in their development, this guide contains a number of best practices you should be aware of, and that you should strive to implement by the time your project is ready for real-world usage.

For readers late in their development, or with projects already out in the field, this guide can be viewed as a list of highly recommended practices you should consider adopting for the long-term success of your deployment, especially as you scale up to hundreds or thousands of devices.

• Configure Your Notecard for Low-Power Usage
• Use Note Templates
• Use Environment Variables to Store Configuration
• Allow For Host Firmware Updates
• Create a Provisioning Process
  • Use a Setup Script
  • Use Hardware-Specific QR Codes

Configure Your Notecard for Low-Power Usage

Although many of our quickstart tutorials sync data on a frequent cadence for convenience, that’s likely not an option for your production apps if they need to work on battery power.

We designed the Notecard to be low-power friendly, with low current consumption, and built in a number of features to help you optimize your projects for production deployments. This includes the ability to manage the modem's power state, configure synchronization intervals based on battery levels, and intelligently manage the power of a connected host microcontroller.

If you're building a battery-powered project, we recommend reading through our low-power design guide in detail so you can configure your Notecard appropriately.

Use Note Templates

By default, the Notecard allows for maximum developer flexibility in the structure and content of Notes. As such, individual Notes in a Notefile do not share structure or schema. You can add JSON structures and payloads of any type and format to a Notefile, adding and removing fields as required by your application.

However, the Notecard provides an additional a templating mechanism that requires you to define a schema for the data you places in Notefiles. By providing Note templates you gain the following benefits:

• Data savings, as the Notecard can more efficiently store, compress, and transmit your data by knowing its structure.

• The ability to move between different RATs (radio access technologies), as Note templates are required when working with LoRa or satellite connectivity, because of the low-bandwidth nature of those technologies.

• You can store additional Notes on your device. (The Notecard limits non-templated Notefiles to 100 Notes.)

If you want to give Note templates a try, check out the following guide.

Use Environment Variables to Store Configuration

Once you have devices out in the world, you'll inevitably want to tweak how they work or to run simple experiments—e.g. how would synching every hour instead of every 30 minutes affect my battery usage?

The easiest way to accomplish this configurability with Blues is by using environment variables, which are a Notehub state and settings management feature that allow you to set variables in key-value pairs, and intelligently synchronize those values across devices and fleets of devices.

Based off our experiences with customers, we highly recommend placing any of your project's settings or configuration values in environment variables, and to not hardcode specific values into your firmware. With your configuration in environment variables, you can change the behavior of your devices in the Notehub user interface or Notehub API, and not have to go through the hassle of physically visiting devices, or updating their entire firmware.

The guide below has examples on how to retrieve environment variables values in your firmware.

Allow for Host Firmware Updates

Having the ability to update host firmware is crucial for maintaining security and for fixing mission-critical bugs.

At Blues we make this possible through Notecard Outboard Firmware Update, a feature of the Notecard that allows you to perform host firmware updates "from the outside", and not involving the firmware running on the MCU whatsoever. Notecard Outboard Firmware Update works regardless of RTOS or language, and can be used to switch between them, even modifying flash memory layout and partitioning any time after-the-fact, at the developer's discretion.

You can enable Notecard Outboard Firmware Update with some simple wiring and a single Notecard request, and it can give you the power to update your devices at any time from your desk.

note

Over-the-air firmware updates are not possible over LoRa because of the low-bandwidth nature of the protocol.

Read the tutorial below a step-by-step guide to enabling Notecard Outboard Firmware Update, and trying it out on your hardware.

Create a Provisioning Process

As your project scales and requires more than a single device, establishing a repeatable process for unboxing and preparing devices for deployment can save time and ensure consistent operation.

Use a Setup Script

One tool you may wish to use to streamline provisioning is the Notecard CLI's ability to run setup scripts. Setup scripts allow you to place your default Notecard configuration in a .json file, and to run those commands on your device with a USB connection and a single CLI command.

# config.json
{"req":"hub.set","product":"com.your-company.your-name:your_product"}
{"req":"hub.set","mode":"periodic","outbound":60,"inbound":1440}
{"req":"card.voltage","mode":"lipo"}

notecard -setup config.json

note

We recommend using setup scripts for your default Notecard configuration— you can still use environment variables to override the individual values in your firmware as necessary.

To try it out, install the Notecard CLI, and then check out our guide to using setup scripts below.

Use Hardware-Specific QR Codes

Each Notecard comes with a sticker containing a QR code unique to that device. By default that QR code links to the Quickstart tutorial, but you can provide a redirect URL for your device in Notehub.

By providing a redirect URL you can have the QR code link to a device dashboard, or to a system that can help an installer complete any provisioning steps in the field.

To try it out, check out our guide to working with QR codes below.