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

   1 /**
   2  * Copyright (c) 2010-2023 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.lcn.internal.common;
  14
  15 import org.eclipse.jdt.annotation.NonNullByDefault;
  16 import org.openhab.binding.lcn.internal.LcnBindingConstants;
  17 import org.slf4j.Logger;
  18 import org.slf4j.LoggerFactory;
  19
  20 /**
  21  * Helpers to generate LCN-PCK commands.
  22  * <p>
  23  * LCN-PCK is the command-syntax used by LCN-PCHK to send and receive LCN commands.
  24  *
  25  * @author Tobias Jüttner - Initial Contribution
  26  * @author Fabian Wolter - Migration to OH2
  27  */
  28 @NonNullByDefault
  29 public final class PckGenerator {
  30     private static final Logger LOGGER = LoggerFactory.getLogger(PckGenerator.class);
  31     /** Termination character after a PCK message */
  32     public static final String TERMINATION = "\n";
  33
  34     /**
  35      * Generates a keep-alive.
  36      * LCN-PCHK will close the connection if it does not receive any commands from
  37      * an open {@link Connection} for a specific period (10 minutes by default).
  38      *
  39      * @param counter the current ping's id (optional, but "best practice"). Should start with 1
  40      * @return the PCK command as text
  41      */
  42     public static String ping(int counter) {
  43         return String.format("^ping%d", counter);
  44     }
  45
  46     /**
  47      * Generates a PCK command that will set the LCN-PCHK connection's operation mode.
  48      * This influences how output-port commands and status are interpreted and must be
  49      * in sync with the LCN bus.
  50      *
  51      * @param dimMode see {@link LcnDefs.OutputPortDimMode}
  52      * @param statusMode see {@link LcnDefs.OutputPortStatusMode}
  53      * @return the PCK command as text
  54      */
  55     public static String setOperationMode(LcnDefs.OutputPortDimMode dimMode, LcnDefs.OutputPortStatusMode statusMode) {
  56         return "!OM" + (dimMode == LcnDefs.OutputPortDimMode.NATIVE200 ? "1" : "0")
  57                 + (statusMode == LcnDefs.OutputPortStatusMode.PERCENT ? "P" : "N");
  58     }
  59
  60     /**
  61      * Generates a PCK address header.
  62      * Used for commands to LCN modules and groups.
  63      *
  64      * @param addr the target's address (module or group)
  65      * @param localSegId the local segment id where the physical bus connection is located
  66      * @param wantsAck true to claim an acknowledge / receipt from the target
  67      * @return the PCK address header as text
  68      */
  69     public static String generateAddressHeader(LcnAddr addr, int localSegId, boolean wantsAck) {
  70         return String.format(">%s%03d%03d%s", addr.isGroup() ? "G" : "M", addr.getPhysicalSegmentId(localSegId),
  71                 addr.getId(), wantsAck ? "!" : ".");
  72     }
  73
  74     /**
  75      * Generates a scan-command for LCN segment-couplers.
  76      * Used to detect the local segment (where the physical bus connection is located).
  77      *
  78      * @return the PCK command (without address header) as text
  79      */
  80     public static String segmentCouplerScan() {
  81         return "SK";
  82     }
  83
  84     /**
  85      * Generates a firmware/serial-number request.
  86      *
  87      * @return the PCK command (without address header) as text
  88      */
  89     public static String requestSn() {
  90         return "SN";
  91     }
  92
  93     /**
  94      * Generates a command to request a part of a name of a module.
  95      *
  96      * @param partNumber 0..1
  97      * @return the PCK command (without address header) as text
  98      */
  99     public static String requestModuleName(int partNumber) {
 100         return "NMN" + (partNumber + 1);
 101     }
 102
 103     /**
 104      * Generates an output-port status request.
 105      *
 106      * @param outputId 0..3
 107      * @return the PCK command (without address header) as text
 108      * @throws LcnException if out of range
 109      */
 110     public static String requestOutputStatus(int outputId) throws LcnException {
 111         if (outputId < 0 || outputId > 3) {
 112             throw new LcnException();
 113         }
 114         return String.format("SMA%d", outputId + 1);
 115     }
 116
 117     /**
 118      * Generates a dim command for a single output-port.
 119      *
 120      * @param outputId 0..3
 121      * @param percent 0..100
 122      * @param rampMs ramp in milliseconds
 123      * @return the PCK command (without address header) as text
 124      * @throws LcnException if out of range
 125      */
 126     public static String dimOutput(int outputId, double percent, int rampMs) throws LcnException {
 127         if (outputId < 0 || outputId > 3) {
 128             throw new LcnException();
 129         }
 130         int rampNative = PckGenerator.timeToRampValue(rampMs);
 131         int n = (int) Math.round(percent * 2);
 132         if ((n % 2) == 0) { // Use the percent command (supported by all LCN-PCHK versions)
 133             return String.format("A%dDI%03d%03d", outputId + 1, n / 2, rampNative);
 134         } else { // We have a ".5" value. Use the native command (supported since LCN-PCHK 2.3)
 135             return String.format("O%dDI%03d%03d", outputId + 1, n, rampNative);
 136         }
 137     }
 138
 139     /**
 140      * Generates a command for setting the tunable white mode.
 141      *
 142      * @param mode 0..2
 143      * @return the PCK command (without address header) as text
 144      * @throws LcnException if out of range
 145      */
 146     public static String setTunableWhiteMode(int mode) throws LcnException {
 147         if (mode < 0 || mode > 2) {
 148             throw new LcnException();
 149         }
 150
 151         return String.format("AW%d", mode);
 152     }
 153
 154     /**
 155      * Generates a dim command for all output-ports.
 156      *
 157      * Attention: This command is supported since module firmware version 180501 AND LCN-PCHK 2.61
 158      *
 159      * @param firstPercent dimmer value of the first output 0..100
 160      * @param secondPercent dimmer value of the first output 0..100
 161      * @param thirdPercent dimmer value of the first output 0..100
 162      * @param fourthPercent dimmer value of the first output 0..100
 163      * @param rampMs ramp in milliseconds
 164      * @return the PCK command (without address header) as text
 165      */
 166     public static String dimAllOutputs(double firstPercent, double secondPercent, double thirdPercent,
 167             double fourthPercent, int rampMs) {
 168         long n1 = Math.round(firstPercent * 2);
 169         long n2 = Math.round(secondPercent * 2);
 170         long n3 = Math.round(thirdPercent * 2);
 171         long n4 = Math.round(fourthPercent * 2);
 172
 173         return String.format("OY%03d%03d%03d%03d%03d", n1, n2, n3, n4, timeToRampValue(rampMs));
 174     }
 175
 176     /**
 177      * Generates a control command for switching all outputs ON or OFF with a fixed ramp of 0.5s.
 178      *
 179      * @param percent 0..100
 180      * @returnthe PCK command (without address header) as text
 181      */
 182     public static String controlAllOutputs(double percent) {
 183         return String.format("AH%03d", Math.round(percent));
 184     }
 185
 186     /**
 187      * Generates a control command for switching dimmer output 1 and 2 both ON or OFF with a fixed ramp of 0.5s or
 188      * without ramp.
 189      *
 190      * @param on true, if outputs shall be switched on
 191      * @param ramp true, if the ramp shall be 0.5s, else 0s
 192      * @return the PCK command (without address header) as text
 193      */
 194     public static String controlOutputs12(boolean on, boolean ramp) {
 195         int commandByte;
 196         if (on) {
 197             commandByte = ramp ? 0xC8 : 0xFD;
 198         } else {
 199             commandByte = ramp ? 0x00 : 0xFC;
 200         }
 201         return String.format("X2%03d%03d%03d", 1, commandByte, commandByte);
 202     }
 203
 204     /**
 205      * Generates a dim command for setting the brightness of dimmer output 1 and 2 with a fixed ramp of 0.5s.
 206      *
 207      * @param percent brightness of both outputs 0..100
 208      * @return the PCK command (without address header) as text
 209      */
 210     public static String dimOutputs12(double percent) {
 211         long localPercent = Math.round(percent);
 212         return String.format("AY%03d%03d", localPercent, localPercent);
 213     }
 214
 215     /**
 216      * Let an output flicker.
 217      *
 218      * @param outputId output id 0..3
 219      * @param depth flicker depth, the higher the deeper 0..2
 220      * @param ramp the flicker speed 0..2
 221      * @param count number of flashes 1..15
 222      * @return the PCK command (without address header) as text
 223      * @throws LcnException when the input values are out of range
 224      */
 225     public static String flickerOutput(int outputId, int depth, int ramp, int count) throws LcnException {
 226         if (outputId < 0 || outputId > 3) {
 227             throw new LcnException("Output number out of range");
 228         }
 229         if (count < 1 || count > 15) {
 230             throw new LcnException("Number of flashes out of range");
 231         }
 232         String depthString;
 233         switch (depth) {
 234             case 0:
 235                 depthString = "G";
 236                 break;
 237             case 1:
 238                 depthString = "M";
 239                 break;
 240             case 2:
 241                 depthString = "S";
 242                 break;
 243             default:
 244                 throw new LcnException("Depth out of range");
 245         }
 246         String rampString;
 247         switch (ramp) {
 248             case 0:
 249                 rampString = "L";
 250                 break;
 251             case 1:
 252                 rampString = "M";
 253                 break;
 254             case 2:
 255                 rampString = "S";
 256                 break;
 257             default:
 258                 throw new LcnException("Ramp out of range");
 259         }
 260         return String.format("A%dFL%s%s%02d", outputId + 1, depthString, rampString, count);
 261     }
 262
 263     /**
 264      * Generates a command to change the value of an output-port.
 265      *
 266      * @param outputId 0..3
 267      * @param percent -100..100
 268      * @return the PCK command (without address header) as text
 269      * @throws LcnException if out of range
 270      */
 271     public static String relOutput(int outputId, double percent) throws LcnException {
 272         if (outputId < 0 || outputId > 3) {
 273             throw new LcnException();
 274         }
 275         int n = (int) Math.round(percent * 2);
 276         if ((n % 2) == 0) { // Use the percent command (supported by all LCN-PCHK versions)
 277             return String.format("A%d%s%03d", outputId + 1, percent >= 0 ? "AD" : "SB", Math.abs(n / 2));
 278         } else { // We have a ".5" value. Use the native command (supported since LCN-PCHK 2.3)
 279             return String.format("O%d%s%03d", outputId + 1, percent >= 0 ? "AD" : "SB", Math.abs(n));
 280         }
 281     }
 282
 283     /**
 284      * Generates a command that toggles a single output-port (on->off, off->on).
 285      *
 286      * @param outputId 0..3
 287      * @param ramp see {@link PckGenerator#timeToRampValue(int)}
 288      * @return the PCK command (without address header) as text
 289      * @throws LcnException if out of range
 290      */
 291     public static String toggleOutput(int outputId, int ramp) throws LcnException {
 292         if (outputId < 0 || outputId > 3) {
 293             throw new LcnException();
 294         }
 295         return String.format("A%dTA%03d", outputId + 1, ramp);
 296     }
 297
 298     /**
 299      * Generates a command that toggles all output-ports (on->off, off->on).
 300      *
 301      * @param ramp see {@link PckGenerator#timeToRampValue(int)}
 302      * @return the PCK command (without address header) as text
 303      */
 304     public static String toggleAllOutputs(int ramp) {
 305         return String.format("AU%03d", ramp);
 306     }
 307
 308     /**
 309      * Generates a relays-status request.
 310      *
 311      * @return the PCK command (without address header) as text
 312      */
 313     public static String requestRelaysStatus() {
 314         return "SMR";
 315     }
 316
 317     /**
 318      * Generates a command to control relays.
 319      *
 320      * @param states the 8 modifiers for the relay states
 321      * @return the PCK command (without address header) as text
 322      * @throws LcnException if out of range
 323      */
 324     public static String controlRelays(LcnDefs.RelayStateModifier[] states) throws LcnException {
 325         if (states.length != 8) {
 326             throw new LcnException();
 327         }
 328         StringBuilder ret = new StringBuilder("R8");
 329         for (int i = 0; i < 8; ++i) {
 330             switch (states[i]) {
 331                 case ON:
 332                     ret.append("1");
 333                     break;
 334                 case OFF:
 335                     ret.append("0");
 336                     break;
 337                 case TOGGLE:
 338                     ret.append("U");
 339                     break;
 340                 case NOCHANGE:
 341                     ret.append("-");
 342                     break;
 343                 default:
 344                     throw new LcnException();
 345             }
 346         }
 347         return ret.toString();
 348     }
 349
 350     /**
 351      * Generates a command to control the position of roller shutters on relays.
 352      *
 353      * @param motorNumber of the roller shutter (0-based)
 354      * @param percent of the entire roller shutter height
 355      * @return the PCK command (without address header) as text
 356      * @throws LcnException if out of range
 357      */
 358     public static String controlShutterPosition(int motorNumber, int percent) throws LcnException {
 359         return controlShutter(motorNumber, percent, "JH");
 360     }
 361
 362     /**
 363      * Generates a command to control the slat angle of roller shutters on relays.
 364      *
 365      * @param motorNumber of the roller shutter (0-based)
 366      * @param percent of the slat angle
 367      * @return the PCK command (without address header) as text
 368      * @throws LcnException if out of range
 369      */
 370     public static String controlShutterSlatAngle(int motorNumber, int percent) throws LcnException {
 371         return controlShutter(motorNumber, percent, "JW");
 372     }
 373
 374     private static String controlShutter(int motorNumber, int percent, String command) throws LcnException {
 375         if (motorNumber < 0 || motorNumber >= 4) {
 376             throw new LcnException("Roller shutter (relay) motor number out of range: " + motorNumber);
 377         }
 378
 379         if (percent < 0 || percent > 100) {
 380             throw new LcnException("Roller shutter (relay) position/angle out of range (percent): " + percent);
 381         }
 382
 383         return String.format("%s%03d%03d", command, percent, 1 << motorNumber);
 384     }
 385
 386     /**
 387      * Generates a binary-sensors status request.
 388      *
 389      * @return the PCK command (without address header) as text
 390      */
 391     public static String requestBinSensorsStatus() {
 392         return "SMB";
 393     }
 394
 395     /**
 396      * Generates a command that sets a variable absolute.
 397      *
 398      * @param number regulator number 0..1
 399      * @param value the absolute value to set
 400      * @return the PCK command (without address header) as text
 401      * @throws LcnException
 402      */
 403     public static String setSetpointAbsolute(int number, int value) {
 404         int internalValue = value;
 405         // Set absolute (not in PCK yet)
 406         int b1 = number << 6; // 01000000
 407         b1 |= 0x20; // xx10xxxx (set absolute)
 408         if (value < 1000) {
 409             internalValue = 1000 - internalValue;
 410             b1 |= 8;
 411         } else {
 412             internalValue -= 1000;
 413         }
 414         b1 |= (internalValue >> 8) & 0x0f; // xxxx1111
 415         int b2 = internalValue & 0xff;
 416         return String.format("X2%03d%03d%03d", 30, b1, b2);
 417     }
 418
 419     /**
 420      * Generates a command to change the regulator mode.
 421      *
 422      * @param number regulator number 0..1
 423      * @param cooling true=cooling, false=heating
 424      * @return the PCK command (without address header) as text
 425      * @throws LcnException
 426      */
 427     public static String setRVarMode(int number, boolean cooling) throws LcnException {
 428         String regulator;
 429         switch (number) {
 430             case 0:
 431                 regulator = "A";
 432                 break;
 433             case 1:
 434                 regulator = "B";
 435                 break;
 436             default:
 437                 throw new LcnException();
 438         }
 439
 440         return "RE" + regulator + "T" + (cooling ? "C" : "H");
 441     }
 442
 443     /**
 444      * Generates a command to change the value of a variable.
 445      *
 446      * @param variable the target variable to change
 447      * @param type the reference-point
 448      * @param value the native LCN value to add/subtract (can be negative)
 449      * @return the PCK command (without address header) as text
 450      * @throws LcnException if command is not supported
 451      */
 452     public static String setVariableRelative(Variable variable, LcnDefs.RelVarRef type, int value) {
 453         if (variable.getNumber() == 0) {
 454             // Old command for variable 1 / T-var (compatible with all modules)
 455             return String.format("Z%s%d", value >= 0 ? "A" : "S", Math.abs(value));
 456         } else { // New command for variable 1-12 (compatible with all modules, since LCN-PCHK 2.8)
 457             return String.format("Z%s%03d%d", value >= 0 ? "+" : "-", variable.getNumber() + 1, Math.abs(value));
 458         }
 459     }
 460
 461     /**
 462      * Generates a command the change the value of a regulator setpoint relative.
 463      *
 464      * @param number 0..1
 465      * @param type relative to the current or to the programmed value
 466      * @param value the relative value -4000..+4000
 467      * @return the PCK command (without address header) as text
 468      */
 469     public static String setSetpointRelative(int number, LcnDefs.RelVarRef type, int value) {
 470         return String.format("RE%sS%s%s%d", number == 0 ? "A" : "B", type == LcnDefs.RelVarRef.CURRENT ? "A" : "P",
 471                 value >= 0 ? "+" : "-", Math.abs(value));
 472     }
 473
 474     /**
 475      * Generates a command the change the value of a threshold relative.
 476      *
 477      * @param variable the threshold to change
 478      * @param type relative to the current or to the programmed value
 479      * @param value the relative value -4000..+4000
 480      * @param is2013 true, if the LCN module's firmware is equal to or newer than 2013
 481      * @return the PCK command (without address header) as text
 482      */
 483     public static String setThresholdRelative(Variable variable, LcnDefs.RelVarRef type, int value, boolean is2013)
 484             throws LcnException {
 485         if (is2013) { // New command for registers 1-4 (since 170206, LCN-PCHK 2.8)
 486             return String.format("SS%s%04d%sR%d%d", type == LcnDefs.RelVarRef.CURRENT ? "R" : "E", Math.abs(value),
 487                     value >= 0 ? "A" : "S", variable.getNumber() + 1, variable.getThresholdNumber().get() + 1);
 488         } else if (variable.getNumber() == 0) { // Old command for register 1 (before 170206)
 489             return String.format("SS%s%04d%s%s%s%s%s%s", type == LcnDefs.RelVarRef.CURRENT ? "R" : "E", Math.abs(value),
 490                     value >= 0 ? "A" : "S", variable.getThresholdNumber().get() == 0 ? "1" : "0",
 491                     variable.getThresholdNumber().get() == 1 ? "1" : "0",
 492                     variable.getThresholdNumber().get() == 2 ? "1" : "0",
 493                     variable.getThresholdNumber().get() == 3 ? "1" : "0",
 494                     variable.getThresholdNumber().get() == 4 ? "1" : "0");
 495         } else {
 496             throw new LcnException(
 497                     "Module does not have threshold register " + (variable.getThresholdNumber().get() + 1));
 498         }
 499     }
 500
 501     /**
 502      * Generates a variable value request.
 503      *
 504      * @param variable the variable to request
 505      * @param firmwareVersion the target module's firmware version
 506      * @return the PCK command (without address header) as text
 507      * @throws LcnException if command is not supported
 508      */
 509     public static String requestVarStatus(Variable variable, int firmwareVersion) throws LcnException {
 510         if (firmwareVersion >= LcnBindingConstants.FIRMWARE_2013) {
 511             int id = variable.getNumber();
 512             switch (variable.getType()) {
 513                 case UNKNOWN:
 514                     throw new LcnException("Variable unknown");
 515                 case VARIABLE:
 516                     return "MWT" + (id + 1);
 517                 case REGULATOR:
 518                     return "MWS" + (id + 1);
 519                 case THRESHOLD:
 520                     return "SE" + (id + 1); // Whole register
 521                 case S0INPUT:
 522                     return "MWC" + (id + 1);
 523             }
 524             throw new LcnException("Unsupported variable type: " + variable);
 525         } else {
 526             switch (variable) {
 527                 case VARIABLE1:
 528                     return "MWV";
 529                 case VARIABLE2:
 530                     return "MWTA";
 531                 case VARIABLE3:
 532                     return "MWTB";
 533                 case RVARSETPOINT1:
 534                     return "MWSA";
 535                 case RVARSETPOINT2:
 536                     return "MWSB";
 537                 case THRESHOLDREGISTER11:
 538                 case THRESHOLDREGISTER12:
 539                 case THRESHOLDREGISTER13:
 540                 case THRESHOLDREGISTER14:
 541                 case THRESHOLDREGISTER15:
 542                     return "SL1"; // Whole register
 543                 default:
 544                     throw new LcnException("Unsupported variable type: " + variable);
 545             }
 546         }
 547     }
 548
 549     /**
 550      * Generates a request for LED and logic-operations states.
 551      *
 552      * @return the PCK command (without address header) as text
 553      */
 554     public static String requestLedsAndLogicOpsStatus() {
 555         return "SMT";
 556     }
 557
 558     /**
 559      * Generates a command to the set the state of a single LED.
 560      *
 561      * @param ledId 0..11
 562      * @param state the state to set
 563      * @return the PCK command (without address header) as text
 564      * @throws LcnException if out of range
 565      */
 566     public static String controlLed(int ledId, LcnDefs.LedStatus state) throws LcnException {
 567         if (ledId < 0 || ledId > 11) {
 568             throw new LcnException();
 569         }
 570         return String.format("LA%03d%s", ledId + 1, state == LcnDefs.LedStatus.OFF ? "A"
 571                 : state == LcnDefs.LedStatus.ON ? "E" : state == LcnDefs.LedStatus.BLINK ? "B" : "F");
 572     }
 573
 574     /**
 575      * Generates a command to send LCN keys.
 576      *
 577      * @param cmds the 4 concrete commands to send for the tables (A-D)
 578      * @param keys the tables' 8 key-states (true means "send")
 579      * @return the PCK command (without address header) as text
 580      * @throws LcnException if out of range
 581      */
 582     public static String sendKeys(LcnDefs.SendKeyCommand[] cmds, boolean[] keys) throws LcnException {
 583         if (cmds.length != 4 || keys.length != 8) {
 584             throw new LcnException();
 585         }
 586         StringBuilder ret = new StringBuilder("TS");
 587         for (int i = 0; i < 4; ++i) {
 588             switch (cmds[i]) {
 589                 case HIT:
 590                     ret.append("K");
 591                     break;
 592                 case MAKE:
 593                     ret.append("L");
 594                     break;
 595                 case BREAK:
 596                     ret.append("O");
 597                     break;
 598                 case DONTSEND:
 599                     // By skipping table D (if it is not used), we use the old command
 600                     // for table A-C which is compatible with older LCN modules
 601                     if (i < 3) {
 602                         ret.append("-");
 603                     }
 604                     break;
 605                 default:
 606                     throw new LcnException();
 607             }
 608         }
 609         for (int i = 0; i < 8; ++i) {
 610             ret.append(keys[i] ? "1" : "0");
 611         }
 612         return ret.toString();
 613     }
 614
 615     /**
 616      * Generates a command to send LCN keys deferred / delayed.
 617      *
 618      * @param tableId 0(A)..3(D)
 619      * @param time the delay time
 620      * @param timeUnit the time unit
 621      * @param keys the key-states (true means "send")
 622      * @return the PCK command (without address header) as text
 623      * @throws LcnException if out of range
 624      */
 625     public static String sendKeysHitDefered(int tableId, int time, LcnDefs.TimeUnit timeUnit, boolean[] keys)
 626             throws LcnException {
 627         if (tableId < 0 || tableId > 3 || keys.length != 8) {
 628             throw new LcnException();
 629         }
 630         StringBuilder ret = new StringBuilder("TV");
 631         switch (tableId) {
 632             case 0:
 633                 ret.append("A");
 634                 break;
 635             case 1:
 636                 ret.append("B");
 637                 break;
 638             case 2:
 639                 ret.append("C");
 640                 break;
 641             case 3:
 642                 ret.append("D");
 643                 break;
 644             default:
 645                 throw new LcnException();
 646         }
 647         ret.append(String.format("%03d", time));
 648         switch (timeUnit) {
 649             case SECONDS:
 650                 if (time < 1 || time > 60) {
 651                     throw new LcnException();
 652                 }
 653                 ret.append("S");
 654                 break;
 655             case MINUTES:
 656                 if (time < 1 || time > 90) {
 657                     throw new LcnException();
 658                 }
 659                 ret.append("M");
 660                 break;
 661             case HOURS:
 662                 if (time < 1 || time > 50) {
 663                     throw new LcnException();
 664                 }
 665                 ret.append("H");
 666                 break;
 667             case DAYS:
 668                 if (time < 1 || time > 45) {
 669                     throw new LcnException();
 670                 }
 671                 ret.append("D");
 672                 break;
 673             default:
 674                 throw new LcnException();
 675         }
 676         for (int i = 0; i < 8; ++i) {
 677             ret.append(keys[i] ? "1" : "0");
 678         }
 679         return ret.toString();
 680     }
 681
 682     /**
 683      * Generates a request for key-lock states.
 684      * Always requests table A-D. Supported since LCN-PCHK 2.8.
 685      *
 686      * @return the PCK command (without address header) as text
 687      */
 688     public static String requestKeyLocksStatus() {
 689         return "STX";
 690     }
 691
 692     /**
 693      * Generates a command to lock keys.
 694      *
 695      * @param tableId 0(A)..3(D)
 696      * @param states the 8 key-lock modifiers
 697      * @return the PCK command (without address header) as text
 698      * @throws LcnException if out of range
 699      */
 700     public static String lockKeys(int tableId, LcnDefs.KeyLockStateModifier[] states) throws LcnException {
 701         if (tableId < 0 || tableId > 3 || states.length != 8) {
 702             throw new LcnException();
 703         }
 704         StringBuilder ret = new StringBuilder(
 705                 String.format("TX%s", tableId == 0 ? "A" : tableId == 1 ? "B" : tableId == 2 ? "C" : "D"));
 706         for (int i = 0; i < 8; ++i) {
 707             switch (states[i]) {
 708                 case ON:
 709                     ret.append("1");
 710                     break;
 711                 case OFF:
 712                     ret.append("0");
 713                     break;
 714                 case TOGGLE:
 715                     ret.append("U");
 716                     break;
 717                 case NOCHANGE:
 718                     ret.append("-");
 719                     break;
 720                 default:
 721                     throw new LcnException();
 722             }
 723         }
 724         return ret.toString();
 725     }
 726
 727     /**
 728      * Generates a command to lock keys for table A temporary.
 729      * There is no hardware-support for locking tables B-D.
 730      *
 731      * @param time the lock time
 732      * @param timeUnit the time unit
 733      * @param keys the 8 key-lock states (true means lock)
 734      * @return the PCK command (without address header) as text
 735      * @throws LcnException if out of range
 736      */
 737     public static String lockKeyTabATemporary(int time, LcnDefs.TimeUnit timeUnit, boolean[] keys) throws LcnException {
 738         if (keys.length != 8) {
 739             throw new LcnException();
 740         }
 741         StringBuilder ret = new StringBuilder(String.format("TXZA%03d", time));
 742         switch (timeUnit) {
 743             case SECONDS:
 744                 if (time < 1 || time > 60) {
 745                     throw new LcnException();
 746                 }
 747                 ret.append("S");
 748                 break;
 749             case MINUTES:
 750                 if (time < 1 || time > 90) {
 751                     throw new LcnException();
 752                 }
 753                 ret.append("M");
 754                 break;
 755             case HOURS:
 756                 if (time < 1 || time > 50) {
 757                     throw new LcnException();
 758                 }
 759                 ret.append("H");
 760                 break;
 761             case DAYS:
 762                 if (time < 1 || time > 45) {
 763                     throw new LcnException();
 764                 }
 765                 ret.append("D");
 766                 break;
 767             default:
 768                 throw new LcnException();
 769         }
 770         for (int i = 0; i < 8; ++i) {
 771             ret.append(keys[i] ? "1" : "0");
 772         }
 773         return ret.toString();
 774     }
 775
 776     /**
 777      * Generates the command header / start for sending dynamic texts.
 778      * Used by LCN-GTxD periphery (supports 4 text rows).
 779      * To complete the command, the text to send must be appended (UTF-8 encoding).
 780      * Texts are split up into up to 5 parts with 12 "UTF-8 bytes" each.
 781      *
 782      * @param row 0..3
 783      * @param part 0..4
 784      * @return the PCK command (without address header) as text
 785      * @throws LcnException if out of range
 786      */
 787     public static String dynTextHeader(int row, int part) throws LcnException {
 788         if (row < 0 || row > 3 || part < 0 || part > 4) {
 789             throw new LcnException("Row number is out of range: " + (row + 1));
 790         }
 791         return String.format("GTDT%d%d", row + 1, part + 1);
 792     }
 793
 794     /**
 795      * Generates a command to lock a regulator.
 796      *
 797      * @param regId 0..1
 798      * @param state the lock state
 799      * @return the PCK command (without address header) as text
 800      * @throws LcnException if out of range
 801      */
 802     public static String lockRegulator(int regId, boolean state) throws LcnException {
 803         if (regId < 0 || regId > 1) {
 804             throw new LcnException();
 805         }
 806         return String.format("RE%sX%s", regId == 0 ? "A" : "B", state ? "S" : "A");
 807     }
 808
 809     /**
 810      * Generates a command to start a relay timer
 811      *
 812      * @param relayNumber number of relay (1..8)
 813      * @param duration duration in milliseconds
 814      * @return the PCK command (without address header) as text
 815      * @throws LcnException if out of range
 816      */
 817     public static String startRelayTimer(int relayNumber, double duration) throws LcnException {
 818         if (relayNumber < 1 || relayNumber > 8 || duration < 30 || duration > 240960) {
 819             throw new LcnException();
 820         }
 821         StringBuilder command = new StringBuilder("R8T");
 822         command.append(String.format("%03d", convertMsecToLCNTimer(duration)));
 823         StringBuilder data = new StringBuilder("--------");
 824         data.setCharAt(relayNumber - 1, '1');
 825         command.append(data);
 826         return command.toString();
 827     }
 828
 829     /**
 830      * Generates a command to set the beeping sound volume.
 831      *
 832      * @param volume the sound volume
 833      * @return the PCK command (without address header) as text
 834      * @throws LcnException if out of range
 835      */
 836     public static String setBeepVolume(double volume) throws LcnException {
 837         if (volume < 0 || volume > 100) {
 838             throw new LcnException();
 839         }
 840
 841         return String.format("PIV%03d", Math.round(volume));
 842     }
 843
 844     /**
 845      * Generates a command to let the beeper connected to the LCN module beep.
 846      *
 847      * @param volume the sound volume
 848      * @return the PCK command (without address header) as text
 849      * @throws LcnException if out of range
 850      */
 851     public static String beep(String tonality, int count) throws LcnException {
 852         LcnBindingConstants.ALLOWED_BEEP_TONALITIES.stream() //
 853                 .filter(t -> t.equals(tonality)) //
 854                 .findAny() //
 855                 .orElseThrow(LcnException::new);
 856
 857         if (count < 0) {
 858             throw new LcnException();
 859         }
 860
 861         return String.format("PI%s%d", tonality, Math.min(count, 50));
 862     }
 863
 864     /**
 865      * Generates a null command, used for broadcast messages.
 866      *
 867      * @return the PCK command (without address header) as text
 868      */
 869     public static String nullCommand() {
 870         return "LEER";
 871     }
 872
 873     /**
 874      * Converts the given time into an LCN ramp value.
 875      *
 876      * @param timeMSec the time in milliseconds
 877      * @return the (LCN-internal) ramp value (0..250)
 878      */
 879     private static int timeToRampValue(int timeMSec) {
 880         int ret;
 881         if (timeMSec < 250) {
 882             ret = 0;
 883         } else if (timeMSec < 500) {
 884             ret = 1;
 885         } else if (timeMSec < 660) {
 886             ret = 2;
 887         } else if (timeMSec < 1000) {
 888             ret = 3;
 889         } else if (timeMSec < 1400) {
 890             ret = 4;
 891         } else if (timeMSec < 2000) {
 892             ret = 5;
 893         } else if (timeMSec < 3000) {
 894             ret = 6;
 895         } else if (timeMSec < 4000) {
 896             ret = 7;
 897         } else if (timeMSec < 5000) {
 898             ret = 8;
 899         } else if (timeMSec < 6000) {
 900             ret = 9;
 901         } else {
 902             ret = (timeMSec / 1000 - 6) / 2 + 10;
 903             if (ret > 250) {
 904                 ret = 250;
 905                 LOGGER.warn("Ramp value is too high. Limiting value to 486s.");
 906             }
 907         }
 908         return ret;
 909     }
 910
 911     /**
 912      * Converts duration in milliseconds to lcntimer value
 913      * Source: https://www.symcon.de/forum/threads/38603-LCN-Relais-Kurzzeit-Timer-umrechnen
 914      *
 915      * @param ms time in milliseconds
 916      * @return lcn timer value
 917      */
 918     private static int convertMsecToLCNTimer(double ms) {
 919         Integer lcntimer = -1;
 920         if (ms >= 0 && ms <= 240960) {
 921             double a = ms / 1000 / 0.03;
 922             double b = (a / 32.0) + 1.0;
 923             double c = Math.log(b) / Math.log(2);
 924             double mod = Math.floor(c);
 925             double faktor = 32 * (Math.pow(2, mod) - 1);
 926             double offset = (a - faktor) / Math.pow(2, mod);
 927             lcntimer = (int) (offset + mod * 32);
 928         } else {
 929             LOGGER.warn("Timer not in [0,240960] ms");
 930         }
 931         return lcntimer;
 932     }
 933 }