system#

class platypush.plugins.system.SystemPlugin(*_, **__)[source]#

Bases: SensorPlugin, EntityManager

Plugin to get system info.

Requires:

  • py-cpuinfo (pip install py-cpuinfo) for CPU model and info.

  • psutil (pip install psutil) for CPU load and stats.

__init__(*args, poll_interval: float | None = 60, **kwargs)[source]#
Parameters:
  • thresholds

    A number, numeric pair or mapping of str to number/numeric pair representing the thresholds for the sensor.

    Examples:

    # Any value below 25 from any sensor will trigger a
    # SensorDataBelowThresholdEvent, if the previous value was
    # equal or above, and any value above 25 will trigger a
    # SensorDataAboveThresholdEvent, if the previous value was
    # equal or below
    thresholds: 25.0
    
    # Same as above, but the threshold is only applied to
    # ``temperature`` readings
    thresholds:
        temperature: 25.0
    
    # Any value below 20 from any sensor will trigger a
    # SensorDataBelowThresholdEvent, if the previous value was
    # equal or above, and any value above 25 will trigger a
    # SensorDataAboveThresholdEvent, if the previous value was
    # equal or below (hysteresis configuration with double
    # threshold)
    thresholds:
        - 20.0
        - 25.0
    
    # Same as above, but the threshold is only applied to
    # ``temperature`` readings
    thresholds:
        temperature:
            - 20.0
            - 25.0
    

  • tolerance

    If set, then the sensor change events will be triggered only if the difference between the new value and the previous value is higher than the specified tolerance. For example, if the sensor data is mapped to a dictionary:

    {
        "temperature": 0.01,  # Tolerance on the 2nd decimal digit
        "humidity": 0.1       # Tolerance on the 1st decimal digit
    }
    

    Or, if it’s a raw scalar number:

    0.1  # Tolerance on the 1st decimal digit
    

    Or, if it’s a list of values:

    [
        0.01,   # Tolerance on the 2nd decimal digit for the first value
        0.1     # Tolerance on the 1st decimal digit for the second value
    ]
    

  • enabled_sensors – If get_measurement() returns a key-value mapping, and enabled_sensors is set, then only the reported sensor keys will be returned.

connected_users() List[dict][source]#

Get the list of connected users.

Returns:

{
  "pid": 12345,
  "started": "2023-08-04T23:51:21.181663+00:00",
  "terminal": "pts/1",
  "username": "root"
}

cpu_frequency(per_cpu: bool = False) CpuFrequency | List[CpuFrequency][source]#

Get the CPU frequency, in MHz.

Parameters:

per_cpu – Get per-CPU stats (default: False).

Returns:

If per_cpu=False:

{
  "current": 39,
  "max": 75,
  "min": 63
}

If per_cpu=True then a list will be returned, where each item identifies the CPU times of a core:

[
  {
    "current": 92,
    "max": 6,
    "min": 36
  }
]
cpu_info()[source]#

Get CPU info. :return: .. schema:: system.CpuInfoSchema

cpu_percent(per_cpu: bool = False, interval: float | None = None) float | List[float][source]#

Get the CPU load percentage.

Parameters:
  • per_cpu – Get per-CPU stats (default: False).

  • interval – When interval is 0.0 or None compares system CPU times elapsed since last call or module import, returning immediately (non blocking). That means the first time this is called it will return a meaningless 0.0 value which you should ignore. In this case is recommended for accuracy that this function be called with at least 0.1 seconds between calls.

Returns:

float if per_cpu=False, list[float] otherwise.

cpu_stats() CpuStats[source]#

Get CPU stats.

Returns:

{
  "ctx_switches": 43,
  "interrupts": 4,
  "soft_interrupts": 95,
  "syscalls": 34
}

cpu_times(per_cpu=False, percent=True) list | dict[source]#

Get the CPU times per status, either as absolute time or a percentage.

Parameters:
  • per_cpu – Get per-CPU stats (default: False).

  • percent – Get the stats in percentage (default: True).

Returns:

If per_cpu=False:

{
  "guest": 34,
  "guest_nice": 32,
  "idle": 22,
  "iowait": 47,
  "irq": 6,
  "nice": 54,
  "softirq": 27,
  "steal": 73,
  "system": 84,
  "user": 5
}

If per_cpu=True then a list will be returned, where each item identifies the CPU times of a core:

[
  {
    "guest": 81,
    "guest_nice": 26,
    "idle": 44,
    "iowait": 51,
    "irq": 70,
    "nice": 48,
    "softirq": 38,
    "steal": 28,
    "system": 17,
    "user": 37
  }
]
disk_info()[source]#

Get information about the detected disks and partitions.

Returns:

[
  {
    "busy_time": "Total disk busy time, in seconds",
    "device": "/dev/sda1",
    "free": "Free disk space, in bytes",
    "fstype": "ext4",
    "mountpoint": "/home",
    "opts": "rw,relatime,fmask=0022,dmask=0022,utf8",
    "percent": 50,
    "read_bytes": "Number of read bytes",
    "read_count": "Number of recorded read operations",
    "read_time": "Time spent reading, in seconds",
    "total": "Total available space, in bytes",
    "used": "Used disk space, in bytes",
    "write_bytes": "Number of written bytes",
    "write_count": "Number of recorded write operations",
    "write_time": "Time spent writing, in seconds"
  }
]

get_measurement(*_, **__)[source]#
Returns:

{
  "battery": {
    "power_plugged": "Whether the battery is plugged in or not",
    "seconds_left": 75,
    "value": 92
  },
  "cpu": {
    "frequency": {
      "current": 33,
      "max": 77,
      "min": 71
    },
    "info": {
      "architecture": "x86_64",
      "bits": 64,
      "brand": "Intel(R) Core(TM) i7-5500U CPU @ 2.40GHz",
      "cores": 4,
      "flags": [
        "acpi",
        "aes",
        "cpuid"
      ],
      "frequency_actual": 2350000000,
      "frequency_advertised": 2400000000,
      "l1_data_cache_size": 65536,
      "l1_instruction_cache_size": 65536,
      "l2_cache_size": 524288,
      "l3_cache_size": 4194304,
      "vendor": "GenuineIntel"
    },
    "load_avg": "tuple",
    "percent": 62,
    "stats": {
      "ctx_switches": 96,
      "interrupts": 7,
      "soft_interrupts": 63,
      "syscalls": 21
    },
    "times": {
      "guest": 11,
      "guest_nice": 26,
      "idle": 80,
      "iowait": 47,
      "irq": 56,
      "nice": 71,
      "softirq": 71,
      "steal": 94,
      "system": 48,
      "user": 55
    }
  },
  "disks": [
    {
      "busy_time": "Total disk busy time, in seconds",
      "device": "/dev/sda1",
      "free": "Free disk space, in bytes",
      "fstype": "ext4",
      "mountpoint": "/home",
      "opts": "rw,relatime,fmask=0022,dmask=0022,utf8",
      "percent": 27,
      "read_bytes": "Number of read bytes",
      "read_count": "Number of recorded read operations",
      "read_time": "Time spent reading, in seconds",
      "total": "Total available space, in bytes",
      "used": "Used disk space, in bytes",
      "write_bytes": "Number of written bytes",
      "write_count": "Number of recorded write operations",
      "write_time": "Time spent writing, in seconds"
    }
  ],
  "fans": [
    {
      "id": "acpi_1",
      "label": "CPU",
      "value": 3000
    }
  ],
  "memory": {
    "active": "Size of the active memory, in bytes",
    "available": "Available memory, in bytes",
    "buffers": "Size of the buffered memory, in bytes",
    "cached": "Size of the cached memory, in bytes",
    "free": "Free memory, in bytes",
    "inactive": "Size of the inactive memory, in bytes",
    "percent": 44,
    "shared": "Size of the shared memory, in bytes",
    "total": "Total available memory, in bytes",
    "used": "Used memory, in bytes"
  },
  "network": [
    {
      "addresses": [
        {
          "address": "192.168.1.2",
          "broadcast": "192.168.1.255",
          "family": "AF_INET",
          "netmask": "255.255.255.0"
        }
      ],
      "bytes_recv": "Number of bytes received",
      "bytes_sent": "Number of bytes sent",
      "drop_in": "Number of packets dropped on incoming traffic",
      "drop_out": "Number of packets dropped on outgoing traffic",
      "duplex": "FULL",
      "errors_in": "Number of errors on incoming traffic",
      "errors_out": "Number of errors on outgoing traffic",
      "flags": [
        "up",
        "broadcast",
        "running"
      ],
      "interface": "eth0",
      "is_up": true,
      "mtu": 65535,
      "packets_recv": "Number of packets received",
      "packets_sent": "Number of packets sent",
      "speed": 10000
    }
  ],
  "swap": {
    "free": "Free memory, in bytes",
    "percent": 80,
    "total": "Total available memory, in bytes",
    "used": "Used memory, in bytes"
  },
  "temperature": [
    {
      "critical": 95,
      "high": 75,
      "id": "acpi_1",
      "label": "CPU",
      "value": 55
    }
  ]
}

kill(pid: int)[source]#

Kill a process. :param pid: Process PID.

load_avg() Tuple[float, float, float][source]#

Get the average load as a vector that represents the load within the last 1, 5 and 15 minutes.

mem_swap() dict[source]#

Get the current swap memory usage stats.

Returns:

{
  "free": "Free memory, in bytes",
  "percent": 82,
  "total": "Total available memory, in bytes",
  "used": "Used memory, in bytes"
}

mem_virtual() dict[source]#

Get the current virtual memory usage stats.

Returns:

{
  "active": "Size of the active memory, in bytes",
  "available": "Available memory, in bytes",
  "buffers": "Size of the buffered memory, in bytes",
  "cached": "Size of the cached memory, in bytes",
  "free": "Free memory, in bytes",
  "inactive": "Size of the inactive memory, in bytes",
  "percent": 21,
  "shared": "Size of the shared memory, in bytes",
  "total": "Total available memory, in bytes",
  "used": "Used memory, in bytes"
}

network_connections(type: str = 'inet') List[dict][source]#

Get the list of active network connections. On MacOS this function requires root privileges.

Parameters:

type

Connection type to filter (default: inet). Supported types:

type

Description

inet inet4 inet6 tcp tcp4 tcp6 udp udp4 udp6 unix all

IPv4 and IPv6 IPv4 IPv6 TCP TCP over IPv4 TCP over IPv6 UDP UDP over IPv4 UDP over IPv6 UNIX socket (both UDP and TCP protocols) Any families and protocols

Returns:

[
  {
    "family": "AF_INET",
    "fd": 3,
    "local_address": "192.168.1.2",
    "local_port": 12345,
    "pid": 4321,
    "remote_address": "192.168.1.1",
    "remote_port": 443,
    "status": "ESTABLISHED",
    "type": "SOCK_STREAM"
  }
]

network_info(per_nic: bool = False)[source]#

Get the information and statistics for the network interfaces.

Parameters:

per_nic – Return the stats grouped by interface (default: False).

Returns:

If per_nic=False:

{
  "addresses": [
    {
      "address": "192.168.1.2",
      "broadcast": "192.168.1.255",
      "family": "AF_INET",
      "netmask": "255.255.255.0"
    }
  ],
  "bytes_recv": "Number of bytes received",
  "bytes_sent": "Number of bytes sent",
  "drop_in": "Number of packets dropped on incoming traffic",
  "drop_out": "Number of packets dropped on outgoing traffic",
  "duplex": "FULL",
  "errors_in": "Number of errors on incoming traffic",
  "errors_out": "Number of errors on outgoing traffic",
  "flags": [
    "up",
    "broadcast",
    "running"
  ],
  "interface": "eth0",
  "is_up": true,
  "mtu": 65535,
  "packets_recv": "Number of packets received",
  "packets_sent": "Number of packets sent",
  "speed": 10000
}

If per_nic=True then a list will be returned, where each item identifies the statistics per network interface:

[
  {
    "addresses": [
      {
        "address": "192.168.1.2",
        "broadcast": "192.168.1.255",
        "family": "AF_INET",
        "netmask": "255.255.255.0"
      }
    ],
    "bytes_recv": "Number of bytes received",
    "bytes_sent": "Number of bytes sent",
    "drop_in": "Number of packets dropped on incoming traffic",
    "drop_out": "Number of packets dropped on outgoing traffic",
    "duplex": "FULL",
    "errors_in": "Number of errors on incoming traffic",
    "errors_out": "Number of errors on outgoing traffic",
    "flags": [
      "up",
      "broadcast",
      "running"
    ],
    "interface": "eth0",
    "is_up": true,
    "mtu": 65535,
    "packets_recv": "Number of packets received",
    "packets_sent": "Number of packets sent",
    "speed": 10000
  }
]
pid_exists(pid: int) bool[source]#
Parameters:

pid – Process PID.

Returns:

True if the process exists, False otherwise.

processes() List[dict][source]#

Get the list of running processes.

Returns:

{
  "command_line": [
    "/usr/bin/python",
    "-m",
    "platypush"
  ],
  "cpu_percent": 93,
  "current_directory": "/root",
  "memory_percent": 38,
  "name": "python",
  "parent_pid": 1000,
  "pid": 12345,
  "started": "2023-08-04T23:51:21.168687+00:00",
  "status": "running",
  "terminal": "pts/1",
  "username": "root"
}

resume(pid: int)[source]#

Resume a process. :param pid: Process PID.

sensors_battery() dict | None[source]#

Get stats from the battery sensor.

Returns:

{
  "power_plugged": "Whether the battery is plugged in or not",
  "seconds_left": 75,
  "value": 42
}

sensors_fan() List[dict][source]#

Get stats from the fan sensors.

Returns:

[
  {
    "id": "acpi_1",
    "label": "CPU",
    "value": 3000
  }
]

sensors_temperature() List[dict][source]#

Get stats from the temperature sensors.

Returns:

[
  {
    "critical": 95,
    "high": 75,
    "id": "acpi_1",
    "label": "CPU",
    "value": 55
  }
]

suspend(pid: int)[source]#

Suspend a process. :param pid: Process PID.

terminate(pid: int)[source]#

Terminate a process. :param pid: Process PID.

transform_entities(entities: dict) List[Entity][source]#

This method takes a list of entities in any (plugin-specific) format and converts them into a standardized collection of Entity objects. Since this method is called by publish_entities() before entity updates are published, you may usually want to extend it to pre-process the entities managed by your extension into the standard format before they are stored and published to all the consumers.

wait(pid: int, timeout: int | None = None)[source]#

Wait for a process to terminate.

Parameters:
  • pid – Process PID.

  • timeout – Timeout in seconds (default: None).