From ef542751f45b66e6d703c7ea6776bf61ce23333c Mon Sep 17 00:00:00 2001 From: Ryan Kurte Date: Fri, 15 Jun 2018 10:39:48 +1200 Subject: [PATCH 1/9] Initial Capture Information Block (CIB) concept. Adds CIB with location/orientation/velocity vectors, this is optionally attached to an IDB or referenced from EPBs. --- draft-tuexen-opsawg-pcapng.xml | 181 ++++++++++++++++++++++++++++++++- 1 file changed, 179 insertions(+), 2 deletions(-) diff --git a/draft-tuexen-opsawg-pcapng.xml b/draft-tuexen-opsawg-pcapng.xml index 7cceaa0..bed806a 100644 --- a/draft-tuexen-opsawg-pcapng.xml +++ b/draft-tuexen-opsawg-pcapng.xml @@ -145,10 +145,11 @@ Section Header Block Interface Description Block - Interface Statistics Block + Interface Statistics Block Enhanced Packet Block Simple Packet Block - Name Resolution Block + Name Resolution Block + Capture Information Block Custom Block @@ -267,6 +268,11 @@ capture has been made. If this appears in a file, an Interface Description Block is also required, before this block. + Capture Information Block: it + defines how to store some capture information (such as location, + orientation, velocity and associated errors, as well as rf frequencies + and channels) + Custom Block: it contains vendor-specific data in a portable fashion. @@ -1269,6 +1275,11 @@ Section Header 4 8 no + + epb_cib + 4 + 4 + no @@ -1306,6 +1317,10 @@ Section Header Example: '0'. + The epb_cib + option indicates the Capture Information Block ID to be associated + with this packet, allowing the addition of capture related metadata. + @@ -1828,6 +1843,168 @@ Section Header +
+ + The Capture Information Block (CIB) is used to support the addition + of metadata associated with capture interfaces or packets, including + location, orientation, velocity and related errors, as well as wireless + channel and medium options. + This block can be associated with a specific interface and applied to all + packets received on this interface, or to (a) specific packet(s). + If applied to an interface, this block effects all capture blocks following + until it is superseded by a new CIB applied to the same interface. + + + + Tools that write / read the capture file associate an incrementing 32-bit + number (starting from '0') to each Capture Information Block, called + the CIB ID for the CIB in question. This number is unique within each Section + and identifies the CIB that is referred to in an epb_cip option; it is only + unique inside the current section, so, two Sections can have different + CIBs identified by the same CIB ID values. This unique identifier + is referenced by other blocks, such as Enhanced Packet Blocks, to indicate the + CIB to which the block refers. + + + The format of the Capture Information Block is shown in . + +
+ + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +---------------------------------------------------------------+ + 0 | Block Type = 0x00000006 | + +---------------------------------------------------------------+ + 4 | Block Total Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + 8 / / + / Options (variable) / + / / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Block Total Length | + +---------------------------------------------------------------+ + +
+ The fields have the following meaning: + + + Block Type: The block type of the Capture Information Block is + 6. + + Block Total Length: total size of this block, as described in + . + + Options: optionally, a list of options (formatted according to + the rules defined in ) can be present. + + + + + All the statistic fields are defined as options in order to deal + with systems that do not have a complete set of statistics. Therefore, + In addition to the options defined in , + the following options are valid within this block: + + + Name + Code + Length + Multiple allowed? + + interface_id + 1 + 4 + no + + global_location + 2 + 12 + no + + global_location_error + 3 + 12 + no + + orientation + 4 + 12 + no + + orientation_error + 5 + 12 + no + + velocity + 6 + 12 + no + + velocity_error + 7 + 12 + no + + + + + + The + interface_id option specifies the interface these statistics refers + to; the correct interface will be the one whose Interface + Description Block (within the current Section of the file) is + identified by same number (see ) of + this field. + + The + cib_global_location option specifies the location of the packet + capture or interface; location is stored as three 32-bit floats + representing latitude and longitude in degrees, and altitude in + metres. + + Example: TODO + + The + global_location_error option specifies the error in location capture, + this is stored as three 32-bit floats in the same order and + representation as cib_location + + Example: TODO + + The + cib_orientation option specifies the location of the packet + capture or interface; location is stored as three 32-bit floats + representing yaw, pitch, and roll in radians. + + Example: TODO + + The + orientation_error option specifies the error in orientation capture, + this is stored as three 32-bit floats in the same order and + representation as cib_orientation + + Example: TODO + + The + cib_velocity option specifies the location of the packet + capture or interface; location is stored as three 32-bit floats + representing yaw, pitch, and roll in radians. + + Example: TODO + + The + cib_velocity_error option specifies the error in velocity capture, + this is stored as three 32-bit floats in the same order and + representation as cib_velocity + + Example: TODO + + + + +
From 7608aa602c8c9c6b1311ff0215c73c0db93e65ab Mon Sep 17 00:00:00 2001 From: Ryan Date: Sun, 17 Jun 2018 16:23:59 +1200 Subject: [PATCH 2/9] Copy edits --- draft-tuexen-opsawg-pcapng.xml | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/draft-tuexen-opsawg-pcapng.xml b/draft-tuexen-opsawg-pcapng.xml index bed806a..7448f51 100644 --- a/draft-tuexen-opsawg-pcapng.xml +++ b/draft-tuexen-opsawg-pcapng.xml @@ -145,11 +145,11 @@ Section Header Block Interface Description Block - Interface Statistics Block + Interface Statistics Block Enhanced Packet Block Simple Packet Block - Name Resolution Block - Capture Information Block + Name Resolution Block + Capture Information Block Custom Block @@ -269,9 +269,9 @@ Description Block is also required, before this block. Capture Information Block: it - defines how to store some capture information (such as location, - orientation, velocity and associated errors, as well as rf frequencies - and channels) + defines how to store some capture information such as location, + orientation, velocity and associated errors, as well as Radio Frequency + (RF) information. Custom Block: it contains vendor-specific data in a portable fashion. @@ -1851,7 +1851,7 @@ Section Header channel and medium options. This block can be associated with a specific interface and applied to all packets received on this interface, or to (a) specific packet(s). - If applied to an interface, this block effects all capture blocks following + If applied to an interface, this block affects all capture blocks following until it is superseded by a new CIB applied to the same interface. @@ -1967,9 +1967,9 @@ Section Header Example: TODO The - global_location_error option specifies the error in location capture, + global_location_error option specifies the error in location capture; this is stored as three 32-bit floats in the same order and - representation as cib_location + representation as cib_location. Example: TODO @@ -1981,9 +1981,9 @@ Section Header Example: TODO The - orientation_error option specifies the error in orientation capture, + orientation_error option specifies the error in orientation capture; this is stored as three 32-bit floats in the same order and - representation as cib_orientation + representation as cib_orientation. Example: TODO @@ -1995,9 +1995,9 @@ Section Header Example: TODO The - cib_velocity_error option specifies the error in velocity capture, + cib_velocity_error option specifies the error in velocity capture; this is stored as three 32-bit floats in the same order and - representation as cib_velocity + representation as cib_velocity. Example: TODO From e73d4bccfda451a2bbb3dde1325066ca0cf29721 Mon Sep 17 00:00:00 2001 From: Ryan Date: Sun, 17 Jun 2018 21:21:43 +1200 Subject: [PATCH 3/9] Added local_location, updated descriptions --- draft-tuexen-opsawg-pcapng.xml | 83 +++++++++++++++++++++++++--------- 1 file changed, 61 insertions(+), 22 deletions(-) diff --git a/draft-tuexen-opsawg-pcapng.xml b/draft-tuexen-opsawg-pcapng.xml index 7448f51..36278f8 100644 --- a/draft-tuexen-opsawg-pcapng.xml +++ b/draft-tuexen-opsawg-pcapng.xml @@ -1901,8 +1901,20 @@ Section Header - All the statistic fields are defined as options in order to deal - with systems that do not have a complete set of statistics. Therefore, + Location information can be represented with in global (lat/lng/alt in degrees) + or local (X/Y/Z in metres) form, only one of these forms may be used in a given PCAP file. + Combining files with different forms should result in the removal of all position information. + + + + Velocity and Orientation are to be interpreted from the zero frame for either form. + For the global form, X corresponds to latitude, Y to longitude, and Z to altitude. + Yaw is about the X/Y or Lat/Lng plane with zero facing along Y or North, + pitch is applied with this yaw offset, and roll is applied to the combination of both. + + + All the information fields are defined as options in order to deal + with systems that do not have a complete set of information. Therefore, In addition to the options defined in , the following options are valid within this block: @@ -1917,80 +1929,107 @@ Section Header 4 no - global_location + local_location 2 12 no - global_location_error + local_location_error 3 12 no - orientation + global_location 4 12 no - orientation_error + global_location_error 5 12 no - velocity + orientation 6 12 no - velocity_error + orientation_error 7 12 no + + velocity + 8 + 12 + no + + velocity_error + 9 + 12 + no The - interface_id option specifies the interface these statistics refers - to; the correct interface will be the one whose Interface + cib_interface_id option specifies the interface these statistics + refers to; the correct interface will be the one whose Interface Description Block (within the current Section of the file) is identified by same number (see ) of this field. + The + cib_local_location option specifies the local location of the packet + capture or interface in an abitrary plane; location is stored as three + 32-bit floats representing X, Y (in plane), and Z (altitude) offsets in \ + metres. + + Example: TODO + + The + cib_local_location_error option specifies the error in local location + capture; this is stored as three 32-bit floats in the same order and + representation as cib_local_location. + + Example: TODO + The - cib_global_location option specifies the location of the packet - capture or interface; location is stored as three 32-bit floats + cib_global_location option specifies the global location of the + packet capture or interface; location is stored as three 32-bit floats representing latitude and longitude in degrees, and altitude in metres. Example: TODO The - global_location_error option specifies the error in location capture; - this is stored as three 32-bit floats in the same order and - representation as cib_location. + cib_global_location_error option specifies the error in global location + capture; this is stored as three 32-bit floats in the same order and + representation as cib_global_location. Example: TODO The - cib_orientation option specifies the location of the packet - capture or interface; location is stored as three 32-bit floats - representing yaw, pitch, and roll in radians. + cib_orientation option specifies the orientation of the packet + capturing antenna; orientation is stored as three 32-bit floats + representing yaw, pitch, and roll in radians. + This is relative to the zero frame for global or local location. Example: TODO The - orientation_error option specifies the error in orientation capture; + cib_orientation_error option specifies the error in orientation capture; this is stored as three 32-bit floats in the same order and representation as cib_orientation. Example: TODO The - cib_velocity option specifies the location of the packet - capture or interface; location is stored as three 32-bit floats - representing yaw, pitch, and roll in radians. + cib_velocity option specifies the velocity of the packet capture interface; + velocity is stored as three 32-bit floats representing the motion in the + X (lat), Y (lng), and Z (altitude) directions in metres per second. + This is relative to the zero frame for global or local location. Example: TODO From 2e0bb987990c7e63c8abecc2854d353ee4264d89 Mon Sep 17 00:00:00 2001 From: Ryan Kurte Date: Sat, 18 Aug 2018 16:48:36 +1200 Subject: [PATCH 4/9] Simplified proposal --- draft-tuexen-opsawg-pcapng.xml | 82 ++++++++++++---------------------- 1 file changed, 29 insertions(+), 53 deletions(-) diff --git a/draft-tuexen-opsawg-pcapng.xml b/draft-tuexen-opsawg-pcapng.xml index 36278f8..b1b2660 100644 --- a/draft-tuexen-opsawg-pcapng.xml +++ b/draft-tuexen-opsawg-pcapng.xml @@ -269,9 +269,8 @@ Description Block is also required, before this block. Capture Information Block: it - defines how to store some capture information such as location, - orientation, velocity and associated errors, as well as Radio Frequency - (RF) information. + defines how to store some interface information such as location, + orientation, velocity, and associated errors. Custom Block: it contains vendor-specific data in a portable fashion. @@ -1276,10 +1275,6 @@ Section Header 8 no - epb_cib - 4 - 4 - no @@ -1317,10 +1312,6 @@ Section Header Example: '0'. - The epb_cib - option indicates the Capture Information Block ID to be associated - with this packet, allowing the addition of capture related metadata. - @@ -1846,24 +1837,11 @@ Section Header
The Capture Information Block (CIB) is used to support the addition - of metadata associated with capture interfaces or packets, including - location, orientation, velocity and related errors, as well as wireless - channel and medium options. - This block can be associated with a specific interface and applied to all - packets received on this interface, or to (a) specific packet(s). - If applied to an interface, this block affects all capture blocks following - until it is superseded by a new CIB applied to the same interface. - - - - Tools that write / read the capture file associate an incrementing 32-bit - number (starting from '0') to each Capture Information Block, called - the CIB ID for the CIB in question. This number is unique within each Section - and identifies the CIB that is referred to in an epb_cip option; it is only - unique inside the current section, so, two Sections can have different - CIBs identified by the same CIB ID values. This unique identifier - is referenced by other blocks, such as Enhanced Packet Blocks, to indicate the - CIB to which the block refers. + of time-varying metadata associated with capture interfaces, including + location, orientation, velocity, and related errors. + Each CIB is associated with a specific interface and applied to all packets + received on this interface following the CIB until superseded by a new CIB on + the same interface. The format of the Capture Information Block is shown in Block Total Length: total size of this block, as described in . + Interface ID: specifies the interface for this CIB to be applied + to; the correct interface will be the one whose Interface + Description Block (within the current Section of the file) is + identified by the same number (see ) + of this field. The interface ID MUST be valid, which means that an + matching interface description block MUST exist. + Options: optionally, a list of options (formatted according to the rules defined in ) can be present. @@ -1903,7 +1890,8 @@ Section Header Location information can be represented with in global (lat/lng/alt in degrees) or local (X/Y/Z in metres) form, only one of these forms may be used in a given PCAP file. - Combining files with different forms should result in the removal of all position information. + Combining pcap files with different location formats should result in the + removal of all position information. @@ -1913,8 +1901,8 @@ Section Header pitch is applied with this yaw offset, and roll is applied to the combination of both. - All the information fields are defined as options in order to deal - with systems that do not have a complete set of information. Therefore, + All the information fields are defined as options in order to support + systems that do not have a complete set of information. Therefore, In addition to the options defined in , the following options are valid within this block: @@ -1924,48 +1912,43 @@ Section Header Length Multiple allowed? - interface_id - 1 - 4 - no - local_location - 2 + 1 12 no local_location_error - 3 + 2 12 no global_location - 4 + 3 12 no global_location_error - 5 + 4 12 no orientation - 6 + 5 12 no orientation_error - 7 + 6 12 no velocity - 8 + 7 12 no velocity_error - 9 + 8 12 no @@ -1973,13 +1956,6 @@ Section Header - The - cib_interface_id option specifies the interface these statistics - refers to; the correct interface will be the one whose Interface - Description Block (within the current Section of the file) is - identified by same number (see ) of - this field. - The cib_local_location option specifies the local location of the packet capture or interface in an abitrary plane; location is stored as three From c91863c9b7ec4e382a3728d08a9936e395b85082 Mon Sep 17 00:00:00 2001 From: Ryan Kurte Date: Sat, 18 Aug 2018 16:54:31 +1200 Subject: [PATCH 5/9] Added example --- draft-tuexen-opsawg-pcapng.xml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/draft-tuexen-opsawg-pcapng.xml b/draft-tuexen-opsawg-pcapng.xml index b1b2660..85a85a7 100644 --- a/draft-tuexen-opsawg-pcapng.xml +++ b/draft-tuexen-opsawg-pcapng.xml @@ -1844,6 +1844,13 @@ Section Header the same interface. + For example, a capture from a static interface may contain a single CIB at + the start of the file to apply to all packets on this interface. + A capture from a moving interface with GNSS will add a CIB each time updated + positional information is available, and this information will apply to all + packets received on this interface until the next CIB. + + The format of the Capture Information Block is shown in . From 4e8919516888bd43df8fc356c2803adb90df7c44 Mon Sep 17 00:00:00 2001 From: Ryan Kurte Date: Sat, 18 Aug 2018 16:58:50 +1200 Subject: [PATCH 6/9] Added note on CIB persistence --- draft-tuexen-opsawg-pcapng.xml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/draft-tuexen-opsawg-pcapng.xml b/draft-tuexen-opsawg-pcapng.xml index 85a85a7..bbf76b7 100644 --- a/draft-tuexen-opsawg-pcapng.xml +++ b/draft-tuexen-opsawg-pcapng.xml @@ -1841,7 +1841,7 @@ Section Header location, orientation, velocity, and related errors. Each CIB is associated with a specific interface and applied to all packets received on this interface following the CIB until superseded by a new CIB on - the same interface. + the same interface. For example, a capture from a static interface may contain a single CIB at @@ -1851,6 +1851,11 @@ Section Header packets received on this interface until the next CIB. + Note that issuing a new CIB will clear all existing CIB options on an interface, + for example, the CIBs for a non-moving but rotating interface with a known position + must all contain both location and orientation data. + + The format of the Capture Information Block is shown in . From dac8670b5818166655debcc47a0d9c7483fcea75 Mon Sep 17 00:00:00 2001 From: Ryan Kurte Date: Thu, 24 Jan 2019 09:51:16 +1300 Subject: [PATCH 7/9] Fixed CIB block type, cib_options collision --- draft-tuexen-opsawg-pcapng.xml | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/draft-tuexen-opsawg-pcapng.xml b/draft-tuexen-opsawg-pcapng.xml index bbf76b7..3f671fe 100644 --- a/draft-tuexen-opsawg-pcapng.xml +++ b/draft-tuexen-opsawg-pcapng.xml @@ -1864,7 +1864,7 @@ Section Header 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------------------------------------------------------+ - 0 | Block Type = 0x00000006 | + 0 | Block Type = 0x00000009 | +---------------------------------------------------------------+ 4 | Block Total Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ @@ -1925,42 +1925,42 @@ Section Header Multiple allowed? local_location - 1 + 2 12 no local_location_error - 2 + 3 12 no global_location - 3 + 4 12 no global_location_error - 4 + 5 12 no orientation - 5 + 6 12 no orientation_error - 6 + 7 12 no velocity - 7 + 8 12 no velocity_error - 8 + 9 12 no @@ -2562,6 +2562,11 @@ Section Header Technologies LLC) + 0x00000009 + + Capture Information Block + + 0x00000101 Hone Project From 7820a51a2e5df1ea82add19cbc2ce2f68297f920 Mon Sep 17 00:00:00 2001 From: Ryan Kurte Date: Wed, 13 Feb 2019 14:44:42 +1300 Subject: [PATCH 8/9] Fixing comments from review --- draft-tuexen-opsawg-pcapng.xml | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/draft-tuexen-opsawg-pcapng.xml b/draft-tuexen-opsawg-pcapng.xml index 3c0e460..cc001f5 100644 --- a/draft-tuexen-opsawg-pcapng.xml +++ b/draft-tuexen-opsawg-pcapng.xml @@ -1316,7 +1316,6 @@ Section Header 4 8 no - @@ -2122,6 +2121,13 @@ Section Header pitch is applied with this yaw offset, and roll is applied to the combination of both. + + Error options provide an optional mechanism for attaching error information to measurements, + and are only valid where the corresponding measurement (location, velocity, or orientation) + option is specified. Should an error option be present without the corresponding measurement, + this option should be ignored. + + All the information fields are defined as options in order to support systems that do not have a complete set of information. Therefore, In addition to the options defined in , @@ -2180,7 +2186,7 @@ Section Header The cib_local_location option specifies the local location of the packet capture or interface in an abitrary plane; location is stored as three - 32-bit floats representing X, Y (in plane), and Z (altitude) offsets in \ + 32-bit floats representing X, Y (in plane), and Z (altitude) offsets in metres. Example: TODO @@ -2192,7 +2198,7 @@ Section Header Example: TODO - The + The cib_global_location option specifies the global location of the packet capture or interface; location is stored as three 32-bit floats representing latitude and longitude in degrees, and altitude in @@ -2781,7 +2787,7 @@ Section Header - 0x0000000B/c> + 0x0000000B Capture Information Block From 5df4b9d9f6b4d7e902517a6e2c917479e8b02556 Mon Sep 17 00:00:00 2001 From: Ryan Kurte Date: Wed, 13 Feb 2019 15:16:04 +1300 Subject: [PATCH 9/9] add CIB option examples, fix CIB block number --- draft-tuexen-opsawg-pcapng.xml | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/draft-tuexen-opsawg-pcapng.xml b/draft-tuexen-opsawg-pcapng.xml index cc001f5..aa91165 100644 --- a/draft-tuexen-opsawg-pcapng.xml +++ b/draft-tuexen-opsawg-pcapng.xml @@ -2090,7 +2090,7 @@ Section Header Block Type: The block type of the Capture Information Block is - 6. + 11. Block Total Length: total size of this block, as described in . @@ -2189,14 +2189,16 @@ Section Header 32-bit floats representing X, Y (in plane), and Z (altitude) offsets in metres. - Example: TODO + Example: '41 24 cc cd 41 73 33 33 3f cc cc cd' decodes to + x: 10.3m, y: 15.2m, z: 1.6m The cib_local_location_error option specifies the error in local location capture; this is stored as three 32-bit floats in the same order and representation as cib_local_location. - Example: TODO + Example: '3f 80 00 00 3f 99 99 9a 3f cc cc cd' decodes to + x_error: 1.0m, y_error: 1.2m, z_error: 1.6m The cib_global_location option specifies the global location of the @@ -2204,14 +2206,16 @@ Section Header representing latitude and longitude in degrees, and altitude in metres. - Example: TODO + Example: 'c2 13 64 ce 43 2e c2 90 41 88 00 00' decodes to + lat: -36.8484437° lng: 174.7600023° alt: 17.0m The cib_global_location_error option specifies the error in global location capture; this is stored as three 32-bit floats in the same order and representation as cib_global_location. - Example: TODO + Example: '3f 80 00 00 3f 99 99 9a 3f cc cc cd' decodes to + lat_error: 0.1° lng_error: 0.2° alt_error: 1.6m The cib_orientation option specifies the orientation of the packet @@ -2219,14 +2223,16 @@ Section Header representing yaw, pitch, and roll in radians. This is relative to the zero frame for global or local location. - Example: TODO + Example: '3f c9 0f db 3e 86 0a 92 00 00 00 00' decodes to + yaw: pi/2, pitch: -pi/12, roll: 0.0 The cib_orientation_error option specifies the error in orientation capture; this is stored as three 32-bit floats in the same order and representation as cib_orientation. - Example: TODO + Example: '3c 23 d7 0a 3c a3 d7 0a 00 00 00 00' decodes to + yaw_error: 0.01, pitch_error: 0.02, roll_error: 0.0 The cib_velocity option specifies the velocity of the packet capture interface; @@ -2234,14 +2240,16 @@ Section Header X (lat), Y (lng), and Z (altitude) directions in metres per second. This is relative to the zero frame for global or local location. - Example: TODO + Example: '41 24 cc cd 41 73 33 33 00 00 00 00' decodes to + x: 10.3m/s, y: 15.2m/s, z: 0.0m/s The cib_velocity_error option specifies the error in velocity capture; this is stored as three 32-bit floats in the same order and representation as cib_velocity. - Example: TODO + Example: '3f 80 00 00 3f 99 99 9a 00 00 00 00' decodes to + x_error: 1.0m/s, y_error: 1.2m/s, z_error: 0.0m/s