Bluetooth Application Layer development on Nexus Channel

[jjmilburn]

Hi Vaibhav,

Definitely, regarding the extension questions! Let me respond to the particular questions for each:

PAYG Credit

“di” (device IDs) is an optional list of Nexus IDs of devices that are being ‘controlled’ (typically ‘mirroring’) the credit of a controller/gateway. Based on what you’ve said about Airlink, I think this ‘di’ property would not be used/relevant in your case. Its basically exposed for diagnostics only anyway, but is used in some existing integration work).

(We can also edit the text for the optional di property description to make it more clear, if you have suggestions, but you can probably just ignore it here).

Energy Generation

Definitely! Again, these models pre 1.0 are essentially drafts. Would these changes capture your needs?

• ‘ft’ becomes a uint8_t enum, which has at least ‘generic fault’ (fault but no description)and ‘OK’ (no faults present), or a number of different faults? Or, would it be preferable to have a bitmask-style where ft is a longer value (uint32_t, multi-byte string) and each bit maps to a specific fault (so multiple faults could be present at once in a compact way?)

• Units are described on each of the properties, e.g.
  

  

• eg, egs, egp: egs and egp define a time window over which ‘eg’ is computed:

(You can see the per-property details by expanding the ‘20x’ GET response, e.g. the 205 response for energy generation;
https://angaza.github.io/nexus-channel-models/resource_types/core/energy/102-generation/redoc_wrapper.html#/paths/~1ein/get

(right now, the resource only lists ‘vi’ and ‘ai’ as required).

Energy Consumption

• Similar comment as ‘ft’ on energy generation - lets change it. Whats more flexible in your opinion, the enum, bitstring, or something else?

• eo, eos, eop = eos and eop define a time window over which ‘eo’ is computed.
  

  

(right now, the resource only lists ‘vo’ and ‘ao’ as required).

Battery

Similar comment about ‘ft’ as the other two. I suspect we could just apply a change to all three resources here.

ca (capacity), ds (discharging status), cg (charging status), lb (t/f below low battery threshold):

100% agree that pmin, pmax, tchg, and bh could be added - I don’t see any properties on the battery resource currently that handle that information well. If you can specify some ranges for those, and enums if relevant (depending on how you model ‘bh’) I could either help put a PR up on your behalf or help you put one up.

Regarding the state of these resources - for the most part, these are derivations from the existing OCF resource models. For example, the OCF ‘battery’ resource: OCF oneIoTA

But, we intentionally spun off the Nexus Channel Core registry to allow changes like the ones you are proposing to be captured and used. I only mention this so you have an idea of where the ‘baseline draft’ models came from - we certainly expect and anticipate that these models will change based on industry needs (like the ones you are proposing!).

[jjmilburn]

@Vaibhav , to get to the resource property definitions I took screenshots of above:

1. Start at the Resource Type Registry
2. Click on the relevant resource link (e.g. energygen.oas.yaml)
   
3. Click on the ‘205’ under ‘Responses’ to expand the content for a 205 response from this resource (to a GET request)
   
   

[Vaibhav]

Oh I could swear I tried clicking everywhere on the page, apologies. I’ll reformat and update the Airlink manual with full details and changes per above. E.g. I’ve also created the COSE encrypted property to allow building of Nexus Channel app links above.

@jjmilburn I’ve updated the specs now, could you please take a look? I added a new column to show which resource each property is mapping to.
https://airlinkdocs.enaccess.org/AirLink%20Manual%2091fc0f59a1464a6bbb654b164ad4676f/AirLink%20Devices%204dfc27f9e47e452594ec42eafbb56154.html

[jjmilburn]

Ah, I hadn’t responded to some of your questions from the above comment - let me try here.

An ‘adf’ for every property.

Sounds good. Do you think it would be possible (eventually) to navigate between different Airlink ‘adfs’ for a given Airlink resource on the website, so a developer could quickly look up what format they’d need to interface with a certain device (or, someone could just include multiple ADF handlers for a given resource if they plan to connect to devices with slightly different implementations, etc).

Each device would just report the internal combination of rtr and UUID within nx/res, that way the gateway can use the rtr value to access the same bluetooth service and not require a UUID registry.

That makes sense to me. So, as long as every Airlink device knows the fixed nx/res UUID, they can use that to determine every other UUID on a device they’re connecting to (the first connection just polls the nx/res UUID, and then makes further logic decisions based on whats available). Agreed that this eliminates the need for an offline UUID registry.

I’ve split it out already in the uploaded airlink documentation as a ‘customer provisioning’ resource. I’m thinking it might also need a human-readable device serial number or payment reference added. Here’s the set proposed:

Noted - the bit that confused me here was that the customer/client info was ‘optional’, which confused me a bit.

You had mentioned that the payg resource should include a product type e.g. water pump etc. That made sense.

I think I may have misspoken here. I’m not sure I see the use case (currently) for a product type on the PAYG credit resource. That resource currently does specify credit units (gallons, hours, minutes, etc), but that doesn’t require a product type. Can you elaborate on what the product type might be used for on that specific resource?

Other potential use cases are if we allow a local authority figure in a community to act as a backup in case someone’s phone is broken, to help update their credits. This is important in productive use cases since they don’t want to miss even a day of productivity and many of the customers are living hand to mouth.

Makes sense - thanks! It sounds like the typical non-gateway device might connect to a handful of gateways over its lifetime (usually), but not ‘dozens’. Correct me if thats wrong, I’m just building a mental model here.

I probably don’t understand enough about encryption to get how this works intuitively, and clearly you have given this some thought. Is there any documentation or example code available that you could point me to?

There is a bit, but there is a larger release pending some other gates currently. The code I want to share with you is the embedded-side code used by this demo. The code that I want to share demonstrates steps 2 and onwards (below). But, the general flow is:

1. Backend (or some server that is aware of the secret keys of both the ‘controller’ and ‘accessory’ you wish to securely link) generates an “Origin Command” to link the devices. This is sent to the “Controller” (e.g. gateway device)
2. The “Controller” validates it against its own secret key (ensures this command is valid for the controller to accept/has a valid MAC, hasn’t previously been used, etc), and if so, extracts information from the ‘origin command’ that can be used to send a link challenge to the specified “Accessory”. The link challenge is not equivalent to ‘a token’, its information from the server mixed with a random value from the controller/gateway… but functionally, its close enough to think of it as an ‘accessory specific one time use token’.

• At this point, the controller has derived a ‘link security key’ that will be used to secure (generate authentication codes/MACS) for any secured messages sent to/from the accessory.

3. The controller sends a ‘link challenge’ to the accessory, which is validated by the accessory (command has a valid MAC, is for this accessory, hasn’t been used before). The accessory uses the link challenge info and its own secret key to independently derive the same ‘link security key’ as the controller.
4. The accessory sends back a response ‘proving’ that it knows the same link security key as the controller (without ever sending that key over the wire/air). The controller confirms this, and the link is established.
5. All further communication between the Nexus Channel resources for these two devices can use the security layer, which will ensure that messages sent/received are not replayed (protection against MITM and replay attacks), prevents any payload tampering/modification, and protects against address spoofing (the sender has to provide their Nexus ID/some app ID which is used to look up the link security key on the receiver side)

• The message CBOR payload is secured, as well as a nonce, and the CoAP code (GET, response code, etc).

I will share the link when the more useful code is released that has can more easily be followed with that demo…

I could see where having example code for this kind of interaction would make this easier to adopt for someone designing a new device. Do you believe that this interaction is fairly optimal across different use cases and would become the de-facto standard? Or do you think manufacturers might develop their own application layer handshake (e.g. re-using the passthrough property in their own ways)?

For the use cases encountered so far, I think the example showing use of the existing app layer link handshake (Nexus Channel Redoc Wrapper), which provides authentication/integrity is likely sufficient. Its definitely extensible, though - someone could add their own link handshake which supports multi-party/group keys (right now, links are one-to-one), encryption (secrecy) in addition to integrity/authentication, etc.

We were thinking of using a uint_32 device ID per advertisement packet, would the Nexus IDs then be application layer IDs that are separate from the device ID?

Currently, Angaza has been distributing ‘universal’ PAYG IDs freely via the Nexus API that can be converted into Nexus IDs by appending a fixed 2-byte ‘authority ID’ in front of them. These PAYG IDs are used for devices regardless of what PAYG CRM they are sold on (Angaza or otherwise), but its not clear if the Airlink “Device IDs” would be a good fit for generation from this same batch of numbers or not. If not, it might make sense to just assign a new “Authority ID” for Airlink “device IDs” (which are just the IDs as specified/in use now you are describing).

Interoperable gateways from other manufacturers as well as other client’s gateways from the same manufacturer would need to report this one combined property as part of enabling crowd-sourced stolen asset detection.

So it sounds like that you could (maybe in the future) have backend logic similar to ‘tell all gateways to be on the lookout for these reported stolen devices’, and when they pop up, you can geolocate them? That is pretty neat.

For a resource model related to location, would ‘lat/long’ be sufficient, or do you want an accuracy field as well (if available)?

[Vaibhav]

@jjmilburn

Do you think it would be possible (eventually) to navigate between different Airlink ‘adfs’ for a given Airlink resource on the website

Haven’t thought through this. Does any API doc system allow this? We could move to a system that does if available - do you plan to move hand-off documentation or maintain it? We could do that as a 1.0 and look for something that tracks API by version or even documents by version…

@jjmilburn

Can you elaborate on what the product type might be used for on that specific resource?

Possibly unit is sufficient, although it won’t be unique hence it seemed to make sense to have product type. Let’s take example of water flow - both a smart tap and pump would count that as a credit unit. Can you think of any other difference that needs to be captured between the two for the systems to work? If not we could remove it.

@jjmilburn

not ‘dozens’

We’re trying to crowdsource the location detection, so many gateways could be authorized for a single device to aggregate ‘drive-by’ location. There wouldn’t be an actual connection, just downloading the advt packet. Although each of those gateways would need to be authorized to post that data to the device’s history on our server.

@jjmilburn

“Authority ID” for Airlink “device IDs” (which are just the IDs as specified/in use now you are describing).

Ok as long as the Authority ID - universal PAYG ID conversion to Nexus IDs is done at the application layer this should inter-work I think?

@jjmilburn

‘tell all gateways to be on the lookout for these reported stolen devices’

That’s one potential selling point of interoperable systems in a region, sort of a ‘group insurance’ for interoperating distributors.

@jjmilburn

accuracy field as well

We do need this accuracy field, because we might be using basic GSM triangulation or cell-phone coordinates as a reference. Add to that BLE signal strength detection by the gateway and accuracy becomes important I think. Location is tricky!

[jjmilburn]

@Vaibhav

Haven’t thought through this. Does any API doc system allow this? We could move to a system that does if available - do you plan to move hand-off documentation or maintain it? We could do that as a 1.0 and look for something that tracks API by version or even documents by version…

I’m not familiar with a free tool that does this, but I believe that Redocly has some facility for this, they claim “Multiple versions supported with a version switcher”.

I’m not sure what hand-off documentation you are referring to - but we plan to keep all Nexus Channel Core models available in the registry, and would be happy to redirect any inquiries about AirLink to whatever site will store the adfs and relevant definitions for the current version if you like!

Possibly unit is sufficient, although it won’t be unique hence it seemed to make sense to have product type. Let’s take example of water flow - both a smart tap and pump would count that as a credit unit. Can you think of any other difference that needs to be captured between the two for the systems to work? If not we could remove it.

I’m a bit confused here - the PAYG credit resource makes no statement or claim about ‘what kind of device’ it is hosted on. In other words, it would be normal and expected for many different varieties of devices to have the same ‘units’ for their PAYG credit resource (e.g. seconds/hours for many time based devices). That resource simply stores / reports the remaining credit on the device (in whatever units the device uses for metering credit), and allows updating of the remaining value. Its certainly imaginable that a single device might have two different PAYG credit management schemes running simultaneously (e.g. a device that is both a metered pump and a SHS), but we’d anticipate seeing two different “PAYG credit” resources in that case on the device (as the credit for each separate ‘management scheme’ would be independent of one another).

Am I missing something? I suspect there is some other use case that might be implicitly overloaded onto the PAYG credit resource, and I’m trying to understand what it is.

We’re trying to crowdsource the location detection, so many gateways could be authorized for a single device to aggregate ‘drive-by’ location. There wouldn’t be an actual connection, just downloading the advt packet. Although each of those gateways would need to be authorized to post that data to the device’s history on our server.

That makes sense. If they are just picking up the advertising packet, and don’t need to securely message back and forth to that resource, it doesn’t sound like you’d be using Nexus Channel Security Links for that (since setting those up would imply at least one round-trip). Similarly, Nexus Channel security applies to security between the devices themselves, so the way the gateway authenticates with the cloud ‘on behalf of’ the accessory is a separate problem (one that I think you’ve solved/are solving with thingsboard, if I understand correctly?).

Ok as long as the Authority ID - universal PAYG ID conversion to Nexus IDs is done at the application layer this should inter-work I think?

I think so too.

We do need this accuracy field, because we might be using basic GSM triangulation or cell-phone coordinates as a reference. Add to that BLE signal strength detection by the gateway and accuracy becomes important I think. Location is tricky!

Sounds great! It might make sense to think about what the atomic ‘resources’ here are - is a geolocation resource fully defined by lat/long/accuracy, and how does a (separate?) bluetooth triangulation resource feed into that, etc.