Add license and add documentation

Author: rkalnins

LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2022 Roberts Kalnins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,3 +1,31 @@
-# SHTP
-  
-Packet parser for decoding SHTP traffic in Logic 2.
+# SHTP and SH2 HLA 
+
+SHTP and SH2 are the Sensor Hub Transport Protocol and Sensor Hub 2 protocols from CEVA designed
+to be used with sensor hub devices.
+
+SHTP packet parser is done but the SH2 HLA only supports a small portion of the protocol. This parser
+was written to test communication with the Bosch BNO085 IMU and the project only needed 3 of the many sensor reports.
+The only supported reports currently are the time base, time rebase, gyroscope (calibrated), linear acceleration, and
+rotation vector reports.
+
+SH2 internally layers SH2 on top of SHTP.
+
+## Roadmap
+
+### SHTP
+
+Nothing yet.
+
+### SH2
+
+- [ ] Display floating point result
+- [ ] Add other sensor report types
+
+## Licensing
+
+Released under MIT license.
+
+## Contributing
+
+Any contributions welcome. This tool was written to facilitate testing in a capstone project in the University
+of Michigan's EECS 473 Advanced Embedded Systems course and only covers the portions of SH2 that were needed.

common.py

@@ -2,6 +2,9 @@
 from saleae.analyzers import HighLevelAnalyzer, AnalyzerFrame, StringSetting, NumberSetting, ChoicesSetting
 
 class Packet:
+    """
+    SHTP packet
+    """
     end_times: list
     start_times: list
     is_continuation_header: bool
@@ -34,18 +37,24 @@ def __init__(self):
 
     def fill_header(self, d):
         if self.packet.header_idx == 0:
+            # first byte is length LSB
             self.packet.length_lsb = d[0]
         elif self.packet.header_idx == 1:
+            # second byte is length MSB
             self.packet.length_msb = d[0]
             length = self.packet.length_lsb | (self.packet.length_msb << 8)
+
+            # erase continuation bit
             length = length & 0x7FFF
 
             print("len: ", length)
 
             self.packet.length = length
         elif self.packet.header_idx == 2:
+            # third byte is channel index
             self.packet.channel = d[0]
         elif self.packet.header_idx == 3:
+            # fourth byte is sequence number
             self.packet.sequence_number = d[0]
 
         self.packet.header_idx += 1
@@ -57,10 +66,14 @@ def decode(self, frame: AnalyzerFrame):
         if type == 'start' and self.packet is None:
             self.packet = Packet(frame.start_time)
         elif type == 'start':
+            # packet is continuation in another transaction
             self.packet.is_continuation_header = True
             self.packet.header_idx = 0
         elif (type == 'stop' or type == 'data') and self.packet is not None:
+            # transaction is over
+
             if self.packet.length - 4 == len(self.packet.data):
+                # packet is done if length matches initial length from header
                 self.packet.end_time = frame.end_time
 
                 f = AnalyzerFrame(
@@ -85,18 +98,21 @@ def decode(self, frame: AnalyzerFrame):
 
         if self.packet is not None:
             if type == 'data':
+                # skip continuation headers
                 if self.packet.is_continuation_header:
                     self.packet.header_idx += 1
-
+                    
+                    # continuation header is over
                     if self.packet.header_idx >= 4:
                         self.packet.is_continuation_header = False
                 else:
                     d = frame.data['data']
 
+                    # parse initial SHTP packet header
                     if self.packet.header_idx < 4:
                         self.fill_header(d)
                     else:
-                        # print(d)
+                        # handle internal byte
                         self.packet.data.extend(d)
                         self.packet.start_times.append(frame.start_time)
                         self.packet.end_times.append(frame.end_time)

sh2_analyzer.py

@@ -34,12 +34,6 @@ class Report:
     def __init__(self):
         self.byte_data = bytearray()
 
-    def done(self):
-        # convert to floats
-        # get quaternions
-        # etc.
-        pass
-
 class FixedInt16Data:
     lsb: int
     msb: int
@@ -109,6 +103,11 @@ def __init__(self):
         self.pitch = 0
         self.yaw = 0
 
+    def get_rpy():
+        # TODO: convert fixed pt to quaternion RPY 
+        return self.roll, self.pitch, self.yaw
+
+
 class TimebaseReport(Report):
     report_id = TIMEBASE_REPORT_ID
     length = TIMEBASE_REPORT_LEN
@@ -159,6 +158,9 @@ def __init__(self):
         self.current_report = None
 
     def execute_parser_step(self, new_data, start_time, end_time):
+        # parse data in packet by report type
+
+        # start new report
         if self.current_report is None:
             if new_data == GYRO_REPORT_ID:
                 self.current_report = GyroReport()
@@ -177,7 +179,8 @@ def execute_parser_step(self, new_data, start_time, end_time):
             return False
         else:
             self.current_report.byte_data.extend(new_data.to_bytes(1, 'big'))
-
+            
+            # report is complete
             if self.current_report.length - 1 == len(self.current_report.byte_data):
                 self.current_report.end_time = end_time
                 print('done', self.current_report.report_type, self.current_report.byte_data)
@@ -186,13 +189,15 @@ def execute_parser_step(self, new_data, start_time, end_time):
                 return False
 
     def parse_sh2(self, frame: AnalyzerFrame, p):
+        # all frames generated from parsing reports from this SHTP packet
         frames = []
 
         for i in range(len(p.data)):
             is_done = self.execute_parser_step(p.data[i], p.start_times[i], p.end_times[i])
 
             if is_done:
                 data = dict()
+                # read data from reports based on type and generate correct report output
                 if self.current_report.report_type == 'gyro' or self.current_report.report_type == 'accel':
                     data['x'] = self.current_report.x.getFloating() 
                     data['y'] = self.current_report.x.getFloating() 
@@ -213,17 +218,18 @@ def parse_sh2(self, frame: AnalyzerFrame, p):
                 )
 
                 self.current_report = None
-                        
+                       
+                # multiple SH2 reports can exist per SHTP packet, each report is one frame
                 frames.append(f)
 
 
         return frames
 
     def decode(self, frame: AnalyzerFrame):
         fp = self.shtp_parser.decode(frame)
-        print(fp)
 
         if fp is not None:
+            # wait for shtp packet to be compelte
             return self.parse_sh2(fp[0], fp[1])
 
         return fp

shtp_analyzer.py

@@ -3,6 +3,7 @@
 from common import Packet, SHTPParser
 
 class SHTPHla(HighLevelAnalyzer):
+    # analyzer output format
     result_types = {
         'packet': {
             'format': 'CH: {{data.channel}} SEQ: {{data.sequence}} DAT[{{data.length}}]: {{data.contents}}'