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