From: Johan Hedberg <[email protected]>
---
Makefile.am | 2 +-
doc/6lowpan-api.txt | 291 ++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 292 insertions(+), 1 deletion(-)
create mode 100644 doc/6lowpan-api.txt
diff --git a/Makefile.am b/Makefile.am
index 90bb86baefdc..d6726dde40a0 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -239,7 +239,7 @@ EXTRA_DIST += $(test_scripts)
EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
doc/test-coverage.txt doc/settings-storage.txt
-EXTRA_DIST += doc/mgmt-api.txt \
+EXTRA_DIST += doc/mgmt-api.txt doc/6lowpan-api.txt \
doc/adapter-api.txt doc/device-api.txt \
doc/agent-api.txt doc/profile-api.txt \
doc/network-api.txt doc/media-api.txt \
diff --git a/doc/6lowpan-api.txt b/doc/6lowpan-api.txt
new file mode 100644
index 000000000000..03dffbff8968
--- /dev/null
+++ b/doc/6lowpan-api.txt
@@ -0,0 +1,291 @@
+6LoWPAN Management API
+**********************
+
+Copyright (C) 2015 Intel Corporation
+
+
+Overview
+========
+
+The 6LoWPAN Management API follows largely the same principles as the
+main Bluetooth Management API described in mgmt-api.txt. The main
+difference is a separate namespace for command and event codes,
+distinguished by using HCI_CHANNEL_6LOWPAN rather than
+HCI_CHANNEL_CONTROL when creating the mgmt socket.
+
+
+Read 6LoWPAN Version Information Command
+========================================
+
+ Command Code: 0x0001
+ Controller Index: <non-controller>
+ Command Parameters:
+ Return Parameters: Version (1 Octets)
+ Revision (2 Octets)
+
+ This command returns the 6LoWPAN version and revision.
+ Besides, being informational the information can be used to
+ determine whether certain behavior has changed or bugs fixed
+ when interacting with the kernel.
+
+ This command generates a Command Complete event on success or
+ a Command Status event on failure.
+
+
+Read 6LoWPAN Supported Commands Command
+========================================
+
+ Command Code: 0x0002
+ Controller Index: <non-controller>
+ Command Parameters:
+ Return Parameters: Num_Of_Commands (2 Octets)
+ Num_Of_Events (2 Octets)
+ Command1 (2 Octets)
+ Command2 (2 Octets)
+ ...
+ Event1 (2 Octets)
+ Event2 (2 Octets)
+ ...
+
+ This command returns the list of supported 6LoWPAN commands
+ and events.
+
+ The commands Read 6LoWPAN Version Information and Read
+ 6LoWPAN Supported Commands are not included in this list.
+ Both commands are always supported and mandatory.
+
+ The events Command Status and Command Complete are not included
+ in this list. Both are implicit and mandatory.
+
+ This command generates a Command Complete event on success or
+ a Command Status event on failure.
+
+
+Read Controller Index List Command
+==================================
+
+ Command Code: 0x0003
+ Controller Index: <non-controller>
+ Command Parameters:
+ Return Parameters: Num_Controllers (2 Octets)
+ Controller_Index[i] (2 Octets)
+ Supported_Features[i] (4 Octets)
+
+ This command returns the list of currently known controllers
+ that can be used for 6LoWPAN connections. Controllers added or
+ removed after calling this command can be monitored using the
+ Index Added and Index Removed events.
+
+ The Supported_Features is a bitmask with the following available
+ bits:
+
+ 0 Node Role Supported
+ 1 Router Role Supported
+
+ This command generates a Command Complete event on success or
+ a Command Status event on failure.
+
+
+Connect Command
+===============
+
+ Command Code: 0x0004
+ Controller Index: <controller id>
+ Command Parameters: Address (6 Octets)
+ Address_Type (1 Octet)
+ Return Parameters: Address (6 Octets)
+ Address_Type (1 Octet)
+ Network_Interface (16 Octets)
+
+ This command is used to connect to a remote 6LoWPAN Node.
+
+ The returned Network_Interface parameter is a nul-terminated
+ string containing the created network interface name.
+
+ This command generates a Command Complete event on success
+ or failure.
+
+ Possible errors: Busy
+ Invalid Parameters
+ Not Powered
+ Invalid Index
+
+
+Disconnect Command
+==================
+
+ Command Code: 0x0005
+ Controller Index: <controller id>
+ Command Parameters: Address (6 Octets)
+ Address_Type (1 Octet)
+ Return Parameters: Address (6 Octets)
+ Address_Type (1 Octet)
+
+ This command is used to disconnect from a remote 6LoWPAN Node.
+
+ This command generates a Command Complete event on success
+ or failure.
+
+ Possible errors: Busy
+ Not Connected
+ Invalid Parameters
+ Not Powered
+ Invalid Index
+
+
+Start Node Command
+==================
+
+ Command Code: 0x0005
+ Controller Index: <controller id>
+ Command Parameters:
+ Return Parameters:
+
+ This command is used create a 6LoWPAN Node for a specified
+ controller.
+
+ This command generates a Command Complete event on success or
+ a Command Status event on failure.
+
+ Possible errors: Busy
+ Invalid Index
+
+
+Stop Node Command
+=================
+
+ Command Code: 0x0006
+ Controller Index: <controller id>
+ Command Parameters:
+ Return Parameters:
+
+ This command is used to stop a 6LoWPAN Node for a specified
+ controller.
+
+ This command generates a Command Complete event on success or
+ a Command Status event on failure.
+
+ Possible errors: Rejected
+ Invalid Index
+
+
+Command Complete Event
+======================
+
+ Event Code: 0x0001
+ Controller Index: <controller id> or <non-controller>
+ Event Parameters: Command_Opcode (2 Octets)
+ Status (1 Octet)
+ Return_Parameters
+
+ This event is an indication that a command has completed. The
+ fixed set of parameters includes the opcode to identify the
+ command that completed as well as a status value to indicate
+ success or failure. The rest of the parameters are command
+ specific and documented in the section for each command
+ separately.
+
+
+Command Status Event
+====================
+
+ Event Code: 0x0002
+ Controller Index: <controller id> or <non-controller>
+ Event Parameters: Command_Opcode (2 Octets)
+ Status (1 Octet)
+
+ The command status event is used to indicate an early status for
+ a pending command. In the case that the status indicates failure
+ (anything else except success status) this also means that the
+ command has finished executing.
+
+
+Index Added Event
+=================
+
+ Event Code: 0x0003
+ Controller Index: <controller id>
+ Event Parameters: Supported_Features (4 octets)
+
+ This event indicates that a new controller has been added to the
+ system that can be used for 6LoWPAN.
+
+ The Supported_Features is a bitmask with the following available
+ bits:
+
+ 0 Node Role Supported
+ 1 Router Role Supported
+
+
+Index Removed Event
+===================
+
+ Event Code: 0x0004
+ Controller Index: <controller id>
+ Event Parameters:
+
+ This event indicates that a 6LoWPAN-capable controller has been
+ removed from the system.
+
+
+6LoWPAN Connected Event
+=======================
+
+ Event Code: 0x0005
+ Controller Index: <controller id>
+ Event Parameters: Address (6 Octets)
+ Address_Type (1 Octet)
+ Role (1 Octet)
+ Interface_Name (16 Octets)
+
+ This event indicates that a successful 6LoWPAN connection has
+ been created to the remote device.
+
+ Possible values for the Address_Type parameter:
+ 1 LE Public
+ 2 LE Random
+
+ For devices using resolvable random addresses with a known
+ identity resolving key, the Address and Address_Type will
+ contain the identity information.
+
+ The Role parameter indicates which role the local system has for
+ the connection. The parameter has the following possible values:
+ 0x00 Node
+ 0x01 Router
+
+ The Network_Interface parameter is a nul-terminated
+ string containing the created network interface name.
+
+
+6LoWPAN Disconnected Event
+==========================
+
+ Event Code: 0x0006
+ Controller Index: <controller id>
+ Event Parameters: Address (6 Octets)
+ Address_Type (1 Octet)
+ Role (1 Octet)
+ Reason (1 Octet)
+
+ This event indicates that the 6LoWPAN connection was lost to a
+ remote device.
+
+ Possible values for the Address_Type parameter:
+ 1 LE Public
+ 2 LE Random
+
+ For devices using resolvable random addresses with a known
+ identity resolving key, the Address and Address_Type will
+ contain the identity information.
+
+ The Role parameter indicates which role the local system has for
+ the connection. The parameter has the following possible values:
+ 0x00 Node
+ 0x01 Router
+
+ Possible values for the Reason parameter:
+ 0 Unspecified
+ 1 Connection timeout
+ 2 Connection terminated by local host
+ 3 Connection terminated by remote host
--
2.1.0
Hi Marcel,
On Fri, Mar 20, 2015, Marcel Holtmann wrote:
> >>> +Read Controller Index List Command
> >>> +==================================
> >>> +
> >>> + Command Code: 0x0003
> >>> + Controller Index: <non-controller>
> >>> + Command Parameters:
> >>> + Return Parameters: Num_Controllers (2 Octets)
> >>> + Controller_Index[i] (2 Octets)
> >>> + Supported_Features[i] (4 Octets)
> >>> +
> >>> + This command returns the list of currently known controllers
> >>> + that can be used for 6LoWPAN connections. Controllers added or
> >>> + removed after calling this command can be monitored using the
> >>> + Index Added and Index Removed events.
> >>> +
> >>> + The Supported_Features is a bitmask with the following available
> >>> + bits:
> >>> +
> >>> + 0 Node Role Supported
> >>> + 1 Router Role Supported
> >>> +
> >>> + This command generates a Command Complete event on success or
> >>> + a Command Status event on failure.
> >>
> >> so my preference is to keep command codes 0x0001 - 0x0003 exactly the
> >> same as with what we have in the current GAP part of the API. That
> >> means this should just return the list of controller indexes.
> >
> > For 0x0001 and 0x0002 I agree, but I'm not convinced for the rest. If
> > the information we need to return is rather simple we can avoid
> > unnecessary messaging and context switches if we just include it along
> > with the index. So I'd consider going with the "Extended" style index
> > commands and events that we just recently introduced to the GAP channel
> > as well.
>
> the extended read index list is totally different here. Features do
> not belong in here. And this is actually more like Supported_Settings
> and Current_Settings.
>
> > If we find that we need more information in the future we can always
> > then add a Read Info command.
>
> Not really. We add that from the start. Worked fine for a long time
> for us and I rather not break with a design that we know works.
This really isn't that complex of an API that we should need to
speculate on what would work or not work (I think it's clear that both
options can result in working code). Anyway, I'm not gonna fight this
detail further as I don't have a strong opinion on it.
> >> This also means that event codes 0x0001 - 0x0005 kept exactly the
> >> same.
> >
> > For the index added event I'd still consider having simple info there.
> > As for the HW error, that just makes no sense at all to me. We're
> > operating purely on an L2CAP level here and that error is an HCI level
> > detail. The kernel already handles that by resetting the controller so
> > user space will either way get the appropriate "disconnected" events for
> > the 6lowpan connection.
>
> A client that only operates on the 6LoWPAN side of things still wants
> to know if a hardware error happened. Otherwise you end up having to
> open two sockets.
The user space app with the 6lowpan socket will either way get a
notification that the connection got dropped because we now days handle
HW errors cleanly on the kernel side. Trying to cram HCI details like
that here feels like a layer violation to me (not to mention it'd result
in weird kernel-side code where we need to expose this HCI event to
modules).
As for the HW error event to user-space through the GAP socket, we're
not even doing anything with it right now (nor do we need to since the
kernel takes care of it). And if you did want to do something with it
you'd still have an GAP socket somewhere, even though it's not
necessarily in the same app as the 6lowpan socket.
> >>> +Start Node Command
> >>> +==================
> >>> +
> >>> + Command Code: 0x0005
> >>> + Controller Index: <controller id>
> >>> + Command Parameters:
> >>> + Return Parameters:
> >>> +
> >>> + This command is used create a 6LoWPAN Node for a specified
> >>> + controller.
> >>> +
> >>> + This command generates a Command Complete event on success or
> >>> + a Command Status event on failure.
> >>> +
> >>> + Possible errors: Busy
> >>> + Invalid Index
> >>> +
> >>> +
> >>> +Stop Node Command
> >>> +=================
> >>> +
> >>> + Command Code: 0x0006
> >>> + Controller Index: <controller id>
> >>> + Command Parameters:
> >>> + Return Parameters:
> >>> +
> >>> + This command is used to stop a 6LoWPAN Node for a specified
> >>> + controller.
> >>> +
> >>> + This command generates a Command Complete event on success or
> >>> + a Command Status event on failure.
> >>> +
> >>> + Possible errors: Rejected
> >>> + Invalid Index
> >>
> >> Generally I think Set Node and Set Router seems to be the more obvious
> >> commands here. And they could have then also returned the information
> >> about the changed Current_Features / Current_Settings.
> >
> > I'm fine with Set Node, but I don't know what you'd expect Set Router to
> > do. In router role we actively initiate an L2CAP Connect Request,
> > whereas the Node role is just about having an L2CAP server around (for
> > the purposes of this API - you obviously also need to get the
> > advertising right).
>
> And that is something that internally has to happen from the 6LoWPAN
> module to the core, but I consider that an internal detail.
I was actually thinking we'd let use space use the newly defined
advertising API for this instead of doing shortcuts in the kernel (which
also add complexity there since this would require extra inter-module
communication). This would be similar to how BR/EDR profiles need to
independently register an SDP record and start server L2CAP or RFCOMM
sockets.
I'm open to reconsidering this, but reusing the existing advertising API
will probably result in the simplest code both in user space and the
kernel (no extra stuff for the kernel and for user space I suspect we'll
either way have a simple way for bluetoothd plugins to register LE
UUIDs).
> >>> + This event indicates that a successful 6LoWPAN connection has
> >>> + been created to the remote device.
> >>> +
> >>> + Possible values for the Address_Type parameter:
> >>> + 1 LE Public
> >>> + 2 LE Random
> >>> +
> >>> + For devices using resolvable random addresses with a known
> >>> + identity resolving key, the Address and Address_Type will
> >>> + contain the identity information.
> >>> +
> >>> + The Role parameter indicates which role the local system has for
> >>> + the connection. The parameter has the following possible values:
> >>> + 0x00 Node
> >>> + 0x01 Router
> >>
> >> Why local system? Don't we actually know that information. I am really
> >> not getting this event.
> >
> > I put this info there so 3rd party apps (think btmon or 'btmgmt monitor'
> > can track what's happening). For a single user (bluetoothd) you're right
> > that this event would only be needed to notify of new connections when
> > we're in the Node role. For Router we'd know the new connection from a
> > successful Connect command response.
>
> It is also all IP based. I do not even think this will make any difference.
Not sure what you're saying here. That it was a mistake of the IPSP spec
to define two separate roles, that in practice everyone is equal in
6lowpan? I don't think I agree with that.
Johan
Hi Johan,
>>> +Read Controller Index List Command
>>> +==================================
>>> +
>>> + Command Code: 0x0003
>>> + Controller Index: <non-controller>
>>> + Command Parameters:
>>> + Return Parameters: Num_Controllers (2 Octets)
>>> + Controller_Index[i] (2 Octets)
>>> + Supported_Features[i] (4 Octets)
>>> +
>>> + This command returns the list of currently known controllers
>>> + that can be used for 6LoWPAN connections. Controllers added or
>>> + removed after calling this command can be monitored using the
>>> + Index Added and Index Removed events.
>>> +
>>> + The Supported_Features is a bitmask with the following available
>>> + bits:
>>> +
>>> + 0 Node Role Supported
>>> + 1 Router Role Supported
>>> +
>>> + This command generates a Command Complete event on success or
>>> + a Command Status event on failure.
>>
>> so my preference is to keep command codes 0x0001 - 0x0003 exactly the
>> same as with what we have in the current GAP part of the API. That
>> means this should just return the list of controller indexes.
>
> For 0x0001 and 0x0002 I agree, but I'm not convinced for the rest. If
> the information we need to return is rather simple we can avoid
> unnecessary messaging and context switches if we just include it along
> with the index. So I'd consider going with the "Extended" style index
> commands and events that we just recently introduced to the GAP channel
> as well.
the extended read index list is totally different here. Features do not belong in here. And this is actually more like Supported_Settings and Current_Settings.
> If we find that we need more information in the future we can always
> then add a Read Info command.
Not really. We add that from the start. Worked fine for a long time for us and I rather not break with a design that we know works.
>> This also means that event codes 0x0001 - 0x0005 kept exactly the
>> same.
>
> For the index added event I'd still consider having simple info there.
> As for the HW error, that just makes no sense at all to me. We're
> operating purely on an L2CAP level here and that error is an HCI level
> detail. The kernel already handles that by resetting the controller so
> user space will either way get the appropriate "disconnected" events for
> the 6lowpan connection.
A client that only operates on the 6LoWPAN side of things still wants to know if a hardware error happened. Otherwise you end up having to open two sockets.
>> And that should be kept the same for any future channel we are
>> adding support for. The basic commands and events have served us
>> really well.
>
> Just because it works well doesn't mean that we shouldn't think a bit
> whether we can do better, especially since we're operating in a slightly
> different context. We can't anymore change the GAP channel but we can
> try to get new ones right from the start. Considering providing some
> extra info along with the index is one example. That said, I don't have
> a super strong opinion either way - I was simply trying to keep this new
> interface as short & simple as possible.
Since I have written the 4th client that utilizes management style API now, I do have rather strong opinion here. Things that actually work very well are things you want to keep exactly that way.
>> With this in mind the first specific command would be the Read
>> Controller Info type command with 0x0004 that then. It will return the
>> list of Supported_Features and Current_Features and maybe some extra
>> information about the 6LoWPAN side of things. Doing it that way has
>> also served us well to communicate states across the clients easily.
>
> I agree with having a similar supported vs current settings/features
> split, so I'll fix at least that for the next revision.
>
>>> +Connect Command
>>> +===============
>>> +
>>> + Command Code: 0x0004
>>> + Controller Index: <controller id>
>>> + Command Parameters: Address (6 Octets)
>>> + Address_Type (1 Octet)
>>> + Return Parameters: Address (6 Octets)
>>> + Address_Type (1 Octet)
>>> + Network_Interface (16 Octets)
>>
>> Kernel interfaces should return the 4 octet ifindex. Not the network
>> interface name. Also this is most likely pretty much wrong in the
>> connect context. Per controller you only have a single 6LoWPAN network
>> interface anyway. That sounds more like something that should be
>> generic in the read info details.
>
> Not sure if you realized, but I took this straight from the BNEP ioctl
> where there's a "char device[16]" return parameter in the
> bnep_connadd_req struct. If the ifindex is a general convention in
> kernel APIs then I'm fine with that.
And that is a clear mistake in the BNEP ioctl that we can not fix anymore. No need to repeat this mistake.
>> I spent a lot of time to explain the Address_Type parameters in the
>> other document, we might better actually copy that over here. And
>> clearly say which ones are supported and which ones reserved.
>
> Sure.
>
>>> +Start Node Command
>>> +==================
>>> +
>>> + Command Code: 0x0005
>>> + Controller Index: <controller id>
>>> + Command Parameters:
>>> + Return Parameters:
>>> +
>>> + This command is used create a 6LoWPAN Node for a specified
>>> + controller.
>>> +
>>> + This command generates a Command Complete event on success or
>>> + a Command Status event on failure.
>>> +
>>> + Possible errors: Busy
>>> + Invalid Index
>>> +
>>> +
>>> +Stop Node Command
>>> +=================
>>> +
>>> + Command Code: 0x0006
>>> + Controller Index: <controller id>
>>> + Command Parameters:
>>> + Return Parameters:
>>> +
>>> + This command is used to stop a 6LoWPAN Node for a specified
>>> + controller.
>>> +
>>> + This command generates a Command Complete event on success or
>>> + a Command Status event on failure.
>>> +
>>> + Possible errors: Rejected
>>> + Invalid Index
>>
>> Generally I think Set Node and Set Router seems to be the more obvious
>> commands here. And they could have then also returned the information
>> about the changed Current_Features / Current_Settings.
>
> I'm fine with Set Node, but I don't know what you'd expect Set Router to
> do. In router role we actively initiate an L2CAP Connect Request,
> whereas the Node role is just about having an L2CAP server around (for
> the purposes of this API - you obviously also need to get the
> advertising right).
And that is something that internally has to happen from the 6LoWPAN module to the core, but I consider that an internal detail.
>>> +Command Status Event
>>> +====================
>>> +
>>> + Event Code: 0x0002
>>> + Controller Index: <controller id> or <non-controller>
>>> + Event Parameters: Command_Opcode (2 Octets)
>>> + Status (1 Octet)
>>> +
>>> + The command status event is used to indicate an early status for
>>> + a pending command. In the case that the status indicates failure
>>> + (anything else except success status) this also means that the
>>> + command has finished executing.
>>
>> I would include the Controller Error event to allow us to indicate
>> controller errors.
>
> As I mentioned earlier the HW error really makes no sense at all to me,
> neither from the API perspective nor from the implementation.
See my comment above. If something goes wrong, you might want to know that this happened.
>
>>> +Index Added Event
>>> +=================
>>> +
>>> + Event Code: 0x0003
>>> + Controller Index: <controller id>
>>> + Event Parameters: Supported_Features (4 octets)
>>> +
>>> + This event indicates that a new controller has been added to the
>>> + system that can be used for 6LoWPAN.
>>> +
>>> + The Supported_Features is a bitmask with the following available
>>> + bits:
>>> +
>>> + 0 Node Role Supported
>>> + 1 Router Role Supported
>>> +
>>> +
>>> +Index Removed Event
>>> +===================
>>> +
>>> + Event Code: 0x0004
>>> + Controller Index: <controller id>
>>> + Event Parameters:
>>> +
>>> + This event indicates that a 6LoWPAN-capable controller has been
>>> + removed from the system.
>>
>> As said above, these two I would have kept exactly as is with the
>> current interface. Just tell about the new index. That has been
>> working out nicely.
>
> I'd like to hear a good argument for why we wouldn't try to avoid the
> extra messaging and context switching by providing some basic info in
> addition to the index.
Because you will do that anyway. There is nothing to save here. This makes it simpler. The information you need come in a simple call. And if you call it with giving --index to it, then you still get the same info.
>> We might actually want to move the whole common set of parameters into
>> a common document that provides the basics and these common commands
>> and events. Then each individual document can focus on its part.
>
> Yep, that would make sense, as long as we can agree on what the common
> part is :)
>
>>> +6LoWPAN Connected Event
>>> +=======================
>>> +
>>> + Event Code: 0x0005
>>> + Controller Index: <controller id>
>>> + Event Parameters: Address (6 Octets)
>>> + Address_Type (1 Octet)
>>> + Role (1 Octet)
>>> + Interface_Name (16 Octets)
>>
>> The interface makes really no sense here. That is fixed and always the
>> same for the controller id. These information need to be provided
>> differently in the common info set.
>
> I was thinking that it'd give some future flexibility if we end up
> splitting this up into one interface per connection at some point, but
> I'm fine with putting this in the controller info part of the API.
>
> Btw, do we expect to have a single interface per controller even when
> the controller is acting simultaneously in router and node roles?
That is how 6LoWPAN is defined. It is an IP level thing. All connections feed into the same netdev.
>
>>> + This event indicates that a successful 6LoWPAN connection has
>>> + been created to the remote device.
>>> +
>>> + Possible values for the Address_Type parameter:
>>> + 1 LE Public
>>> + 2 LE Random
>>> +
>>> + For devices using resolvable random addresses with a known
>>> + identity resolving key, the Address and Address_Type will
>>> + contain the identity information.
>>> +
>>> + The Role parameter indicates which role the local system has for
>>> + the connection. The parameter has the following possible values:
>>> + 0x00 Node
>>> + 0x01 Router
>>
>> Why local system? Don't we actually know that information. I am really
>> not getting this event.
>
> I put this info there so 3rd party apps (think btmon or 'btmgmt monitor'
> can track what's happening). For a single user (bluetoothd) you're right
> that this event would only be needed to notify of new connections when
> we're in the Node role. For Router we'd know the new connection from a
> successful Connect command response.
It is also all IP based. I do not even think this will make any difference.
>>> +6LoWPAN Disconnected Event
>>> +==========================
>>> +
>>> + Event Code: 0x0006
>>> + Controller Index: <controller id>
>>> + Event Parameters: Address (6 Octets)
>>> + Address_Type (1 Octet)
>>> + Role (1 Octet)
>>> + Reason (1 Octet)
>>> +
>>> + This event indicates that the 6LoWPAN connection was lost to a
>>> + remote device.
>>> +
>>> + Possible values for the Address_Type parameter:
>>> + 1 LE Public
>>> + 2 LE Random
>>> +
>>> + For devices using resolvable random addresses with a known
>>> + identity resolving key, the Address and Address_Type will
>>> + contain the identity information.
>>> +
>>> + The Role parameter indicates which role the local system has for
>>> + the connection. The parameter has the following possible values:
>>> + 0x00 Node
>>> + 0x01 Router
>>> +
>>> + Possible values for the Reason parameter:
>>> + 0 Unspecified
>>> + 1 Connection timeout
>>> + 2 Connection terminated by local host
>>> + 3 Connection terminated by remote host
>>
>> The obvious missing event is when Current_Features change or the
>> service as node or router has been activated. We really want to
>> communicate this kind of information.
>
> Agreed. I'll add that.
Regards
Marcel
Hi Marcel,
On Thu, Mar 19, 2015, Marcel Holtmann wrote:
> > +Read Controller Index List Command
> > +==================================
> > +
> > + Command Code: 0x0003
> > + Controller Index: <non-controller>
> > + Command Parameters:
> > + Return Parameters: Num_Controllers (2 Octets)
> > + Controller_Index[i] (2 Octets)
> > + Supported_Features[i] (4 Octets)
> > +
> > + This command returns the list of currently known controllers
> > + that can be used for 6LoWPAN connections. Controllers added or
> > + removed after calling this command can be monitored using the
> > + Index Added and Index Removed events.
> > +
> > + The Supported_Features is a bitmask with the following available
> > + bits:
> > +
> > + 0 Node Role Supported
> > + 1 Router Role Supported
> > +
> > + This command generates a Command Complete event on success or
> > + a Command Status event on failure.
>
> so my preference is to keep command codes 0x0001 - 0x0003 exactly the
> same as with what we have in the current GAP part of the API. That
> means this should just return the list of controller indexes.
For 0x0001 and 0x0002 I agree, but I'm not convinced for the rest. If
the information we need to return is rather simple we can avoid
unnecessary messaging and context switches if we just include it along
with the index. So I'd consider going with the "Extended" style index
commands and events that we just recently introduced to the GAP channel
as well.
If we find that we need more information in the future we can always
then add a Read Info command.
> This also means that event codes 0x0001 - 0x0005 kept exactly the
> same.
For the index added event I'd still consider having simple info there.
As for the HW error, that just makes no sense at all to me. We're
operating purely on an L2CAP level here and that error is an HCI level
detail. The kernel already handles that by resetting the controller so
user space will either way get the appropriate "disconnected" events for
the 6lowpan connection.
> And that should be kept the same for any future channel we are
> adding support for. The basic commands and events have served us
> really well.
Just because it works well doesn't mean that we shouldn't think a bit
whether we can do better, especially since we're operating in a slightly
different context. We can't anymore change the GAP channel but we can
try to get new ones right from the start. Considering providing some
extra info along with the index is one example. That said, I don't have
a super strong opinion either way - I was simply trying to keep this new
interface as short & simple as possible.
> With this in mind the first specific command would be the Read
> Controller Info type command with 0x0004 that then. It will return the
> list of Supported_Features and Current_Features and maybe some extra
> information about the 6LoWPAN side of things. Doing it that way has
> also served us well to communicate states across the clients easily.
I agree with having a similar supported vs current settings/features
split, so I'll fix at least that for the next revision.
> > +Connect Command
> > +===============
> > +
> > + Command Code: 0x0004
> > + Controller Index: <controller id>
> > + Command Parameters: Address (6 Octets)
> > + Address_Type (1 Octet)
> > + Return Parameters: Address (6 Octets)
> > + Address_Type (1 Octet)
> > + Network_Interface (16 Octets)
>
> Kernel interfaces should return the 4 octet ifindex. Not the network
> interface name. Also this is most likely pretty much wrong in the
> connect context. Per controller you only have a single 6LoWPAN network
> interface anyway. That sounds more like something that should be
> generic in the read info details.
Not sure if you realized, but I took this straight from the BNEP ioctl
where there's a "char device[16]" return parameter in the
bnep_connadd_req struct. If the ifindex is a general convention in
kernel APIs then I'm fine with that.
> I spent a lot of time to explain the Address_Type parameters in the
> other document, we might better actually copy that over here. And
> clearly say which ones are supported and which ones reserved.
Sure.
> > +Start Node Command
> > +==================
> > +
> > + Command Code: 0x0005
> > + Controller Index: <controller id>
> > + Command Parameters:
> > + Return Parameters:
> > +
> > + This command is used create a 6LoWPAN Node for a specified
> > + controller.
> > +
> > + This command generates a Command Complete event on success or
> > + a Command Status event on failure.
> > +
> > + Possible errors: Busy
> > + Invalid Index
> > +
> > +
> > +Stop Node Command
> > +=================
> > +
> > + Command Code: 0x0006
> > + Controller Index: <controller id>
> > + Command Parameters:
> > + Return Parameters:
> > +
> > + This command is used to stop a 6LoWPAN Node for a specified
> > + controller.
> > +
> > + This command generates a Command Complete event on success or
> > + a Command Status event on failure.
> > +
> > + Possible errors: Rejected
> > + Invalid Index
>
> Generally I think Set Node and Set Router seems to be the more obvious
> commands here. And they could have then also returned the information
> about the changed Current_Features / Current_Settings.
I'm fine with Set Node, but I don't know what you'd expect Set Router to
do. In router role we actively initiate an L2CAP Connect Request,
whereas the Node role is just about having an L2CAP server around (for
the purposes of this API - you obviously also need to get the
advertising right).
> > +Command Status Event
> > +====================
> > +
> > + Event Code: 0x0002
> > + Controller Index: <controller id> or <non-controller>
> > + Event Parameters: Command_Opcode (2 Octets)
> > + Status (1 Octet)
> > +
> > + The command status event is used to indicate an early status for
> > + a pending command. In the case that the status indicates failure
> > + (anything else except success status) this also means that the
> > + command has finished executing.
>
> I would include the Controller Error event to allow us to indicate
> controller errors.
As I mentioned earlier the HW error really makes no sense at all to me,
neither from the API perspective nor from the implementation.
> > +Index Added Event
> > +=================
> > +
> > + Event Code: 0x0003
> > + Controller Index: <controller id>
> > + Event Parameters: Supported_Features (4 octets)
> > +
> > + This event indicates that a new controller has been added to the
> > + system that can be used for 6LoWPAN.
> > +
> > + The Supported_Features is a bitmask with the following available
> > + bits:
> > +
> > + 0 Node Role Supported
> > + 1 Router Role Supported
> > +
> > +
> > +Index Removed Event
> > +===================
> > +
> > + Event Code: 0x0004
> > + Controller Index: <controller id>
> > + Event Parameters:
> > +
> > + This event indicates that a 6LoWPAN-capable controller has been
> > + removed from the system.
>
> As said above, these two I would have kept exactly as is with the
> current interface. Just tell about the new index. That has been
> working out nicely.
I'd like to hear a good argument for why we wouldn't try to avoid the
extra messaging and context switching by providing some basic info in
addition to the index.
> We might actually want to move the whole common set of parameters into
> a common document that provides the basics and these common commands
> and events. Then each individual document can focus on its part.
Yep, that would make sense, as long as we can agree on what the common
part is :)
> > +6LoWPAN Connected Event
> > +=======================
> > +
> > + Event Code: 0x0005
> > + Controller Index: <controller id>
> > + Event Parameters: Address (6 Octets)
> > + Address_Type (1 Octet)
> > + Role (1 Octet)
> > + Interface_Name (16 Octets)
>
> The interface makes really no sense here. That is fixed and always the
> same for the controller id. These information need to be provided
> differently in the common info set.
I was thinking that it'd give some future flexibility if we end up
splitting this up into one interface per connection at some point, but
I'm fine with putting this in the controller info part of the API.
Btw, do we expect to have a single interface per controller even when
the controller is acting simultaneously in router and node roles?
> > + This event indicates that a successful 6LoWPAN connection has
> > + been created to the remote device.
> > +
> > + Possible values for the Address_Type parameter:
> > + 1 LE Public
> > + 2 LE Random
> > +
> > + For devices using resolvable random addresses with a known
> > + identity resolving key, the Address and Address_Type will
> > + contain the identity information.
> > +
> > + The Role parameter indicates which role the local system has for
> > + the connection. The parameter has the following possible values:
> > + 0x00 Node
> > + 0x01 Router
>
> Why local system? Don't we actually know that information. I am really
> not getting this event.
I put this info there so 3rd party apps (think btmon or 'btmgmt monitor'
can track what's happening). For a single user (bluetoothd) you're right
that this event would only be needed to notify of new connections when
we're in the Node role. For Router we'd know the new connection from a
successful Connect command response.
> > +6LoWPAN Disconnected Event
> > +==========================
> > +
> > + Event Code: 0x0006
> > + Controller Index: <controller id>
> > + Event Parameters: Address (6 Octets)
> > + Address_Type (1 Octet)
> > + Role (1 Octet)
> > + Reason (1 Octet)
> > +
> > + This event indicates that the 6LoWPAN connection was lost to a
> > + remote device.
> > +
> > + Possible values for the Address_Type parameter:
> > + 1 LE Public
> > + 2 LE Random
> > +
> > + For devices using resolvable random addresses with a known
> > + identity resolving key, the Address and Address_Type will
> > + contain the identity information.
> > +
> > + The Role parameter indicates which role the local system has for
> > + the connection. The parameter has the following possible values:
> > + 0x00 Node
> > + 0x01 Router
> > +
> > + Possible values for the Reason parameter:
> > + 0 Unspecified
> > + 1 Connection timeout
> > + 2 Connection terminated by local host
> > + 3 Connection terminated by remote host
>
> The obvious missing event is when Current_Features change or the
> service as node or router has been activated. We really want to
> communicate this kind of information.
Agreed. I'll add that.
Johan
Hi Johan,
> ---
> Makefile.am | 2 +-
> doc/6lowpan-api.txt | 291 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 292 insertions(+), 1 deletion(-)
> create mode 100644 doc/6lowpan-api.txt
>
> diff --git a/Makefile.am b/Makefile.am
> index 90bb86baefdc..d6726dde40a0 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -239,7 +239,7 @@ EXTRA_DIST += $(test_scripts)
> EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
> doc/test-coverage.txt doc/settings-storage.txt
>
> -EXTRA_DIST += doc/mgmt-api.txt \
> +EXTRA_DIST += doc/mgmt-api.txt doc/6lowpan-api.txt \
> doc/adapter-api.txt doc/device-api.txt \
> doc/agent-api.txt doc/profile-api.txt \
> doc/network-api.txt doc/media-api.txt \
> diff --git a/doc/6lowpan-api.txt b/doc/6lowpan-api.txt
> new file mode 100644
> index 000000000000..03dffbff8968
> --- /dev/null
> +++ b/doc/6lowpan-api.txt
> @@ -0,0 +1,291 @@
> +6LoWPAN Management API
> +**********************
> +
> +Copyright (C) 2015 Intel Corporation
> +
> +
> +Overview
> +========
> +
> +The 6LoWPAN Management API follows largely the same principles as the
> +main Bluetooth Management API described in mgmt-api.txt. The main
> +difference is a separate namespace for command and event codes,
> +distinguished by using HCI_CHANNEL_6LOWPAN rather than
> +HCI_CHANNEL_CONTROL when creating the mgmt socket.
> +
> +
> +Read 6LoWPAN Version Information Command
> +========================================
> +
> + Command Code: 0x0001
> + Controller Index: <non-controller>
> + Command Parameters:
> + Return Parameters: Version (1 Octets)
> + Revision (2 Octets)
> +
> + This command returns the 6LoWPAN version and revision.
> + Besides, being informational the information can be used to
> + determine whether certain behavior has changed or bugs fixed
> + when interacting with the kernel.
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
> +
> +
> +Read 6LoWPAN Supported Commands Command
> +========================================
> +
> + Command Code: 0x0002
> + Controller Index: <non-controller>
> + Command Parameters:
> + Return Parameters: Num_Of_Commands (2 Octets)
> + Num_Of_Events (2 Octets)
> + Command1 (2 Octets)
> + Command2 (2 Octets)
> + ...
> + Event1 (2 Octets)
> + Event2 (2 Octets)
> + ...
> +
> + This command returns the list of supported 6LoWPAN commands
> + and events.
> +
> + The commands Read 6LoWPAN Version Information and Read
> + 6LoWPAN Supported Commands are not included in this list.
> + Both commands are always supported and mandatory.
> +
> + The events Command Status and Command Complete are not included
> + in this list. Both are implicit and mandatory.
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
> +
> +
> +Read Controller Index List Command
> +==================================
> +
> + Command Code: 0x0003
> + Controller Index: <non-controller>
> + Command Parameters:
> + Return Parameters: Num_Controllers (2 Octets)
> + Controller_Index[i] (2 Octets)
> + Supported_Features[i] (4 Octets)
> +
> + This command returns the list of currently known controllers
> + that can be used for 6LoWPAN connections. Controllers added or
> + removed after calling this command can be monitored using the
> + Index Added and Index Removed events.
> +
> + The Supported_Features is a bitmask with the following available
> + bits:
> +
> + 0 Node Role Supported
> + 1 Router Role Supported
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
so my preference is to keep command codes 0x0001 - 0x0003 exactly the same as with what we have in the current GAP part of the API. That means this should just return the list of controller indexes.
This also means that event codes 0x0001 - 0x0005 kept exactly the same. And that should be kept the same for any future channel we are adding support for. The basic commands and events have served us really well.
With this in mind the first specific command would be the Read Controller Info type command with 0x0004 that then. It will return the list of Supported_Features and Current_Features and maybe some extra information about the 6LoWPAN side of things. Doing it that way has also served us well to communicate states across the clients easily.
> +
> +
> +Connect Command
> +===============
> +
> + Command Code: 0x0004
> + Controller Index: <controller id>
> + Command Parameters: Address (6 Octets)
> + Address_Type (1 Octet)
> + Return Parameters: Address (6 Octets)
> + Address_Type (1 Octet)
> + Network_Interface (16 Octets)
Kernel interfaces should return the 4 octet ifindex. Not the network interface name. Also this is most likely pretty much wrong in the connect context. Per controller you only have a single 6LoWPAN network interface anyway. That sounds more like something that should be generic in the read info details.
I spent a lot of time to explain the Address_Type parameters in the other document, we might better actually copy that over here. And clearly say which ones are supported and which ones reserved.
> +
> + This command is used to connect to a remote 6LoWPAN Node.
> +
> + The returned Network_Interface parameter is a nul-terminated
> + string containing the created network interface name.
> +
> + This command generates a Command Complete event on success
> + or failure.
> +
> + Possible errors: Busy
> + Invalid Parameters
> + Not Powered
> + Invalid Index
> +
> +
> +Disconnect Command
> +==================
> +
> + Command Code: 0x0005
> + Controller Index: <controller id>
> + Command Parameters: Address (6 Octets)
> + Address_Type (1 Octet)
> + Return Parameters: Address (6 Octets)
> + Address_Type (1 Octet)
> +
> + This command is used to disconnect from a remote 6LoWPAN Node.
> +
> + This command generates a Command Complete event on success
> + or failure.
> +
> + Possible errors: Busy
> + Not Connected
> + Invalid Parameters
> + Not Powered
> + Invalid Index
> +
> +
> +Start Node Command
> +==================
> +
> + Command Code: 0x0005
> + Controller Index: <controller id>
> + Command Parameters:
> + Return Parameters:
> +
> + This command is used create a 6LoWPAN Node for a specified
> + controller.
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
> +
> + Possible errors: Busy
> + Invalid Index
> +
> +
> +Stop Node Command
> +=================
> +
> + Command Code: 0x0006
> + Controller Index: <controller id>
> + Command Parameters:
> + Return Parameters:
> +
> + This command is used to stop a 6LoWPAN Node for a specified
> + controller.
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
> +
> + Possible errors: Rejected
> + Invalid Index
Generally I think Set Node and Set Router seems to be the more obvious commands here. And they could have then also returned the information about the changed Current_Features / Current_Settings.
> +
> +
> +Command Complete Event
> +======================
> +
> + Event Code: 0x0001
> + Controller Index: <controller id> or <non-controller>
> + Event Parameters: Command_Opcode (2 Octets)
> + Status (1 Octet)
> + Return_Parameters
> +
> + This event is an indication that a command has completed. The
> + fixed set of parameters includes the opcode to identify the
> + command that completed as well as a status value to indicate
> + success or failure. The rest of the parameters are command
> + specific and documented in the section for each command
> + separately.
> +
> +
> +Command Status Event
> +====================
> +
> + Event Code: 0x0002
> + Controller Index: <controller id> or <non-controller>
> + Event Parameters: Command_Opcode (2 Octets)
> + Status (1 Octet)
> +
> + The command status event is used to indicate an early status for
> + a pending command. In the case that the status indicates failure
> + (anything else except success status) this also means that the
> + command has finished executing.
I would include the Controller Error event to allow us to indicate controller errors.
> +
> +
> +Index Added Event
> +=================
> +
> + Event Code: 0x0003
> + Controller Index: <controller id>
> + Event Parameters: Supported_Features (4 octets)
> +
> + This event indicates that a new controller has been added to the
> + system that can be used for 6LoWPAN.
> +
> + The Supported_Features is a bitmask with the following available
> + bits:
> +
> + 0 Node Role Supported
> + 1 Router Role Supported
> +
> +
> +Index Removed Event
> +===================
> +
> + Event Code: 0x0004
> + Controller Index: <controller id>
> + Event Parameters:
> +
> + This event indicates that a 6LoWPAN-capable controller has been
> + removed from the system.
As said above, these two I would have kept exactly as is with the current interface. Just tell about the new index. That has been working out nicely.
We might actually want to move the whole common set of parameters into a common document that provides the basics and these common commands and events. Then each individual document can focus on its part.
> +
> +
> +6LoWPAN Connected Event
> +=======================
> +
> + Event Code: 0x0005
> + Controller Index: <controller id>
> + Event Parameters: Address (6 Octets)
> + Address_Type (1 Octet)
> + Role (1 Octet)
> + Interface_Name (16 Octets)
The interface makes really no sense here. That is fixed and always the same for the controller id. These information need to be provided differently in the common info set.
> +
> + This event indicates that a successful 6LoWPAN connection has
> + been created to the remote device.
> +
> + Possible values for the Address_Type parameter:
> + 1 LE Public
> + 2 LE Random
> +
> + For devices using resolvable random addresses with a known
> + identity resolving key, the Address and Address_Type will
> + contain the identity information.
> +
> + The Role parameter indicates which role the local system has for
> + the connection. The parameter has the following possible values:
> + 0x00 Node
> + 0x01 Router
Why local system? Don't we actually know that information. I am really not getting this event.
> +
> + The Network_Interface parameter is a nul-terminated
> + string containing the created network interface name.
> +
> +
> +6LoWPAN Disconnected Event
> +==========================
> +
> + Event Code: 0x0006
> + Controller Index: <controller id>
> + Event Parameters: Address (6 Octets)
> + Address_Type (1 Octet)
> + Role (1 Octet)
> + Reason (1 Octet)
> +
> + This event indicates that the 6LoWPAN connection was lost to a
> + remote device.
> +
> + Possible values for the Address_Type parameter:
> + 1 LE Public
> + 2 LE Random
> +
> + For devices using resolvable random addresses with a known
> + identity resolving key, the Address and Address_Type will
> + contain the identity information.
> +
> + The Role parameter indicates which role the local system has for
> + the connection. The parameter has the following possible values:
> + 0x00 Node
> + 0x01 Router
> +
> + Possible values for the Reason parameter:
> + 0 Unspecified
> + 1 Connection timeout
> + 2 Connection terminated by local host
> + 3 Connection terminated by remote host
The obvious missing event is when Current_Features change or the service as node or router has been activated. We really want to communicate this kind of information.
Regards
Marcel
Hi Johan,
looks good now.
Acked-by: Jukka Rissanen <[email protected]>
On to, 2015-03-19 at 12:39 +0200, Johan Hedberg wrote:
> From: Johan Hedberg <[email protected]>
>
> ---
> Makefile.am | 2 +-
> doc/6lowpan-api.txt | 291 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 292 insertions(+), 1 deletion(-)
> create mode 100644 doc/6lowpan-api.txt
>
> diff --git a/Makefile.am b/Makefile.am
> index 90bb86baefdc..d6726dde40a0 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -239,7 +239,7 @@ EXTRA_DIST += $(test_scripts)
> EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
> doc/test-coverage.txt doc/settings-storage.txt
>
> -EXTRA_DIST += doc/mgmt-api.txt \
> +EXTRA_DIST += doc/mgmt-api.txt doc/6lowpan-api.txt \
> doc/adapter-api.txt doc/device-api.txt \
> doc/agent-api.txt doc/profile-api.txt \
> doc/network-api.txt doc/media-api.txt \
> diff --git a/doc/6lowpan-api.txt b/doc/6lowpan-api.txt
> new file mode 100644
> index 000000000000..03dffbff8968
> --- /dev/null
> +++ b/doc/6lowpan-api.txt
> @@ -0,0 +1,291 @@
> +6LoWPAN Management API
> +**********************
> +
> +Copyright (C) 2015 Intel Corporation
> +
> +
> +Overview
> +========
> +
> +The 6LoWPAN Management API follows largely the same principles as the
> +main Bluetooth Management API described in mgmt-api.txt. The main
> +difference is a separate namespace for command and event codes,
> +distinguished by using HCI_CHANNEL_6LOWPAN rather than
> +HCI_CHANNEL_CONTROL when creating the mgmt socket.
> +
> +
> +Read 6LoWPAN Version Information Command
> +========================================
> +
> + Command Code: 0x0001
> + Controller Index: <non-controller>
> + Command Parameters:
> + Return Parameters: Version (1 Octets)
> + Revision (2 Octets)
> +
> + This command returns the 6LoWPAN version and revision.
> + Besides, being informational the information can be used to
> + determine whether certain behavior has changed or bugs fixed
> + when interacting with the kernel.
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
> +
> +
> +Read 6LoWPAN Supported Commands Command
> +========================================
> +
> + Command Code: 0x0002
> + Controller Index: <non-controller>
> + Command Parameters:
> + Return Parameters: Num_Of_Commands (2 Octets)
> + Num_Of_Events (2 Octets)
> + Command1 (2 Octets)
> + Command2 (2 Octets)
> + ...
> + Event1 (2 Octets)
> + Event2 (2 Octets)
> + ...
> +
> + This command returns the list of supported 6LoWPAN commands
> + and events.
> +
> + The commands Read 6LoWPAN Version Information and Read
> + 6LoWPAN Supported Commands are not included in this list.
> + Both commands are always supported and mandatory.
> +
> + The events Command Status and Command Complete are not included
> + in this list. Both are implicit and mandatory.
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
> +
> +
> +Read Controller Index List Command
> +==================================
> +
> + Command Code: 0x0003
> + Controller Index: <non-controller>
> + Command Parameters:
> + Return Parameters: Num_Controllers (2 Octets)
> + Controller_Index[i] (2 Octets)
> + Supported_Features[i] (4 Octets)
> +
> + This command returns the list of currently known controllers
> + that can be used for 6LoWPAN connections. Controllers added or
> + removed after calling this command can be monitored using the
> + Index Added and Index Removed events.
> +
> + The Supported_Features is a bitmask with the following available
> + bits:
> +
> + 0 Node Role Supported
> + 1 Router Role Supported
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
> +
> +
> +Connect Command
> +===============
> +
> + Command Code: 0x0004
> + Controller Index: <controller id>
> + Command Parameters: Address (6 Octets)
> + Address_Type (1 Octet)
> + Return Parameters: Address (6 Octets)
> + Address_Type (1 Octet)
> + Network_Interface (16 Octets)
> +
> + This command is used to connect to a remote 6LoWPAN Node.
> +
> + The returned Network_Interface parameter is a nul-terminated
> + string containing the created network interface name.
> +
> + This command generates a Command Complete event on success
> + or failure.
> +
> + Possible errors: Busy
> + Invalid Parameters
> + Not Powered
> + Invalid Index
> +
> +
> +Disconnect Command
> +==================
> +
> + Command Code: 0x0005
> + Controller Index: <controller id>
> + Command Parameters: Address (6 Octets)
> + Address_Type (1 Octet)
> + Return Parameters: Address (6 Octets)
> + Address_Type (1 Octet)
> +
> + This command is used to disconnect from a remote 6LoWPAN Node.
> +
> + This command generates a Command Complete event on success
> + or failure.
> +
> + Possible errors: Busy
> + Not Connected
> + Invalid Parameters
> + Not Powered
> + Invalid Index
> +
> +
> +Start Node Command
> +==================
> +
> + Command Code: 0x0005
> + Controller Index: <controller id>
> + Command Parameters:
> + Return Parameters:
> +
> + This command is used create a 6LoWPAN Node for a specified
> + controller.
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
> +
> + Possible errors: Busy
> + Invalid Index
> +
> +
> +Stop Node Command
> +=================
> +
> + Command Code: 0x0006
> + Controller Index: <controller id>
> + Command Parameters:
> + Return Parameters:
> +
> + This command is used to stop a 6LoWPAN Node for a specified
> + controller.
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
> +
> + Possible errors: Rejected
> + Invalid Index
> +
> +
> +Command Complete Event
> +======================
> +
> + Event Code: 0x0001
> + Controller Index: <controller id> or <non-controller>
> + Event Parameters: Command_Opcode (2 Octets)
> + Status (1 Octet)
> + Return_Parameters
> +
> + This event is an indication that a command has completed. The
> + fixed set of parameters includes the opcode to identify the
> + command that completed as well as a status value to indicate
> + success or failure. The rest of the parameters are command
> + specific and documented in the section for each command
> + separately.
> +
> +
> +Command Status Event
> +====================
> +
> + Event Code: 0x0002
> + Controller Index: <controller id> or <non-controller>
> + Event Parameters: Command_Opcode (2 Octets)
> + Status (1 Octet)
> +
> + The command status event is used to indicate an early status for
> + a pending command. In the case that the status indicates failure
> + (anything else except success status) this also means that the
> + command has finished executing.
> +
> +
> +Index Added Event
> +=================
> +
> + Event Code: 0x0003
> + Controller Index: <controller id>
> + Event Parameters: Supported_Features (4 octets)
> +
> + This event indicates that a new controller has been added to the
> + system that can be used for 6LoWPAN.
> +
> + The Supported_Features is a bitmask with the following available
> + bits:
> +
> + 0 Node Role Supported
> + 1 Router Role Supported
> +
> +
> +Index Removed Event
> +===================
> +
> + Event Code: 0x0004
> + Controller Index: <controller id>
> + Event Parameters:
> +
> + This event indicates that a 6LoWPAN-capable controller has been
> + removed from the system.
> +
> +
> +6LoWPAN Connected Event
> +=======================
> +
> + Event Code: 0x0005
> + Controller Index: <controller id>
> + Event Parameters: Address (6 Octets)
> + Address_Type (1 Octet)
> + Role (1 Octet)
> + Interface_Name (16 Octets)
> +
> + This event indicates that a successful 6LoWPAN connection has
> + been created to the remote device.
> +
> + Possible values for the Address_Type parameter:
> + 1 LE Public
> + 2 LE Random
> +
> + For devices using resolvable random addresses with a known
> + identity resolving key, the Address and Address_Type will
> + contain the identity information.
> +
> + The Role parameter indicates which role the local system has for
> + the connection. The parameter has the following possible values:
> + 0x00 Node
> + 0x01 Router
> +
> + The Network_Interface parameter is a nul-terminated
> + string containing the created network interface name.
> +
> +
> +6LoWPAN Disconnected Event
> +==========================
> +
> + Event Code: 0x0006
> + Controller Index: <controller id>
> + Event Parameters: Address (6 Octets)
> + Address_Type (1 Octet)
> + Role (1 Octet)
> + Reason (1 Octet)
> +
> + This event indicates that the 6LoWPAN connection was lost to a
> + remote device.
> +
> + Possible values for the Address_Type parameter:
> + 1 LE Public
> + 2 LE Random
> +
> + For devices using resolvable random addresses with a known
> + identity resolving key, the Address and Address_Type will
> + contain the identity information.
> +
> + The Role parameter indicates which role the local system has for
> + the connection. The parameter has the following possible values:
> + 0x00 Node
> + 0x01 Router
> +
> + Possible values for the Reason parameter:
> + 0 Unspecified
> + 1 Connection timeout
> + 2 Connection terminated by local host
> + 3 Connection terminated by remote host
Cheers,
Jukka