🐣 incubating Bifravst as an official Nordic Semiconductor project 🎉

[coderbyheart]

I am happy to share that we plan to lift Bifravst into the state of an official
Nordic project! 🎉

This means that in the coming weeks we will establish the best path to provide
this project through nRF Connect SDK,
Nordic Semiconductor Info center and
potentially other established channels.

It will lead to some form of rebranding (the Bifravst term is not a crowd
favorite 😿) and reorganizing of repositories and documentation,
but overall this means more resources and attention for this project and the
move to a first public release under the nRF Connect SDK release scheme.

I'll update this issue with more information as soon as it crystallizes.

Tasks

• look into generating Read The Docs style docs
• figure out where to publish docs on https://developer.nordicsemi.no
• decide on name/brand for the whole project (Proposal)
• decide on name of the NCS application: Asset Tracker v2 / asset_tracker_v2
• move repos to NordicSemiconductor
• move firmware repo into NCS

(more to come)

Considerations for moving the project

1. All changes must be considered from a user point of view: how will the change
   affect their ability to clone and update the project (source code and
   documentation) for their needs and also contribute back
2. The project itself must not lose abilities it has today, like frequent
   releases (including firmware builds), continuous integration and deployment

NCS

https://github.com/nrfconnect/sdk-nrf

• Need way to publish prebuilt hex files for our own environment

The guide for building applications with NCS links to the official Zephyr documentation on Application Development which asks the user to Create an application folder outside of the Zephyr base directory.

Feedback from engineers

• Out of tree is easier to use and what customers prefer
• In tree is there to force us to keep an application working with every release, but in past we have seen that applications are not tested fully and issues are discovered after a release, and then stay broken until the next major release (which is months away)
• Keeping the application out of tree allows to release fixes once they are discovered and unblock customers

InfoCenter

https://infocenter.nordicsemi.com/

• What's a good example?
  • nRF Connect for Desktop
  • nRF Connect for Cloud has no entry
• Source code is not public:
  • users can't fork / export / modify it and host it themselves with
    modifications
  • changes / feedback trough email

Feedback from Tech Writers

• they favor the current way because it keeps the documentation close to the source code and it can be kept up to date by the developers
• the project discovery should happen through DevZone in the form of blog posts, possibly also through marketing effort
• the hardware specification should however be put in InfoCenter as a Reference Design

Considerations for renaming the project

Nordic Semiconductor has
a naming scheme for its development tools
nRF Connect for <Platform> or nRF <Project> and for its
Prototyping platforms
Nordic Thingy:XX.

Keep in mind that this project is not

• a multi-cloud solutions, rather it offers concrete example for specific cloud
  vendors and right now only one: Amazon Web Services (AWS)
• a generic solution, rather it contains specific design decision for a
  ultra-low-power feather-weight (formfactor and physical weight) asset tracker

It is also not a pure SDK because it also includes hardware specifically
designed to the use case.

So the name should ideally reflect that.

A possible scheme cloud be
Nordic Cat Tracker <Component> [for <Cloud Vendor> [<Sub-Component>]]:

• Nordic Cat Tracker
• Nordic Cat Tracker Firmware
• Nordic Cat Tracker Hardware
• Nordic Cat Tracker Cloud Solution: Web Application
• Nordic Cat Tracker Cloud Solution for AWS
• Nordic Cat Tracker Cloud Solution for Azure
• Nordic Cat Tracker Cloud Solution for GCP
• Nordic Cat Tracker Cloud Solution: Device UI Server
• Nordic Cat Tracker Cloud Solution: Device UI Web Application
• Nordic Cat Tracker Cloud Solution: Cell Geolocation Helpers

These projects are support tools and libraries which have no Cat Tracker
specific behaviour so they could keep their original names:

• AWS Athena Helpers
• AWS CloudFormation Cleaner
• AWS CloudFormation Helpers
• AWS Package Layered Lambdas
• Code Style
• End-to-End BDD Test Runner Example
• End-to-End BDD Test Runner
• Eslint Configuration
• Random Words
• RSRP Bar

The GitHub project could be renamed to nordic-cat-tracker.

[coderbyheart]

I talked with the tech writers @umapraseeda and Oisin F. on how to proceed with the documentation:

• they favor the current way because it keeps the documentation close to the source code and it can be kept up to date by the developers
• the project discovery should happen through DevZone in the form of blog posts, possibly also through marketing effort
• the hardware specification should however be put in InfoCenter as a Reference Design

[coderbyheart]

Internally we agreed to:

• Maintain the application outside of the nrf repo, because this is the recommended way for customers to develop applications. Still have to be included in NCS through adding it to nrf repo west.yml
• Move repos under Nordic's official GitHub account for NCS
• Provide backlink from https://github.com/nrfconnect/sdk-nrf/tree/master/applications/asset_tracker for people who directly look into SDK source on github. It will be included in the NCS folder structure when people download NCS.
• Keep documentation close to source, and as is right now, rendered using GitBook using Markdown:  https://bifravst.gitbook.io/bifravst/ (allows customers to fork and update according to their own product)

A decision on the name has not yet been made.

[coderbyheart]

Provide backlink from https://github.com/nrfconnect/sdk-nrf/tree/master/applications/asset_tracker for people who directly look into SDK source on github. It will be included in the NCS folder structure when people download NCS.

This can be achieved through west.

In this repo the west.yaml would look like:

manifest:
  remotes:
    - name: nordic
      url-base: https://github.com/nrfconnect
  projects:
    - name: sdk-nrf
      path: nrf
      remote: nordic
      revision: vX.Y.Z
      import:
        # avoid importing ourselves
        name-denylist:
          - bifravst
  self:
    path: firmware

and then our users could do:

west init -m https://github.com/bifravst/firmware

and they would get Bifravst + NCS.

But at the same time, the manifest in nrfconnect/sdk-nrf would have:

    - name: bifravst
      path: applications/bifravst
      revision: <SHA>
      url: https://github.com/bifravst/firmware

So when our users do:

west init -m https://github.com/nrfconnect/sdk-nrf

they also get Bifravst.

[coderbyheart]

Notes from the Bifravst Q&A today with the tech writers:

• Documentation should follow https://developer.nordicsemi.com/ style (ReadTheDocs), so GitBook.com should not be used
  • mcuboot docs (https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/mcuboot/wrapper.html) are an example where the source docs are Markdown
• the firmware documentation (which should go under Applications in the NCS documentation) and the documentation of the full project, which should be separate (but look the same).
• figure out where to publish it on https://developer.nordicsemi.no

[coderbyheart]

Documentation has been converted to Sphinx/Read The Docs style: https://bifravst.github.io/bifravst/

[coderbyheart]

We have drafted a proposal for the new names today:

---

Written name

The overall name for the project is:

Asset Tracker Cloud Example

When individual flavors are considered, the name is

• Asset Tracker AWS Example
• Asset Tracker Azure Example
• ...

Slug

Main projects

The project slugs use the following naming rules for the main project
repositories that implement the Asset Tracker Cloud Example or contain otherwise
source code specific to the Asset Tracker Cloud Example.

• use asset-tracker-cloud-[vendor] as a prefix to denote that it contains
  "cloud example code"
• append -[vendor] to the prefix if the project relates to a specific cloud
  vendor
• for the firmware repo use asset-tracker-firmware
• do not use example as part of the slug

bifravst	→	NordicSemiconductor	Purpose
bifravst	→	asset-tracker-cloud-docs	Documentation
aws	→	asset-tracker-cloud-aws	AWS
azure	→	asset-tracker-cloud-azure	Azure
app	→	asset-tracker-cloud-app	Web App
firmware	→	asset-tracker-firmware	Firmware
device-ui	→	asset-tracker-cloud-device-ui	Device Simulator Web App
device-ui-server	→	asset-tracker-cloud-device-ui-server	Device Simulator Server used by the Device Simulator Web App
code-style	→	asset-tracker-cloud-code-style	Code style for all Asset Tracker Cloud Example projects
eslint-config-typescript	→	asset-tracker-cloud-eslint-config-typescript	TypeScript code style for all Asset Tracker Cloud Example projects

Helper projects

The project slugs use the following naming rules for helper repositories:

use cloud-[vendor]- as a prefix for projects that have cloud vendor specific
code, but are not specific to the asset tracker application, e.g. helper
libraries for a specific AWS service:

bifravst	→	NordicSemiconductor	Purpose
cloudformation-cleaner	→	cloud-aws-cloudformation-cleaner	cleans up left-over stacks from CI runs
cloudformation-helpers	→	cloud-aws-cloudformation-helpers	simplifies working with AWS CloudFormation stacks.
package-layered-lambdas	→	cloud-aws-package-layered-lambdas	packages lambdas with Webpack for deploying to AWS
timestream-helpers	→	cloud-aws-timestream-helpers	simplifies working with AWS Timestream
firmware-ci-aws	→	cloud-aws-firmware-ci	Firmware CI runner for AWS

use cloud- as a prefix for prjects that are used with a cloud but are
vendor-agnostic:

bifravst	→	NordicSemiconductor	Purpose
firmware-ci	→	cloud-firmware-ci	Contains helper functions for interacting with the nRF9160 used during end-to-end tests
e2e-bdd-test-runner	→	cloud-e2e-bdd-test-runner	Implementation of a test-runner for end-to-end tests of cloud-native applications using Gherkin features.
e2e-bdd-test-runner-example	→	cloud-e2e-bdd-test-runner-example	Demonstrates e2e-bdd-test-runner

use -[language] as a suffix for projects that provide libraries for a
specific programming environment:

bifravst	→	NordicSemiconductor	Purpose
cell-geolocation-helpers	→	cell-geolocation-helpers-js	Helper functions for the cell geolocation feature.
object-to-env	→	object-to-env-js	Convert an object to environment variable definitions
random-words	→	random-words-js	Returns random 8-letter words from the Webster's Unabridged Dictionary.
rsrp-bar	→	rsrp-bar-react	React component to render an RSRP bar or a failover icon in case the reported value is not valid.

keep standalone projects as is:

bifravst	→	NordicSemiconductor	Purpose
at_client	→	at_client	Compile the AT client sample for 9160DK and Thingy:91 and publish it regularly.