git.basschouten.com Git - openhab-addons.git/blob

   1 /**
   2  * Copyright (c) 2010-2024 Contributors to the openHAB project
   3  *
   4  * See the NOTICE file(s) distributed with this work for additional
   5  * information.
   6  *
   7  * This program and the accompanying materials are made available under the
   8  * terms of the Eclipse Public License 2.0 which is available at
   9  * http://www.eclipse.org/legal/epl-2.0
  10  *
  11  * SPDX-License-Identifier: EPL-2.0
  12  */
  13 package org.openhab.binding.systeminfo.internal.model;
  14
  15 import javax.measure.quantity.ElectricPotential;
  16 import javax.measure.quantity.Frequency;
  17 import javax.measure.quantity.Temperature;
  18 import javax.measure.quantity.Time;
  19
  20 import org.eclipse.jdt.annotation.NonNullByDefault;
  21 import org.eclipse.jdt.annotation.Nullable;
  22 import org.openhab.core.library.dimension.DataAmount;
  23 import org.openhab.core.library.types.DecimalType;
  24 import org.openhab.core.library.types.PercentType;
  25 import org.openhab.core.library.types.QuantityType;
  26 import org.openhab.core.library.types.StringType;
  27
  28 /**
  29  * {@link SysteminfoInterface} defines the methods needed to provide this binding with the required system information.
  30  *
  31  * @author Svilen Valkanov - Initial contribution
  32  * @author Wouter Born - Add null annotations
  33  * @author Mark Herwege - Add dynamic creation of extra channels
  34  * @author Mark Herwege - Use units of measure
  35  * @author Mark Herwege - Processor frequency channels
  36  */
  37 @NonNullByDefault
  38 public interface SysteminfoInterface {
  39
  40     /**
  41      * Initialize logic for the Systeminfo implementation
  42      */
  43     void initializeSysteminfo();
  44
  45     // Operating system info
  46     /**
  47      * Get the Family of the operating system /e.g. Windows, Unix,.../
  48      */
  49     StringType getOsFamily();
  50
  51     /**
  52      * Get the manufacturer of the operating system
  53      */
  54     StringType getOsManufacturer();
  55
  56     /**
  57      * Get the version of the operating system
  58      *
  59      * @return
  60      */
  61     StringType getOsVersion();
  62
  63     // CPU info
  64     /**
  65      * Get the name of the CPU
  66      */
  67     StringType getCpuName();
  68
  69     /**
  70      * Get description about the CPU e.g (model, family, vendor, serial number, identifier, architecture(32bit or
  71      * 64bit))
  72      */
  73     StringType getCpuDescription();
  74
  75     /**
  76      * Get the number of logical CPUs/cores available for processing.
  77      */
  78     DecimalType getCpuLogicalCores();
  79
  80     /**
  81      * Get the number of physical CPUs/cores available for processing.
  82      */
  83     DecimalType getCpuPhysicalCores();
  84
  85     /**
  86      * Get the maximum CPU frequency of the processor.
  87      */
  88     @Nullable
  89     QuantityType<Frequency> getCpuMaxFreq();
  90
  91     /**
  92      * Get the current CPU frequency of a logical processor.
  93      */
  94     @Nullable
  95     QuantityType<Frequency> getCpuFreq(int logicalProcessorIndex);
  96
  97     /**
  98      * Returns the system cpu load.
  99      *
 100      * @return the system cpu load between 0 and 100% or null, if no information is available
 101      */
 102     @Nullable
 103     PercentType getSystemCpuLoad();
 104
 105     /**
 106      * Returns the system load average for the last minute.
 107      *
 108      * @return the load as a number of processes or null, if no information is available
 109      */
 110     @Nullable
 111     DecimalType getCpuLoad1();
 112
 113     /**
 114      * Returns the system load average for the last 5 minutes.
 115      *
 116      * @return the load as number of processes or null, if no information is available
 117      */
 118     @Nullable
 119     DecimalType getCpuLoad5();
 120
 121     /**
 122      * Returns the system load average for the last 15 minutes.
 123      *
 124      * @return the load as number of processes or null, if no information is available
 125      */
 126     @Nullable
 127     DecimalType getCpuLoad15();
 128
 129     /**
 130      * Get the System uptime (time since boot).
 131      *
 132      * @return time since boot
 133      */
 134     QuantityType<Time> getCpuUptime();
 135
 136     /**
 137      * Get the number of threads currently running
 138      *
 139      * @return number of threads
 140      */
 141     DecimalType getCpuThreads();
 142
 143     // Memory info
 144     /**
 145      * Returns total size of memory
 146      *
 147      * @return memory size
 148      */
 149     QuantityType<DataAmount> getMemoryTotal();
 150
 151     /**
 152      * Returns available size of memory
 153      *
 154      * @return memory size
 155      */
 156     QuantityType<DataAmount> getMemoryAvailable();
 157
 158     /**
 159      * Returns used size of memory
 160      *
 161      * @return memory size
 162      */
 163     QuantityType<DataAmount> getMemoryUsed();
 164
 165     /**
 166      * Percents of available memory on the machine
 167      *
 168      * @return percent of available memory or null, if no information is available
 169      */
 170     @Nullable
 171     PercentType getMemoryAvailablePercent();
 172
 173     /**
 174      * Percents of used memory on the machine
 175      *
 176      * @return percent of used memory or null, if no information is available
 177      */
 178     @Nullable
 179     PercentType getMemoryUsedPercent();
 180
 181     // Swap memory info
 182     /**
 183      * Returns total size of swap memory
 184      *
 185      * @return memory size or 0, if there is no swap memory
 186      */
 187     QuantityType<DataAmount> getSwapTotal();
 188
 189     /**
 190      * Returns available size swap of memory
 191      *
 192      * @return memory size or 0, if no there is no swap memory
 193      */
 194     QuantityType<DataAmount> getSwapAvailable();
 195
 196     /**
 197      * Returns used size of swap memory
 198      *
 199      * @return memory size or 0, if no there is no swap memory
 200      */
 201     QuantityType<DataAmount> getSwapUsed();
 202
 203     /**
 204      * Percents of available swap memory on the machine
 205      *
 206      * @return percent of available memory or null, if no there is no swap memory
 207      */
 208     @Nullable
 209     PercentType getSwapAvailablePercent();
 210
 211     /**
 212      * Percents of used swap memory on the machine
 213      *
 214      * @return percent of used memory or null, if no there is no swap memory
 215      */
 216     @Nullable
 217     PercentType getSwapUsedPercent();
 218
 219     // Storage info
 220     /**
 221      * Returns the total space of the logical storage volume.
 222      *
 223      * @param deviceIndex - the index of the logical volume
 224      * @return storage size
 225      * @throws DeviceNotFoundException
 226      */
 227     QuantityType<DataAmount> getStorageTotal(int deviceIndex) throws DeviceNotFoundException;
 228
 229     /**
 230      * Returns the available storage space on the logical storage volume
 231      *
 232      * @param deviceIndex - the index of the logical volume
 233      * @return storage size
 234      * @throws DeviceNotFoundException
 235      */
 236     QuantityType<DataAmount> getStorageAvailable(int deviceIndex) throws DeviceNotFoundException;
 237
 238     /**
 239      * Gets the used storage space on the logical storage volume
 240      *
 241      * @param deviceIndex - the index of the logical volume
 242      * @return storage size
 243      * @throws DeviceNotFoundException
 244      */
 245     QuantityType<DataAmount> getStorageUsed(int deviceIndex) throws DeviceNotFoundException;
 246
 247     /**
 248      * Gets the percent of available storage on the logical volume
 249      *
 250      * @param deviceIndex - the index of the logical volume
 251      * @return percent of available storage or null
 252      * @throws DeviceNotFoundException
 253      */
 254     @Nullable
 255     PercentType getStorageAvailablePercent(int deviceIndex) throws DeviceNotFoundException;
 256
 257     /**
 258      * Gets the percent of used storage on the logical volume
 259      *
 260      * @param deviceIndex - the index of the logical volume
 261      * @return percent of used storage or null
 262      * @throws DeviceNotFoundException
 263      */
 264     @Nullable
 265     PercentType getStorageUsedPercent(int deviceIndex) throws DeviceNotFoundException;
 266
 267     /**
 268      * Gets the name of the logical storage volume
 269      *
 270      * @throws DeviceNotFoundException
 271      */
 272     StringType getStorageName(int deviceIndex) throws DeviceNotFoundException;
 273
 274     /**
 275      * Gets the type of the logical storage volume (e.g. NTFS, FAT32)
 276      *
 277      * @throws DeviceNotFoundException
 278      */
 279     StringType getStorageType(int deviceIndex) throws DeviceNotFoundException;
 280
 281     /**
 282      * Gets the description of the logical storage volume
 283      *
 284      * @throws DeviceNotFoundException
 285      */
 286     StringType getStorageDescription(int deviceIndex) throws DeviceNotFoundException;
 287
 288     // Hardware drive info
 289     /**
 290      * Gets the name of the physical storage drive
 291      *
 292      * @param deviceIndex - index of the storage drive
 293      * @throws DeviceNotFoundException
 294      */
 295     StringType getDriveName(int deviceIndex) throws DeviceNotFoundException;
 296
 297     /**
 298      * Gets the model of the physical storage drive
 299      *
 300      * @param deviceIndex - index of the storage drive
 301      * @throws DeviceNotFoundException
 302      */
 303     StringType getDriveModel(int deviceIndex) throws DeviceNotFoundException;
 304
 305     /**
 306      * Gets the serial number of the physical storage drive
 307      *
 308      * @param deviceIndex - index of the storage drive
 309      * @throws DeviceNotFoundException
 310      */
 311     StringType getDriveSerialNumber(int deviceIndex) throws DeviceNotFoundException;
 312
 313     // Network info
 314     /**
 315      * Get the Host IP address of the network.
 316      *
 317      * @param networkIndex - the index of the network
 318      * @return 32-bit IPv4 address
 319      * @throws DeviceNotFoundException
 320      */
 321     StringType getNetworkIp(int networkIndex) throws DeviceNotFoundException;
 322
 323     /**
 324      * Get the name of this network.
 325      *
 326      * @param networkIndex - the index of the network
 327      * @throws DeviceNotFoundException
 328      */
 329     StringType getNetworkName(int networkIndex) throws DeviceNotFoundException;
 330
 331     /**
 332      * The description of the network. On some platforms, this is identical to the name.
 333      *
 334      * @param networkIndex - the index of the network
 335      * @throws DeviceNotFoundException
 336      */
 337     StringType getNetworkDisplayName(int networkIndex) throws DeviceNotFoundException;
 338
 339     /**
 340      * Gets the MAC Address of the network.
 341      *
 342      * @param networkIndex - the index of the network
 343      * @throws DeviceNotFoundException
 344      */
 345     StringType getNetworkMac(int networkIndex) throws DeviceNotFoundException;
 346
 347     /**
 348      * Get number of packets received
 349      *
 350      * @param networkIndex - the index of the network
 351      * @throws DeviceNotFoundException
 352      */
 353     DecimalType getNetworkPacketsReceived(int networkIndex) throws DeviceNotFoundException;
 354
 355     /**
 356      * Get number of packets sent
 357      *
 358      * @param networkIndex - the index of the network
 359      * @throws DeviceNotFoundException
 360      */
 361     DecimalType getNetworkPacketsSent(int networkIndex) throws DeviceNotFoundException;
 362
 363     /**
 364      * Get data sent for this network
 365      *
 366      * @param networkIndex - the index of the network
 367      * @throws DeviceNotFoundException
 368      */
 369     QuantityType<DataAmount> getNetworkDataSent(int networkIndex) throws DeviceNotFoundException;
 370
 371     /**
 372      * Get data received for this network
 373      *
 374      * @param networkIndex - the index of the network
 375      * @throws DeviceNotFoundException
 376      */
 377     QuantityType<DataAmount> getNetworkDataReceived(int networkIndex) throws DeviceNotFoundException;
 378
 379     // Display info
 380     /**
 381      * Get information about the display device as product number, manufacturer, serial number, width and height in cm";
 382      *
 383      * @param deviceIndex - the index of the display device
 384      * @throws DeviceNotFoundException
 385      */
 386     StringType getDisplayInformation(int deviceIndex) throws DeviceNotFoundException;
 387
 388     // Sensors info
 389     /**
 390      * Get the information from the CPU temperature sensors.
 391      *
 392      * @return Temperature if available, null otherwise.
 393      */
 394     @Nullable
 395     QuantityType<Temperature> getSensorsCpuTemperature();
 396
 397     /**
 398      * Get the information for the CPU voltage.
 399      *
 400      * @return Voltage if available, null otherwise.
 401      */
 402     @Nullable
 403     QuantityType<ElectricPotential> getSensorsCpuVoltage();
 404
 405     /**
 406      * Get fan speed
 407      *
 408      * @param deviceIndex
 409      * @return Speed in rpm or null if unable to measure fan speed
 410      * @throws DeviceNotFoundException
 411      */
 412     @Nullable
 413     DecimalType getSensorsFanSpeed(int deviceIndex) throws DeviceNotFoundException;
 414
 415     // Battery info
 416     /**
 417      * Get estimated time remaining for the power source.
 418      *
 419      * @param deviceIndex
 420      * @return duration remaining charge or null, if the time is estimated as unlimited
 421      * @throws DeviceNotFoundException
 422      */
 423     @Nullable
 424     QuantityType<Time> getBatteryRemainingTime(int deviceIndex) throws DeviceNotFoundException;
 425
 426     /**
 427      * Battery remaining capacity.
 428      *
 429      * @param deviceIndex
 430      * @return percentage value
 431      * @throws DeviceNotFoundException
 432      */
 433     PercentType getBatteryRemainingCapacity(int deviceIndex) throws DeviceNotFoundException;
 434
 435     /**
 436      * Get battery name
 437      *
 438      * @param deviceIndex
 439      * @throws DeviceNotFoundException
 440      */
 441     StringType getBatteryName(int deviceIndex) throws DeviceNotFoundException;
 442
 443     /**
 444      * Get PID of process executing this code
 445      *
 446      * @return current process ID
 447      */
 448     int getCurrentProcessID();
 449
 450     /**
 451      * Returns the name of the process
 452      *
 453      * @param pid - the PID of the process
 454      * @throws DeviceNotFoundException - thrown if process with this PID can not be found
 455      */
 456     @Nullable
 457     StringType getProcessName(int pid) throws DeviceNotFoundException;
 458
 459     /**
 460      * Returns the CPU usage of the process
 461      *
 462      * @param pid - the PID of the process
 463      * @return - percentage value, can be above 100% if process uses multiple cores
 464      * @throws DeviceNotFoundException - thrown if process with this PID can not be found
 465      */
 466     @Nullable
 467     DecimalType getProcessCpuUsage(int pid) throws DeviceNotFoundException;
 468
 469     /**
 470      * Returns the size of RAM memory only usage of the process
 471      *
 472      * @param pid - the PID of the process
 473      * @return memory size
 474      * @throws DeviceNotFoundException thrown if process with this PID can not be found
 475      */
 476     @Nullable
 477     QuantityType<DataAmount> getProcessMemoryUsage(int pid) throws DeviceNotFoundException;
 478
 479     /**
 480      * Returns the full path of the executing process.
 481      *
 482      * @param pid - the PID of the process
 483      * @throws DeviceNotFoundException - thrown if process with this PID can not be found
 484      */
 485     @Nullable
 486     StringType getProcessPath(int pid) throws DeviceNotFoundException;
 487
 488     /**
 489      * Returns the number of threads in this process.
 490      *
 491      * @param pid - the PID of the process
 492      * @throws DeviceNotFoundException - thrown if process with this PID can not be found
 493      */
 494     @Nullable
 495     DecimalType getProcessThreads(int pid) throws DeviceNotFoundException;
 496
 497     /**
 498      * Returns the number of network interfaces.
 499      *
 500      * @return network interface count
 501      */
 502     int getNetworkIFCount();
 503
 504     /**
 505      * Returns the number of displays.
 506      *
 507      * @return display count
 508      */
 509     int getDisplayCount();
 510
 511     /**
 512      * Returns the number of storages.
 513      *
 514      * @return storage count
 515      */
 516     int getFileOSStoreCount();
 517
 518     /**
 519      * Returns the number of power sources/batteries.
 520      *
 521      * @return power source count
 522      */
 523     int getPowerSourceCount();
 524
 525     /**
 526      * Returns the number of drives.
 527      *
 528      * @return drive count
 529      */
 530     int getDriveCount();
 531
 532     /**
 533      * Returns the number of fans.
 534      *
 535      * @return fan count
 536      */
 537     int getFanCount();
 538 }