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..6c4e2fb7201a
--- /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 server.
+
+ 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
+ a Command Status event on 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 server.
+
+ This command generates a Command Complete event on success or
+ a Command Status event on failure.
+
+ Possible errors: Busy
+ Not Connected
+ Invalid Parameters
+ Not Powered
+ Invalid Index
+
+
+Start Server Command
+====================
+
+ Command Code: 0x0005
+ Controller Index: <controller id>
+ Command Parameters:
+ Return Parameters:
+
+ This command is used to start a 6LoWPAN server 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 Server Command
+===================
+
+ Command Code: 0x0006
+ Controller Index: <controller id>
+ Command Parameters:
+ Return Parameters:
+
+ This command is used to stop a 6LoWPAN server 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 Jukka,
On Thu, Mar 19, 2015, Jukka Rissanen wrote:
> > +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 server.
>
> We should probably say "... remote 6LoWPAN node" here instead.
Indeed. I'll change it.
> > +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 server.
>
> Ditto
Sure.
> > +Start Server Command
>
> The specification talks about "Router" so should we use same terminology
> here instead of "Server"?
Actually this would be the Node role. So I'll rename it to 'Start Node
Command'.
> > +Stop Server Command
>
> Ditto.
Sure.
Johan
Hi Szymon,
On Thu, Mar 19, 2015, Szymon Janc wrote:
> > +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 server.
> > +
> > + 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
> > + a Command Status event on failure.
>
> Shouldn't this always return command complete? ie for userspace to be
> able to easily handle multiple connect commands?
> (currently mgmt lib handles only 1 command at once but...)
Good catch. I'll fix it in v2.
> > +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 server.
> > +
> > + This command generates a Command Complete event on success or
> > + a Command Status event on failure.
>
> Same here.
Will fix.
Johan
Hi Johan,
looks good, except for couple of comments below
On to, 2015-03-19 at 11:10 +0200, Johan Hedberg wrote:
> From: Johan Hedberg <[email protected]>
>
> ---
> +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 server.
We should probably say "... remote 6LoWPAN node" here instead.
> +
> + 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
> + a Command Status event on 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 server.
Ditto
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
> +
> + Possible errors: Busy
> + Not Connected
> + Invalid Parameters
> + Not Powered
> + Invalid Index
> +
> +
> +Start Server Command
The specification talks about "Router" so should we use same terminology
here instead of "Server"?
> +====================
> +
> + Command Code: 0x0005
> + Controller Index: <controller id>
> + Command Parameters:
> + Return Parameters:
> +
> + This command is used to start a 6LoWPAN server 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 Server Command
Ditto.
> +===================
> +
> + Command Code: 0x0006
> + Controller Index: <controller id>
> + Command Parameters:
> + Return Parameters:
> +
> + This command is used to stop a 6LoWPAN server 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
> +
Cheers,
Jukka
Hi Johan,
On Thursday 19 of March 2015 11:10:30 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..6c4e2fb7201a
> --- /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 server.
> +
> + 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
> + a Command Status event on failure.
Shouldn't this always return command complete? ie for userspace to be
able to easily handle multiple connect commands?
(currently mgmt lib handles only 1 command at once but...)
> +
> + 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 server.
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
Same here.
> +
> + Possible errors: Busy
> + Not Connected
> + Invalid Parameters
> + Not Powered
> + Invalid Index
> +
> +
> +Start Server Command
> +====================
> +
> + Command Code: 0x0005
> + Controller Index: <controller id>
> + Command Parameters:
> + Return Parameters:
> +
> + This command is used to start a 6LoWPAN server 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 Server Command
> +===================
> +
> + Command Code: 0x0006
> + Controller Index: <controller id>
> + Command Parameters:
> + Return Parameters:
> +
> + This command is used to stop a 6LoWPAN server 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
>
--
Best regards,
Szymon Janc