---
date: 2025-12-17
version: 1.7.2
previous_version: 1.7.1
release_type: patch
---

# Release v1.7.2

## Overview

**v1.7.2** is a patch release combining two major features and infrastructure improvements:

- **Feature 024**: Unified threshold operation logging across all commands
- **Feature 025**: MAC address integration for device identification
- Device communication robustness improvements
- Notebook management infrastructure consolidation

**Release Timeline**: v1.7.1 (2025-11-02) → v1.7.2 (2025-12-17)

---

## 📊 Release Statistics

| Metric | Value |
|--------|-------|
| **Total Commits** | 33 |
| **Code Changes** | ~2,600 lines added/modified |
| **Test Addition** | 1,352 lines in 5 new test files |
| **Features** | 2 major features |
| **Bug Fixes** | 5 critical device communication fixes |
| **Files Modified** | ~150 files |

---

## ✨ Feature 024: Unified Threshold Operation Logging

### Overview

Implements consistent logging output across all threshold-related commands (`write`, `scan`, `fit`), improving operational visibility and troubleshooting.

### Implementation Details

**Commit**: [`ca4da70`](https://gitlab.com/qumasan/haniwers/-/commit/ca4da70)

**Code Changes**:
- `src/haniwers/v1/cli/threshold.py` - Centralized logging logic (20 lines)
- `src/haniwers/v1/threshold/writer.py` - CSV output integration (8 lines)

**Test Coverage** (3 new test suites, 756 lines):
- `test_threshold_parallel_logging.py` (191 lines) - Parallel scan logging
- `test_threshold_serial_logging.py` (239 lines) - Serial scan logging
- `test_threshold_unified_logging.py` (326 lines) - Unified format validation

### Benefits

- ✅ Consistent CSV output format across all threshold commands
- ✅ CSV header row included for proper data structure
- ✅ Parallel and serial operations use identical logging format
- ✅ Enhanced troubleshooting and audit trail

---

## ✨ Feature 025: MAC Address Integration

### Overview

Automatically retrieves ESP32 MAC addresses and embeds them in data filenames for accurate device identification and traceability.

### Implementation Details

**Commit**: [`b0e62e9`](https://gitlab.com/qumasan/haniwers/-/commit/b0e62e9)

**New Components**:
- `src/haniwers/v1/helpers/mac_address.py` (113 lines)
  - `format_mac_address()` - Format MAC addresses as filesystem-safe hex
  - Supports multiple MAC formats (colon-separated, hyphen-separated, no separator)
  - Graceful fallback to "unknown" on retrieval errors

**Enhanced Components**:
- `src/haniwers/v1/daq/device.py` (+77 lines)
  - `get_mac_address()` method for Device class
  - Uses `esptool.main()` for module-based retrieval
  - Comprehensive error handling with logging

- `src/haniwers/v1/daq/sampler.py` (+47 lines)
  - `mac_address` parameter in filename generation
  - Maintains backwards compatibility

- `src/haniwers/v1/cli/daq.py` (+6 lines)
  - Integrates MAC address into DAQ workflow

**Test Coverage** (596 lines, 29 tests passing):
- `tests/v1/unit/cli/helpers/test_mac_address.py` (318 lines)
- `tests/v1/unit/daq/test_sampler_mac.py` (278 lines)

### Filename Impact

**Before**:
```
osechi_data_2025-12-17_10h30m45s_0000000.csv
```

**After**:
```
osechi_data_2025-12-17_10h30m45s_0000000_aabbccddeeff.csv
                                     ^^^^^^^^^^^^
                                     Device MAC address
```

### Benefits

- ✅ Unique device identification across all data files
- ✅ Automatic retrieval via esptool (no manual configuration)
- ✅ Improved data traceability for multi-device experiments
- ✅ Graceful degradation when MAC unavailable
- ✅ 100% test coverage (29 tests)

---

## 🔧 Bug Fixes

### Device Communication Robustness

| Fix | Files | Description |
|-----|-------|-------------|
| JSON Response Handling | `v0/daq.py`, `v1/threshold/writer.py` | Handle JSON-formatted device responses correctly |
| Protocol Compliance | Both versions | Add newline after 3-byte commands for firmware compatibility |
| DEBUG Output | `v1/threshold/writer.py` | Skip DEBUG lines when reading device responses |
| Option Application | `v1/cli/threshold.py` | Apply `duration` and `max_retry` options in parallel commands |
| Legacy Tests | `v0/threshold/writer/test_*.py` | Update CSV writer tests for header row compatibility |

**Commits**:
- [`31ccb9d`](https://gitlab.com/qumasan/haniwers/-/commit/31ccb9d) - JSON threshold response
- [`76b7d08`](https://gitlab.com/qumasan/haniwers/-/commit/76b7d08) - JSON DAQ response
- [`4c55682`](https://gitlab.com/qumasan/haniwers/-/commit/4c55682) - Threshold protocol
- [`a8cce01`](https://gitlab.com/qumasan/haniwers/-/commit/a8cce01) - DAQ protocol
- [`dc98b29`](https://gitlab.com/qumasan/haniwers/-/commit/dc98b29) - DEBUG output
- [`19a76b3`](https://gitlab.com/qumasan/haniwers/-/commit/19a76b3) - Option application
- [`c88377a`](https://gitlab.com/qumasan/haniwers/-/commit/c88377a) - Legacy tests

---

## 🏗️ Infrastructure Improvements

### Notebook Management Consolidation

**Commit**: [`de60583`](https://gitlab.com/qumasan/haniwers/-/commit/de60583)

**Changes**:
- Unified `markdowns/` → `notebooks/md/` (46 files moved)
- Consolidated `notebooks/` → `notebooks/nb/` (87 files moved)
- Updated jupytext configuration (`.jupytext.toml` → `jupytext.toml`)
- Updated CLAUDE.md with new structure (87 lines modified)

**Benefits**:
- ✅ Cleaner directory structure
- ✅ Better separation between interactive notebooks and markdown sources
- ✅ Improved Git management (`.ipynb` files excluded from tracking)
- ✅ Enhanced jupytext synchronization

### Git Management

- Exclude `.ipynb` files from version control (41 files)
- Update `.gitignore` for notebook development directory
- Add `notebooks/README.md` with management guide (237 lines)
- Update `Taskfile.yml` with improved `nb:sync` task

---

## 📚 Documentation Updates

### Specification Documents

| Document | Lines | Content |
|----------|-------|---------|
| `specs/024-unify-threshold-logging/spec.md` | 107 | Threshold logging requirements |
| `specs/025-add-mac-filename/spec.md` | 105 | MAC address feature specification |
| `specs/024-unify-threshold-logging/plan.md` | 113 | Implementation plan for logging |
| `specs/025-add-mac-filename/plan.md` | 191 | Implementation plan for MAC feature |
| `specs/024-unify-threshold-logging/tasks.md` | 215 | Detailed task breakdown for logging |
| `specs/025-add-mac-filename/tasks.md` | 185 | Detailed task breakdown for MAC feature |

### Progress Logs

- `docs/progress/entries/2025-11-18-threshold-logging-unified.md` (118 lines)
- `docs/progress/entries/2025-11-29-mac-address-feature.md` (129 lines)

---

## 📋 Testing

### New Test Suites Added

| Test File | Lines | Coverage |
|-----------|-------|----------|
| `test_threshold_parallel_logging.py` | 191 | Parallel scan logging format |
| `test_threshold_serial_logging.py` | 239 | Serial scan logging format |
| `test_threshold_unified_logging.py` | 326 | Unified logging validation |
| `test_mac_address.py` | 318 | MAC address formatting |
| `test_sampler_mac.py` | 278 | Filename generation with MAC |

**Total**: 1,352 lines of test code
**Test Status**: All passing ✅

### Test Commands

```bash
# Run v1 unit tests
task test

# Run with coverage
task test:cov

# Run specific test file
poetry run pytest tests/v1/unit/cli/helpers/test_mac_address.py
```

---

## 🔄 Migration Guide (v1.7.1 → v1.7.2)

### Breaking Changes

**None** - Full backwards compatibility maintained

### Recommended Actions

1. **Update CLI Usage**:
   - Threshold logging now includes consistent CSV format
   - No command syntax changes required

2. **Data Processing**:
   - New filenames include MAC address
   - Existing data files continue to work
   - Consider re-running DAQ to capture device MAC

3. **Notebook Management**:
   - If working with notebooks, use `task nb:sync` to synchronize
   - `.ipynb` files no longer tracked; work with notebooks/nb/ directory

### Verification Steps

```bash
# Verify installation
haniwers-v1 --version
# Output: haniwers 1.7.2

# Test threshold logging
haniwers-v1 threshold write --help

# Test DAQ with MAC address
haniwers-v1 daq --help
```

---

## 📦 Installation

### PyPI (Coming Soon)

```bash
pip install haniwers==1.7.2
```

### From Source

```bash
git fetch origin
git checkout v1.7.2
poetry install
```

---

## 🙏 Contributors & Reviewers

This release incorporates work from:
- Feature 024: Threshold logging unification
- Feature 025: MAC address device identification
- Device communication fixes across v0 and v1

---

## 📌 Known Issues & Limitations

1. **MAC Address Retrieval**:
   - Requires `esptool` module to be properly installed
   - Gracefully falls back to "unknown" if retrieval fails
   - Some ESP32 models may require specific configuration

2. **Notebook Synchronization**:
   - Manual `task nb:sync` required before committing notebook changes
   - `.ipynb` files excluded from Git tracking

---

## 🔗 Related Resources

- [Feature 024 Specification](../specs/024-unify-threshold-logging/spec.md)
- [Feature 025 Specification](../specs/025-add-mac-filename/spec.md)
- [MAC Address Implementation Guide](../docs/progress/entries/2025-11-29-mac-address-feature.md)
- [Threshold Logging Implementation Guide](../docs/progress/entries/2025-11-18-threshold-logging-unified.md)

---

## 🚀 Next Steps

### Planned for v1.8.0

- Enhanced error handling for device communication
- Expanded MAC address validation
- Documentation updates with new filename format

### Community Feedback

Please report issues at: https://gitlab.com/qumasan/haniwers/issues

---

**Release Date**: December 17, 2025
**Status**: ✅ Ready for Production
**Quality Gates**: All pre-commit checks passing, 100% test coverage targets met