IoTuring 2024.2.1

Simple and powerful cross-platform script to control your pc and share statistics using communication protocols like MQTT and home control hubs like HomeAssistant.

IoTuring

If you really like this project and you would like to support it:

The project

Simple and powerful cross-platform script to control your pc and share statistics using communication protocols like MQTT and home control hubs like HomeAssistant.

Like his predecessor - PyMonitorMQTT - IoTuring allows you to choose which data are sent and which command are expected to be given.

Why should you use this ? You don't have to write your configurations manually, entities are updated asynchronously and multiple warehouses can be used with one single run (and this is not deprecated obviously!).

But the most important thing: works on all OSs and all architectures ! Windows, Linux, macOS, openBSD; x86, amd64, ARM and so on...

CHANGELOG: available in Releases page

Install

Who knows how it works

Using pip (on Python >= 3.8) install the IoTuring package

pip install IoTuring

Run with IoTuring or python -m IoTuring

Configure with IoTuring -c or python -m IoTuring -c

Who doesn't know how it works

Requirements

• Python 3.8+
• Pip

Some platforms may need other software for some entities.

Install all requirements on ArchLinux

pacman -Syu python python-pip

Install and update all requirements on Debian or Ubuntu

apt install python3 python3-pip -y
pip install --upgrade pip

Windows

• Python, pip included

Download and install with pip

On Linux and macOS:

pip install IoTuring

On Windows:

py -m pip install IoTuring

Note: on Windows you have to prefix every command with py -m as here.

Configure

The first time you run IoTuring you need to specify which entities and warehouses you want to enable. To run in configuration mode, you only need to specify the '-c' argument along the script execution command:

python -m IoTuring -c

A simple menu will show and you will be able to configure your entities and warehouses ! Once you have selected your preferred settings, you're ready to run IoTuring.

You will be able to enter the configuration menu whenever you want (with the same command as above) to edit your choises.

Run

You can simply run IoTuring using this command

IoTuring

or this one

python -m IoTuring

Docker

Run the configurator:

docker run -it -v ./.config/IoTuring/:/config richibrics/ioturing:latest IoTuring -c

Enable the Console Warehouse to see logs!

Run detached after configuration:

docker run -d -v ./.config/IoTuring/:/config richibrics/ioturing:latest

For a docker compose example see docker-compose.yaml. Create configuration manually or with the command above!

HomeAssistant demo

Your computer will show up in HomeAssistant as a single Device, so all your entities will be grouped together. The device will also have some properties like connectivity and battery status.

You can see how your device will appear under the Devices section in Home Assistant in the following GIF (wait until it's loaded):

All sensors and switches will be available to be added to your dashboard in your favourite cards !

Features

Available entities

Name	Description	Supported platforms
ActiveWindow	shares the name of the window you're working on
AppInfo	shares app informations like the running version
Battery	shares the battery level and charging status
BootTime	shares the machine boot time
Cpu	shares useful information about cpu usage (times, frequencies, percentages)
DesktopEnvironment	shares the running desktop environment (useful only for Linux)
Disk	shares disk usage data
DisplayMode	command for changing multimonitor display mode
Fanspeed	shares maximum fanspeed of each controller
Hostname	shares the machine hostname
Lock	command for locking the machine
Monitor	command for switching monitors on/off
Notify	displays a notification
OperatingSystem	shares the operating system of your machine
Power*	commands for poweroff, reboot and sleep
Ram	shares useful information about ram usage
Temperature	shares temperature sensor data
Terminal	runs custom commands in the shell
Time	shares the machine local time
Uptime	shares the time since the machine is on
Username	shares the name of the user who is working on the machine
Volume	control audio volume

* To use the features from Power entity on macOS and on some Linux distros you need to give permissions to your user to shutdown and reboot without sudo password. You can easily do that by using the following terminal command:

sudo sh -c "echo '$USER ALL=(ALL) NOPASSWD: /sbin/poweroff, /sbin/reboot, /sbin/shutdown' >> /etc/sudoers"

Available warehouses

• HomeAssistant: shares sensors and switches to HomeAssistant. The machine is shown as a Device and all the entites are grouped together. recommended
• MQTT: sends data to MQTT broker and subscribes to commands topics.
• Console: prints data to the console

Development

Editable install

Pip documentation

git clone https://github.com/richibrics/IoTuring
cd IoTuring
pip install -e .

Then run it like in the non-editable mode.

Warning: sometimes to run the module in editable mode you need to cd into the upper IoTuring folder.

Debug log

Overwrite log level with the IOTURING_LOG_LEVEL environment variable. For example to run IoTuring with debug log:

env IOTURING_LOG_LEVEL=LOG_DEBUG IoTuring

Versioning

The project uses calendar versioning:

YYYY.M.n:

• YYYY: Full year: 2022, 2023 ...
• M: Month: 1, 2 ... 11, 12
• n: Build number in the month: 1, 2 ...

Tests

To run tests in docker:

docker run --rm -it -v .:/srv/IoTuring:ro python:3.8.17-slim-bullseye /srv/IoTuring/tests/run_tests.sh

Docker

To build docker image:

docker build -t ioturing:latest .

Contributors

• @richibrics: Riccardo Briccola - Author
• @infeeeee - Main contributor
• @tsunglung

Acknowledgement

Icons in this readme are from Material Design Icons, License: Pictogrammers Free License

Notification icon is from Home Assistant: License: CC BY-SA 4.0