Icoc

ICOc

Command Line Interface

- **Removed unused options** from the command line interface
- All command line arguments should now be **checked for validity** before starting ICOc
- You do not need to connect the PCAN interface to list the help message of the command line interface:

sh
icoc -h


anymore

User Interface

- ICOc should now use considerably **less CPU power**.
- The window for a connected STH now also displays the **sensor range** of the acceleration sensor (in multiples of [g₀](https://en.wikipedia.org/wiki/Gravity_of_Earth))
- We **removed unused menu items** from the user interface
- The **menu** part of the interface now uses a **border** to distinguish itself from the rest of the interface:


┌──────────────────────────────┐
│ 1-9: Connect to STH │
│ │
│ f: Change Output File Name │
│ n: Change STH Name │
│ │
│ q: Quit ICOc │
└──────────────────────────────┘


- ICOc now provides **default values** for nearly all configuration inputs
- ICOc does **not crash** any more if your **terminal window is too small** to display the whole interface. The interface will look garbled if you resize the window to a size that does not fit the whole interface. However, it will look fine after you resize the window to a proper size afterwards, **as long as you do not make the window “really small”** (e.g. leave only two lines for ICOc).

Errors

- ICOc now prints the error messages at the top of the output. This should make it easier to check the reason of an error.

Output

- ICOc now stores **acceleration data in [HDF5](https://www.hdfgroup.org/solutions/hdf5)** format. For more information please take a look at the [documentation](https://github.com/mytoolit/ICOc/#documentation).

Plotter

- The **plotter window now displays the acceleration values as multiples of g₀** (9.81 m/s²).

Removed Functionality

- We **removed** a lot of the **unused, untested and unmaintained functionality** of ICOc:
- XML configuration
- Code to write and read EEPROM data using Excel files

Verification Test

- We enabled most parts of the STH verification test again
- The STH and STU verification tests now use the STH name from the configuration file `config.yaml` (`STH` → `NAME`).

Logger

- ICOc now always extend the logging file name with the postfix `_error`, if there was a problem.

For example, if you use the default name ICOc.txt, then the logging file will be named

- `ICOc_TIMESTAMP_error.txt` (e.g. `ICOc_2021-08-25_10-23-04_error.txt`) instead of
- `ICOc_TIMESTAMP.txt` (e.g. `ICOc_2021-08-25_10-23-04.txt`)

if there were any problems. The behavior of ICOc was similar before. However, the name of the error file could be chosen freely.

- You can now specify the default (base) name of the logging file in the [configuration][] (`Logger` → `ICOC` → `FILENAME`).
- You can now specify the directory where ICOc stores acceleration data in the [configuration][] (`Logger` → `ICOC` → `DIRECTORY`).

[configuration]: https://github.com/MyTooliT/ICOc/blob/e818e5fa/mytoolit/config/config.yaml

Verification Tests

We added the old code of the STH verification tests. You can now execute these tests using the command

sh
test-sth-verification


For more information about these tests, please take a look at the section “Verification Tests” [here](https://github.com/MyTooliT/ICOc/blob/e818e5fa/Documentation/Tutorials.md).

Internal

Message

- The string representation of a message (`repr`) now includes additional information for
- the [“Bluetooth Write Energy Mode Reduced”](https://mytoolit.github.io/Documentation/#command:get-set-state) command
- the EEPROM command [“Read Write Request Counter”](https://mytoolit.github.io/Documentation/#command-read-write-request-counter)
- The code for the string representation now handles incorrect device number values for the acknowledgment message of the [`Get number of available devices`](https://mytoolit.github.io/Documentation/#command:bluetooth:2) properly
- The method `acknowledge` does not ignore the value of the `error` parameter any more

Documentation

- The repo now contains a [bookdown](https://bookdown.org) project for the documentation. The latest version of the bookdown output (HTML, PDF, and EPUB) is available at [GitHub](https://github.com/MyTooliT/ICOc/actions/workflows/documentation.yaml) (just click on the latest “run” and then on the link “ICOc Manual”) or in [the Bitrix24 drive](https://mytoolit.bitrix24.de/docs/path/Documentation%20Repositories/ICOc/).

ICOc

- The data acquisition should now [work more reliable](https://github.com/MyTooliT/ICOc/issues/18), since we fixed
- an [CAN message overflow bug](https://github.com/MyTooliT/ICOc/commit/108b7a64baae980cc24cbda41fd4ca9a979afd80), and
- a [bug that resulted in a “blocked” acceleration data window](https://github.com/MyTooliT/ICOc/commit/12fd083623e9c0b613d2db8e2a54e9b9cac06a28).

Production Test

- The

- stationary acceleration test (`test_acceleration_single_value`),
- supply voltage test (`test_battery_voltage`),
- connection test (`test_connection`), and
- EEPROM test (`test_eeprom`)

now use the [new network class](https://github.com/MyTooliT/ICOc/blob/7b00bcc3f7f56cbbe233ba84e9f55ee82521c88f/mytoolit/can/network.py) instead of the [old network class](https://github.com/MyTooliT/ICOc/blob/7b00bcc3f7f56cbbe233ba84e9f55ee82521c88f/mytoolit/old/network.py)

Internal

Calibration

- Add class `CalibrationMeasurementFormat` to specify the data bytes of a [calibration measurement command](https://mytoolit.github.io/Documentation/#command:Calibration-Measurement).

Measurement

- Add function `convert_voltage_adc_to_volts` to convert (2 byte) [streaming voltage][streaming] values to a supply voltage in volts

[streaming]: https://mytoolit.github.io/Documentation/#block-streaming

Message

- The string representation of a message (`repr`) now includes additional information for the [Get/Set State](https://mytoolit.github.io/Documentation/#command:get-set-state) block command

Network

- Add the coroutine `get_state` to [retrieve information about the current state of a node](https://mytoolit.github.io/Documentation/#command:get-set-state)
- Add the coroutine `read_voltage` to read the supply voltage of a connected STH
- Add the coroutine `read_x_acceleration` to read the x acceleration of a connected STH

Streaming Format

- New class `StreamingFormat` to specify the format of [streaming data][streaming]
- New class `StreamingFormatVoltage` to specify the format of voltage streaming data
- New class `StreamingFormatAcceleration` to specify the format of acceleration streaming data

Utility

- The new function `add_commander_path_to_environment` adds the path to Simplicity Commander (`commander`) to the `PATH` environment variable

Config

- We now use the common term “version” instead of “revision” to specify the current state of the hardware. We therefore renamed

- `STH` → `HARDWARE REVISION` to
- `STH` → `HARDWARE VERSION`

in the [configuration file](https://github.com/MyTooliT/ICOc/blob/f7f90ac6c1be218acc450ddc0a115473180dbe95/mytoolit/config/config.yaml).

ICOc

- The menu for a connected STH now displays the correct STH name instead of the text “Tanja”.
- The main menu now uses “ICOc” instead of “MyToolIt Terminal” as title

Internal

Network

- Add the coroutines

- `read_eeprom_advertisement_time_2`,
- `read_eeprom_batch_number`,
- `read_eeprom_firmware_version`,
- `read_eeprom_gtin`,
- `read_eeprom_hardware_version`,
- `read_eeprom_oem_data`,
- `read_eeprom_operating_time`,
- `read_eeprom_power_off_cycles`,
- `read_eeprom_power_on_cycles`,
- `read_eeprom_product_name`,
- `read_eeprom_production_date`,
- `read_eeprom_release_name`,
- `read_eeprom_serial_number`,
- `read_eeprom_sleep_time_2`,
- `read_eeprom_under_voltage_counter`,
- `read_eeprom_watchdog_reset_counter`,
- `read_eeprom_x_axis_acceleration_offset`, and
- `read_eeprom_x_axis_acceleration_slope`

to read specific values of the EEPROM

- Add the coroutines

- `write_eeprom_advertisement_time_2`,
- `write_eeprom_batch_number`,
- `write_eeprom_firmware_version`,
- `write_eeprom_gtin`,
- `write_eeprom_hardware_version`,
- `write_eeprom_oem_data`,
- `write_eeprom_operating_time`,
- `write_eeprom_power_off_cycles`,
- `write_eeprom_power_on_cycles`,
- `write_eeprom_product_name`,
- `write_eeprom_production_date`,
- `write_eeprom_release_name`,
- `write_eeprom_serial_number`,
- `write_eeprom_sleep_time_2`,
- `write_eeprom_under_voltage_counter`,
- `write_eeprom_watchdog_reset_counter`,
- `write_eeprom_x_axis_acceleration_offset`, and
- `write_eeprom_x_axis_acceleration_slope`

to change specific values in the EEPROM

- Add the following coroutines to read product data:

| Name | Data Item |
| --------------------------- | ----------------------------------------- |
| `get_gtin` | GTIN (Global Trade Identification Number) |
| `get_hardware_version` | Hardware Version Number |
| `get_firmware_version` | Firmware Version Number |
| `get_firmware_release_name` | Firmware Release Name |
| `get_serial_number` | Serial Number |
| `get_product_name` | Product Name |
| `get_oem_data` | OEM (Free Use) Data |

Status

- Add wrapper class for the [`Get/Set State`](https://mytoolit.github.io/Documentation/#command-getset-state) command

Documentation

- Add [STH renaming tutorial](https://github.com/MyTooliT/ICOc/blob/4028eefd/Documentation/Tutorials/Renaming.md)

EEPROM Checker

- The EEPROM checker (`check-eeprom`) now uses [the new network class](https://github.com/MyTooliT/ICOc/blob/4028eefd/mytoolit/can/network.py).

ICOc

- We fixed the sporadic crashes of the graphical plotter interface. You should not see messages about “WinError 10061” any more, when you try to read acceleration data with `icoc`.

STH Test

- The test now uses the serial number (`STH` → `SERIAL NUMBER`) as new name, if you set the status (`STH` → `STATUS`) to `Epoxied` in the [configuration](https://github.com/MyTooliT/ICOc/blob/4028eefd/mytoolit/config/config.yaml). If you use use a different status, then the test will still use the [Base64 encoded MAC address](https://github.com/MyTooliT/ICOc/issues/1) as new (Bluetooth advertisement) name.
- Remove wait time (of 2 seconds) after Bluetooth connection was established. In theory this should make the test execution quite a bit faster, without any adverse effects.

Internal

Message

- The string representation of a message (`repr`) now includes additional information for:

- [EEPROM commands](https://mytoolit.github.io/Documentation/#block-eeprom), and
- the [Bluetooth commands](https://mytoolit.github.io/Documentation/#command:bluetooth):
- [to request a connection](https://mytoolit.github.io/Documentation/#command:bluetooth:7),
- [to check the connection status](https://mytoolit.github.io/Documentation/#command:bluetooth:8),
- [to deactivate the Bluetooth connection](https://mytoolit.github.io/Documentation/#command:bluetooth:9),
- [to retrieve the RSSI](https://mytoolit.github.io/Documentation/#command:bluetooth:12), and
- [to retrieve the MAC address](https://mytoolit.github.io/Documentation/#command:bluetooth:17)
- [to connect to a device using a MAC address](https://mytoolit.github.io/Documentation/#command:bluetooth:18)

Network (Old)

- Improve error message for disconnected CAN adapter

Network (New)

- The class now sends requests multiple times, if it does not receive an answer in a certain amount of time
- Improve error message for disconnected CAN adapter
- The class now logs sent and received messages on the CAN bus, if you change the logger level to `DEBUG` (`LOGGER`→`CAN`→`LEVEL` in the [configuration](https://github.com/MyTooliT/ICOc/blob/4028eefd/mytoolit/config/config.yaml))
- Renamed the following coroutines:

| Old Name | New Name |
| ----------------------------------- | ---------------------------- |
| `get_available_devices_bluetooth` | `get_available_devices` |
| `get_device_name_bluetooth` | `get_name` |
| `get_mac_address_bluetooth` | `get_mac_address` |
| `connect_device_number_bluetooth` | `connect_with_device_number` |
| `check_connection_device_bluetooth` | `is_connected` |

- Add the following coroutines

| Name | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| `connect_with_mac_address` | Connect to a device using its MAC address |
| `get_rssi` | Retrieve the RSSI (Received Signal Strength Indication) of a device |
| `get_sths` | Retrieve a list of available STHs |
| `connect_sth` | Directly connect to an STH using its<br/>• MAC address,<br/> • device number, or<br/> • name<br/> |
| `set_name` | Set the (Bluetooth advertisement) name of an STU or STH |

- Add coroutines:

- `read_eeprom`,
- `read_eeprom_float`,
- `read_eeprom_int`, and
- `read_eeprom_text`

to read EEPROM data

- Add coroutines

- `write_eeprom`,
- `write_eeprom_float`,
- `write_eeprom_int`, and
- `write_eeprom_text`,

to write EEPROM data

- Add the coroutines:

- `read_eeprom_advertisement_time_1`,
- `read_eeprom_name`,
- `read_eeprom_sleep_time_1`, and
- `read_eeprom_status`

to read specific parts of the EEPROM

- Add the coroutines:

- `write_eeprom_advertisement_time_1`,
- `write_eeprom_name`,
- `write_eeprom_sleep_time_1`, and
- `write_eeprom_status`

to write specific parts of the EEPROM

Checks

- We also check the code base with the static type checker [Mypy](https://mypy.readthedocs.io)

GitHub Actions

- We now also test ICOc on Ubuntu Linux

Package

- We now use the version number specified in the [init file of the package](https://github.com/MyTooliT/ICOc/blob/5490bce1/mytoolit/__init__.py) for the package version number.
- You can now also install the Package on Linux (and macOS)

Requirements

- The package now uses the `EUI` (Extended Unique Identifier) class of the [`netaddr`](https://netaddr.readthedocs.io) package to handle MAC addresses

Scripts

- We added a script that removes log and PDF files from the repository root. For more information please take a look at the section “Remove Log and PDF Files” of the [script documentation](https://github.com/MyTooliT/ICOc/blob/5490bce1/Documentation/Scripts.md).

STH Test

- The report of the STH test now also contains information about the used acceleration sensor (±100 g or ± 50 g)
- We added a [configuration item](https://github.com/MyTooliT/ICOc/blob/5490bce1/mytoolit/config/config.yaml) for the holder type (`STH` → `HOLDER TYPE`)
- We added the holder type and the serial number to the PDF report
- Removed extra space before and after headers in PDF report
- The PDF report now contains a list of tables with checkboxes for manual checks

Internal

Checkbox

- New `Flowable` class that can be used to add a checkbox to a PDF report

Command

- Add method `is_error` to check if the current command represents an error
- Add method `set_error` to set or unset the error bit

Identifier

- Add method `acknowledge` to retrieve expected acknowledgment identifier for id
- Add method `is_error` to check if the current identifier represents an error message
- Add method `set_error` to set or unset the error bit
- Support comparison with other identifiers (`==`)

Message

- The class now uses the class `Message` of python-can to store data instead of the class `TPCANMsg` of the PCAN-Basic API
- Add method `identifier` to receive an identifier object for the current message
- Add accessor to set and retrieve message data (`.data`)
- The method `acknowledge` now stores the data of the message in the acknowledgment message
- Fix conversion into `python-can` message for non-empty data field
- Add explanation to string representation for Bluetooth “Activate” and “Get number of available devices” [subcommand](https://mytoolit.github.io/Documentation/#value:bluetooth-subcommand)

Network (New)

- Add coroutine (`reset_node`) to reset a node in the network
- Add coroutine (`activate_bluetooth`) to activate Bluetooth on a node in the network
- Add coroutine (`get_available_devices_bluetooth`) to retrieve the number of available Bluetooth devices
- Add coroutine (`get_device_name_bluetooth`) to retrieve the Bluetooth advertisement name of a device
- Add coroutine (`connect_device_number_bluetooth`) to connect to a Bluetooth device using the device number
- Add coroutine (`deactivate_bluetooth`) to deactivate the Bluetooth connection of a node
- Add coroutine (`check_connection_device_bluetooth`) to check if a Bluetooth device is connected to a node
- Add coroutine (`get_mac_address_bluetooth`) to retrieve the MAC address of a connected Bluetooth device
- Implement context manager interface (`with … as`)
- The code now checks part of the acknowledgement data for the Bluetooth and reset commands of the `System` block

Report

- Add method `add_checkbox_list` to add a list of checkboxes at the end of the PDF report

Utility

- Add function `bytearray_to_text` to convert byte data to a string