doc: remove old/now-wrong info; start new doc

Lots more to do, but this is a minimal set of the critical bits
for the project writ large and the hardware

README.md

@@ -1,3 +1,70 @@
+TotTag
+======
+
+If you are interested in incorporating TotTag devices into your future
+research, please fill out this [Interest Form](https://forms.gle/SqWca9DrKpcx9rBL6).
+
+> **Note: This system is currently under heavy development. At the moment, it
+> is provided as-is with no mechanism for external support, technical or
+> otherwise.  In the future, once the project has reached a steady state and
+> staffing has ramped up, we may begin providing limited support. We will post
+> any updates on that front here. Thank you for your understanding!**
+
+The TotTag is a self-contained PCB which utilizes a hybrid ultra wideband (UWB)
+and Bluetooth Low Energy (BLE) radio design to enable high-fidelity interaction
+tracking between devices _without_ requiring any supporting infrastructure.
+
+<!--
+- The SquarePoint module - 3 UWB antennas
+- Nordic Semiconductors nRF52840 BLE radio
+- 3.3V LDO designed to be used with 4.2V LiPo batteries
+- Battery charge management controller
+- SD card holder
+- microUSB connector including FTDI FT232R for debugging
+- 3-axis accelerometer
+-->
+
+TotTag saw a major plaform refresh in 2023 with a largely new hardware and
+software design. Please bear with us as documentation and guidance throughout
+this repositority updates to match the latest state of the TotTag project.
+
+- [Documentation & Getting Started Guide](doc/)
+- [Hardware details](hardware/)
+- [Software details](software/)
+
+
+
+History, Related Projects, & Relevant Publications
+==================================================
+
+This current effort builds on a long line of work exploring the capabilities of
+ultra wideband under resource-constrained settings. This repository is an
+evolution of projects exploring COTS-based solutions; some others linked below
+explore more custom ultra wideband as well.
+
+SociTrack and TotTag Gen 1
+--------------------------
+
+- Salo, V. C., Pannuto, P., Hedgecock, W., Biri, A., Russo, D. A., Piersiak, H. A., & Humphreys, K. L. (2022). Measuring naturalistic proximity as a window into caregiver-child interaction patterns. Behavior research methods, 54(4), 1580–1594. https://doi.org/10.3758/s13428-021-01681-8
+
+- Andreas Biri, Neal Jackson, Lothar Thiele, Pat Pannuto, and Prabal Dutta. 2020.
+*SociTrack: Infrastructure-Free Interaction Tracking through Mobile Sensor Networks.*
+In The 26th Annual International Conference on Mobile Computing and Networking
+(MobiCom ’20), September 21–25, 2020, London, United Kingdom. ACM, New York, NY,
+USA, 14 pages. https://doi.org/10.1145/3372224.3419190
+
+<!--
+- Andreas Biri, Pat Pannuto, and Prabal Dutta. 2019.
+*Demo Abstract: Tot-Ternary - A Wearable Platform for Social Interaction Tracking.*
+In The 18th International Conference on Information Processing in Sensor Networks
+(co-located with CPS-IoT Week 2019) (IPSN ’19), April 16-18, 2019, Montreal, QC,
+Canada. ACM, New York, NY, USA, 2 pages. https://doi.org/10.1145/3302506.3312486
+-->
+
+<details>
+<summary>Legacy documentation from SociTrack / TotTag Gen 1
+</summary>
+
 SociTrack
 =========
 
@@ -7,15 +74,6 @@ module, containing a DecaWave DW1000 radio for UWB packet transmission and
 timestamping. This module provides node-to-node ranges over an I<sup>2</sup>C
 interface which can then be stored locally or transmitted externally.
 
-If you would be interested in incorporating the SociTrack system or TotTag
-devices into your future research, please fill out this
-[Interest Form](https://forms.gle/SqWca9DrKpcx9rBL6)
-
-**Note: This system is currently under heavy development. At the moment, it is
-provided as-is with no mechanism for external support, technical or otherwise.
-In the future, once the project has reached a steady state and staffing has
-ramped up, we may begin providing limited support. We will post any updates
-on that front here. Thank you for your understanding!**
 
 Hardware
 --------
@@ -55,8 +113,7 @@ to worry about any underlying implementation details.
 The TotTag is a self-contained PCB which utilizes SquarePoint to provide ranging
 data for human interaction tracking. It includes:
 
-- The SquarePoint module
-- 3 UWB antennas
+- The SquarePoint module - 3 UWB antennas
 - Nordic Semiconductors nRF52840 BLE radio
 - 3.3V LDO designed to be used with 4.2V LiPo batteries
 - Battery charge management controller
@@ -131,30 +188,30 @@ Please be aware that the some Linux distros provide out-of-date versions of this
 tool; as such, we strongly recommend that you install the newest version
 directly from ARM.
 
+</details>
 
-Related Publications
---------------------
 
-- Andreas Biri, Neal Jackson, Lothar Thiele, Pat Pannuto, and Prabal Dutta. 2020.
-*SociTrack: Infrastructure-Free Interaction Tracking through Mobile Sensor Networks.*
-In The 26th Annual International Conference on Mobile Computing and Networking
-(MobiCom ’20), September 21–25, 2020, London, United Kingdom. ACM, New York, NY,
-USA, 14 pages. https://doi.org/10.1145/3372224.3419190
+SurePoint
+---------
 
-- Andreas Biri, Pat Pannuto, and Prabal Dutta. 2019.
-*Demo Abstract: Tot-Ternary - A Wearable Platform for Social Interaction Tracking.*
-In The 18th International Conference on Information Processing in Sensor Networks
-(co-located with CPS-IoT Week 2019) (IPSN ’19), April 16-18, 2019, Montreal, QC,
-Canada. ACM, New York, NY, USA, 2 pages. https://doi.org/10.1145/3302506.3312486
+The original projects exploring COTS UWB technology.
+
+PolyPoint introduced the concept of antenna diversity, and demonstrated its
+efficacy by finishing as the best-performing UWB-based system at the 2015
+Microsoft Indoor Localization competition.
+
+SurePoint expanded on the PolyPoint concepts and built a complete system around
+efficient channel diversity, and showed how to scale up robust ranging with
+COTS UWB.
 
 - Benjamin Kempke, Pat Pannuto, Bradford Campbell, and Prabal Dutta. 2016.
-*Surepoint: Exploiting ultra wideband flooding and diversity to provide robust, scalable, high-fidelity indoor localization.*
+*SurePoint: Exploiting ultra wideband flooding and diversity to provide robust, scalable, high-fidelity indoor localization.*
 In Proceedings of the 14th ACM Conference on Embedded Network Sensor Systems
 (SenSys ’16), November 14-16, 2016, Stanford, CA, USA.  ACM, New York, NY,
 USA, 13 pages. https://doi.org/10.1145/2994551.2994570
 
 - Benjamin Kempke, Pat Pannuto, and Prabal Dutta. 2015.
-*Polypoint: Guiding indoor quadrotors with ultra-wideband localization.*
+*PolyPoint: Guiding indoor quadrotors with ultra-wideband localization.*
 In Proceedings of the 2nd International Workshop on Hot Topics in Wireless
 (HotWireless ’15), September 11, 2015, Paris, France. ACM, New York, NY,
 USA, 5 pages. https://doi.org/10.1145/2799650.2799651

hardware/README.md

@@ -1,29 +1,72 @@
 Hardware
 ========
 
-PolyPoint
----------
+TotTag Gen 2 (2023-present)
+---------------------------
 
-The PolyPoint system consists of several PCBs centered around TriPoint, the core
-UWB ranging module.
+`rev_i` is a fairly complete overhaul of the TotTag platform, shedding
+many of the legacy IC selections from the long design history here
+(some traced back to the original 2015 PolyPoint board).
 
-1. **TriPoint**: A triangular module which contains all of the necessary hardware
-for utilizing a DecaWave DW1000 UWB radio. It has castellated headers so it can
-be soldered onto a carrier board to add indoor localization functionality to any
-device.
+The most significant changes are moving from a dual-MCU design to a single MCU,
+based around the Ambiq Apollo4 family of chips, and upgrading to the newer
+generation UWB transciever, ~~Decawave~~ Qorvo's DW3000 family.
 
-2. **TriTag**: A portable carrier board designed to be used as an indoor
-localization tag. Contains TriPoint on one side and a BLE radio on the other.
+`rev_i` is in many ways a first revision of a new board.
+
+`rev_k` fixed most of the major flaws in from `rev_i`, but introduced new
+problems around the DW3000.
+
+`rev_l` hedged around continued DW3000 issues and replaced the integrated
+design with three copies of Qorvo's pre-fab module. This is a temporary
+patch to get working systems with the new transciever more quickly to enable
+scale-up.
+
+`rev_m` has only trivial, cosmetic fixes over `rev_l`.
+
+`rev_n` (in progress) removes the pre-fab UWB modules, and returns to the
+integrated UWB design, which re-opens access to antenna diversity and the
+improved robustness of ranging performance.
+
+
+TotTag Gen 1 (2020-2023)
+------------------------
+
+More recent revisions have focused on the deployability, scaling, and
+robustness of the caregiver-infant interaction tracking application.
 
+This has resulted in a more tightly integrated design as well as one
+more aggressively geared towards a "wireless only" approach to ease
+device management at-scale.
 
-SociTrack
----------
+For more details, see the documentation in the [tottag folder](tottag/).
+
+
+SociTrack (2017-2020)
+---------------------
 
 The SociTrack system consists of a single PCB which integrates both an
 application board and a SquarePoint module. SquarePoint is available from the
 [*Lab11 EAGLE* library](https://github.com/lab11/eagle) as a design block
 (check version number).
 
-- **TotTag**: A single PCB featuring dual microcontrollers and enhanced
-functionality such as SD card logging, accelerometer information, USB connectivity,
-wireless charging, debugging ports, and LEDs, as well as battery voltage sensing.
+The original tottags (i.e., rev_c and rev_d) follow this more modularized
+design, keeping SociTrack's components as cleanly separable features, but
+integrating into a single PCB dual microcontrollers and enhanced functionality
+such as SD card logging, accelerometer information, USB connectivity, wireless
+charging, debugging ports, and LEDs, as well as battery voltage sensing.
+
+
+PolyPoint (2015) and SurePoint (2016-2017)
+------------------------------------------
+
+The PolyPoint system consists of several PCBs centered around TriPoint, the core
+UWB ranging module.
+
+1. **TriPoint**: A triangular module which contains all of the necessary hardware
+for utilizing a DecaWave DW1000 UWB radio. It has castellated headers so it can
+be soldered onto a carrier board to add indoor localization functionality to any
+device.
+
+2. **TriTag**: A portable carrier board designed to be used as an indoor
+localization tag. Contains TriPoint on one side and a BLE radio on the other.

hardware/cad/README.md

@@ -1,4 +1,26 @@
 CAD Models
 ==========
 
-A few designs including a case for TriTag and TotTag.
+A few designs of various cases and mounts used for different iterations of
+hardware over the course of this project.
+
+---------------------------------------------------------------------------
+
+**Note:** As of this writing (July 2024), none of these designs are relevant to
+the recent generations of TotTag PCBs. For the last few years, the board has
+been designed to fit in the OKW Minitec case, specifically the
+[B9006856](https://www.okwenclosures.com/en/Minitec/B9006856.htm).
+You will also need the plastic ring which sits between the two halves of the
+case, e.g. [B9006782](https://www.okwenclosures.com/en/Minitec/B9006782.htm)
+(n.b., color doesn't affect anything; our original order bought 30 cases and 5
+each of B9006782-B9006888).
+
+**If you will be opening and closing the cases often,** we had OKW install
+metal receptacles in the posts for the screws in our larger order. This widens
+the plastic post width slightly (the PCB does not rely on the screw posts for
+alignment or mounting in either case, so this should not affect things
+generally). The new posts accept a `M2,5` screw. The product number for our
+final case is `B9006A30`, which I believe is an internal code for the
+customization they did for our design, and not a publicly available model.
+However, hopefully their sales team can look up the old design by this
+reference for your order if-needed, and do the same modification.

hardware/tottag/README.md

@@ -1,26 +1,60 @@
-Hardware Revision History
-=========================
+TotTag Revision History
+=======================
 
 The original localization platform was developed by the Lab11 research group,
 primarily by @bpkempke, @bradjc, and @ppannuto.
 
-The TotTag hardware was developed @abiri during his Master's Thesis work when
-he was a visiting scholar with the Lab11 research group.
+The original TotTag hardware (rev_c, rev_d) was developed @abiri during his
+Master's Thesis work when he was a visiting scholar with the Lab11 research
+group.
+
+Current TotTag hardware is maintained by @ppannuto and @corruptbear.
+
+## Rev M + AP4BP Rev-B
+[Rev L Issues / Rev M updates](https://github.com/lab11/socitrack/issues/49)
+ - Fix silkscreen error on switch label
+
+## Rev L + AP4BP Rev-B
+[Prior rev's issues / updates](https://github.com/lab11/socitrack/issues/46)
+ - Fixes first-rev issues from the AP4BP module.
+ - Rips out our UWB in favor of DWM3000 pre-fab modules for Qorvo as a hedge
+   to facilitate more certain-to-work UWB in the short term (but sacrificing
+   diversity and robustness [and adding cost]).
+
+## Rev K + AP4BP Rev-A
+[Rev I Issues / Rev K Updates](https://github.com/lab11/socitrack/issues/44)
+ - (n.b., there is no Rev J to avoid I/J confusion)
+ - Move to Apollo4 Blue Plus (Blue has too many silicon bugs)
+    - Split this to a castellated module for separation of hw design concerns
+ - Move to TCXO for DW3000 (bad idea; will be removed next rev)
+
+## Rev I -- **Major Revision**
+ - Refresh part selection to replace 2015 parts with improved modern versions
+ - Major change: Apollo4 Blue as sole MCU
+ - Major change: DW3000 replaces DW1000 as UWB transceiver
+ - Really, most stuff changed except the wireless charging
+
+## Rev H
+[Rev G Issues / Rev H Updates](https://github.com/lab11/socitrack/issues/9)
+ - Isolates high-bandwidth accelerometer to dedicated SPI bus
+ - Revises wireless charging design for robustness
+ - Resolve RTC design issues
+ - DFM cleanups
 
 ## Rev G
-[Rev G Issue.](https://github.com/lab11/totternary/issues/7)
+[Rev F Issues / Rev G Updates](https://github.com/lab11/totternary/issues/7)
  - Add detachable battery connector
  - Add power switch
  - Adapt PCB shape for mass-production case
 
 ## Rev F
 
-[Rev F Issue.](https://github.com/lab11/totternary/issues/4)
+[Rev E Issues / Rev F Updates.](https://github.com/lab11/totternary/issues/4)
  - Add RTC
 
 ## Rev E
 
-[Rev E Issue.](https://github.com/lab11/totternary/issues/3)
+[Rev D Issues / Rev E Updates.](https://github.com/lab11/totternary/issues/3)
 
 Rev E updates:
  - Major performance improvements