src/hardware/hp-3457a/protocol.c

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2016 Alexandru Gagniuc <mr.nuke.me@gmail.com>
   5  *
   6  * This program is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #include <config.h>
  21 #include <math.h>
  22 #include <scpi.h>
  23 #include "protocol.h"
  24
  25 static int set_mq_volt(struct sr_scpi_dev_inst *scpi, enum sr_mqflag flags);
  26 static int set_mq_amp(struct sr_scpi_dev_inst *scpi, enum sr_mqflag flags);
  27 static int set_mq_ohm(struct sr_scpi_dev_inst *scpi, enum sr_mqflag flags);
  28 /*
  29  * The source for the frequency measurement can be either AC voltage, AC+DC
  30  * voltage, AC current, or AC+DC current. Configuring this is not yet
  31  * supported. For details, see "FSOURCE" command.
  32  * The set_mode function is optional and can be set to NULL, but in that case
  33  * a cmd string must be provided.
  34  */
  35 static const struct {
  36         enum sr_mq mq;
  37         enum sr_unit unit;
  38         const char *cmd;
  39         int (*set_mode)(struct sr_scpi_dev_inst *scpi, enum sr_mqflag flags);
  40 } sr_mq_to_cmd_map[] = {
  41         { SR_MQ_VOLTAGE, SR_UNIT_VOLT, "DCV", set_mq_volt },
  42         { SR_MQ_CURRENT, SR_UNIT_AMPERE, "DCI", set_mq_amp },
  43         { SR_MQ_RESISTANCE, SR_UNIT_OHM, "OHM", set_mq_ohm },
  44         { SR_MQ_FREQUENCY, SR_UNIT_HERTZ, "FREQ", NULL },
  45 };
  46
  47 static const struct rear_card_info rear_card_parameters[] = {
  48         {
  49                 .type = REAR_TERMINALS,
  50                 .card_id = 0,
  51                 .name = "Rear terminals",
  52                 .cg_name = "rear",
  53         }, {
  54                 .type = HP_44491A,
  55                 .card_id = 44491,
  56                 .name = "44491A Armature Relay Multiplexer",
  57                 .cg_name = "44491a",
  58         }, {
  59                 .type = HP_44492A,
  60                 .card_id = 44492,
  61                 .name = "44492A Reed Relay Multiplexer",
  62                 .cg_name = "44492a",
  63         }
  64 };
  65
  66 static int send_mq_ac_dc(struct sr_scpi_dev_inst *scpi, const char *mode,
  67                            enum sr_mqflag flags)
  68 {
  69         const char *ac_flag, *dc_flag;
  70
  71         if (flags & ~(SR_MQFLAG_AC | SR_MQFLAG_DC))
  72                 return SR_ERR_NA;
  73
  74         ac_flag = (flags & SR_MQFLAG_AC) ? "AC" : "";
  75         dc_flag = "";
  76         /* Must specify DC measurement when AC flag is not given. */
  77         if ((flags & SR_MQFLAG_DC) || !(flags & SR_MQFLAG_AC))
  78                 dc_flag = "DC";
  79
  80         return sr_scpi_send(scpi, "%s%s%s", ac_flag, dc_flag, mode);
  81 }
  82
  83 static int set_mq_volt(struct sr_scpi_dev_inst *scpi, enum sr_mqflag flags)
  84 {
  85         return send_mq_ac_dc(scpi, "V", flags);
  86 }
  87
  88 static int set_mq_amp(struct sr_scpi_dev_inst *scpi, enum sr_mqflag flags)
  89 {
  90         return send_mq_ac_dc(scpi, "I", flags);
  91 }
  92
  93 static int set_mq_ohm(struct sr_scpi_dev_inst *scpi, enum sr_mqflag flags)
  94 {
  95         const char *ohm_flag;
  96
  97         if (flags & ~(SR_MQFLAG_FOUR_WIRE))
  98                 return SR_ERR_NA;
  99
 100         ohm_flag = (flags & SR_MQFLAG_FOUR_WIRE) ? "F" : "";
 101         return sr_scpi_send(scpi, "OHM%s", ohm_flag);
 102 }
 103
 104 SR_PRIV int hp_3457a_set_mq(const struct sr_dev_inst *sdi, enum sr_mq mq,
 105                             enum sr_mqflag mq_flags)
 106 {
 107         int ret;
 108         size_t i;
 109         struct sr_scpi_dev_inst *scpi = sdi->conn;
 110         struct dev_context *devc = sdi->priv;
 111
 112         for (i = 0; i < ARRAY_SIZE(sr_mq_to_cmd_map); i++) {
 113                 if (sr_mq_to_cmd_map[i].mq != mq)
 114                         continue;
 115                 if (sr_mq_to_cmd_map[i].set_mode) {
 116                         ret = sr_mq_to_cmd_map[i].set_mode(scpi, mq_flags);
 117                 } else {
 118                         ret = sr_scpi_send(scpi, sr_mq_to_cmd_map[i].cmd);
 119                 }
 120                 if (ret == SR_OK) {
 121                         devc->measurement_mq = sr_mq_to_cmd_map[i].mq;
 122                         devc->measurement_mq_flags = mq_flags;
 123                         devc->measurement_unit = sr_mq_to_cmd_map[i].unit;
 124                 }
 125                 return ret;
 126         }
 127
 128         return SR_ERR_NA;
 129 }
 130
 131 SR_PRIV const struct rear_card_info *hp_3457a_probe_rear_card(struct sr_scpi_dev_inst *scpi)
 132 {
 133         size_t i;
 134         float card_fval;
 135         unsigned int card_id;
 136         const struct rear_card_info *rear_card = NULL;
 137
 138         if (sr_scpi_get_float(scpi, "OPT?", &card_fval) != SR_OK)
 139                 return NULL;
 140
 141         card_id = (unsigned int)card_fval;
 142
 143         for (i = 0; i < ARRAY_SIZE(rear_card_parameters); i++) {
 144                 if (rear_card_parameters[i].card_id == card_id) {
 145                         rear_card = rear_card_parameters + i;
 146                         break;
 147                 }
 148         }
 149
 150         if (!rear_card)
 151                 return NULL;
 152
 153         sr_info("Found %s.", rear_card->name);
 154
 155         return rear_card;
 156 }
 157
 158 SR_PRIV int hp_3457a_set_nplc(const struct sr_dev_inst *sdi, float nplc)
 159 {
 160         int ret;
 161         struct sr_scpi_dev_inst *scpi = sdi->conn;
 162         struct dev_context *devc = sdi->priv;
 163
 164         if ((nplc < 1E-6) || (nplc > 100))
 165                 return SR_ERR_ARG;
 166
 167         /* Only need one digit of precision here. */
 168         ret = sr_scpi_send(scpi, "NPLC %.0E", nplc);
 169
 170         /*
 171          * The instrument only has a few valid NPLC setting, so get back the
 172          * one which was selected.
 173          */
 174         sr_scpi_get_float(scpi, "NPLC?", &devc->nplc);
 175
 176         return ret;
 177 }
 178
 179 /* HIRES register only contains valid data with 10 or more powerline cycles. */
 180 static int is_highres_enabled(struct dev_context *devc)
 181 {
 182         return (devc->nplc >= 10.0);
 183 }
 184
 185 static void retrigger_measurement(struct sr_scpi_dev_inst *scpi,
 186                                   struct dev_context *devc)
 187 {
 188         sr_scpi_send(scpi, "?");
 189         devc->acq_state = ACQ_TRIGGERED_MEASUREMENT;
 190 }
 191
 192 static void request_hires(struct sr_scpi_dev_inst *scpi,
 193                           struct dev_context *devc)
 194 {
 195         sr_scpi_send(scpi, "RMATH HIRES");
 196         devc->acq_state = ACQ_REQUESTED_HIRES;
 197 }
 198
 199 static void request_range(struct sr_scpi_dev_inst *scpi,
 200                           struct dev_context *devc)
 201 {
 202         sr_scpi_send(scpi, "RANGE?");
 203         devc->acq_state = ACQ_REQUESTED_RANGE;
 204 }
 205
 206 /*
 207  * Calculate the number of leading zeroes in the measurement.
 208  *
 209  * Depending on the range and measurement, a reading may not have eight digits
 210  * of resolution. For example, on a 30V range:
 211  *    : 10.000000 V has 8 significant digits
 212  *    :  9.999999 V has 7 significant digits
 213  *    :  0.999999 V has 6 significant digits
 214  *
 215  * The number of significant digits is determined based on the range in which
 216  * the measurement was taken:
 217  *    1. By taking the base 10 logarithm of the range, and converting that to
 218  *       an integer, we can get the minimum reading which has a full resolution
 219  *       reading. Raising 10 to the integer power gives the full resolution.
 220  *       Ex: For 30 V range, a full resolution reading is 10.000000.
 221  *    2. A ratio is taken between the full resolution reading and the
 222  *       measurement. Since the full resolution reading is a power of 10,
 223  *       for every leading zero, this ratio will be slightly higher than a
 224  *       power of 10. For example, for 10 V full resolution:
 225  *          : 10.000000 V, ratio = 1.0000000
 226  *          :  9.999999 V, ratio = 1.0000001
 227  *          :  0.999999 V, ratio = 10.000001
 228  *    3. The ratio is rounded up to prevent loss of precision in the next step.
 229  *    4. The base 10 logarithm of the ratio is taken, then rounded up. This
 230  *       gives the number of leading zeroes in the measurement.
 231  *       For example, for 10 V full resolution:
 232  *          : 10.000000 V, ceil(1.0000000) =  1, log10 = 0.00; 0 leading zeroes
 233  *          :  9.999999 V, ceil(1.0000001) =  2, log10 = 0.30; 1 leading zero
 234  *          :  0.999999 V, ceil(10.000001) = 11, log10 = 1.04, 2 leading zeroes
 235  *    5. The number of leading zeroes is subtracted from the maximum number of
 236  *       significant digits, 8, at 7 1/2 digits resolution.
 237  *       For a 10 V full resolution reading, this gives:
 238  *          : 10.000000 V, 0 leading zeroes => 8 significant digits
 239  *          :  9.999999 V, 1 leading zero   => 7 significant digits
 240  *          :  0.999999 V, 2 leading zeroes => 6 significant digits
 241  *
 242  * Single precision floating point numbers can achieve about 16 million counts,
 243  * but in high resolution mode we can get as much as 30 million counts. As a
 244  * result, these calculations must be done with double precision
 245  * (the HP 3457A is a very precise instrument).
 246  */
 247 static int calculate_num_zero_digits(double measurement, double range)
 248 {
 249         int zero_digits;
 250         double min_full_res_reading, log10_range, full_res_ratio;
 251
 252         log10_range = log10(range);
 253         min_full_res_reading = pow(10, (int)log10_range);
 254         if (measurement > min_full_res_reading) {
 255                 zero_digits = 0;
 256         } else if (measurement == 0.0) {
 257                 zero_digits = 0;
 258         } else {
 259                 full_res_ratio = min_full_res_reading / measurement;
 260                 zero_digits = ceil(log10(ceil(full_res_ratio)));
 261         }
 262
 263         return zero_digits;
 264 }
 265
 266 /*
 267  * Until the output modules understand double precision data, we need to send
 268  * the measurement as floats instead of doubles, hence, the dance with
 269  * measurement_workaround double to float conversion.
 270  * See bug #779 for details.
 271  * The workaround should be removed once the output modules are fixed.
 272  */
 273 static void acq_send_measurement(struct sr_dev_inst *sdi)
 274 {
 275         double hires_measurement;
 276         float measurement_workaround;
 277         int zero_digits, num_digits;
 278         struct sr_datafeed_packet packet;
 279         struct sr_datafeed_analog analog;
 280         struct sr_analog_encoding encoding;
 281         struct sr_analog_meaning meaning;
 282         struct sr_analog_spec spec;
 283         struct dev_context *devc = sdi->priv;
 284
 285         hires_measurement = devc->base_measurement;
 286         if (is_highres_enabled(devc))
 287                 hires_measurement += devc->hires_register;
 288
 289         /* Figure out how many of the digits are significant. */
 290         num_digits = is_highres_enabled(devc) ? 8 : 7;
 291         zero_digits = calculate_num_zero_digits(hires_measurement,
 292                                                 devc->measurement_range);
 293         num_digits = num_digits - zero_digits;
 294
 295         packet.type = SR_DF_ANALOG;
 296         packet.payload = &analog;
 297
 298         sr_analog_init(&analog, &encoding, &meaning, &spec, num_digits);
 299         encoding.unitsize = sizeof(float);
 300
 301         meaning.channels = sdi->channels;
 302
 303         measurement_workaround = hires_measurement;
 304         analog.num_samples = 1;
 305         analog.data = &measurement_workaround;
 306
 307         meaning.mq = devc->measurement_mq;
 308         meaning.mqflags = devc->measurement_mq_flags;
 309         meaning.unit = devc->measurement_unit;
 310
 311         sr_session_send(sdi, &packet);
 312 }
 313
 314 SR_PRIV int hp_3457a_receive_data(int fd, int revents, void *cb_data)
 315 {
 316         int ret;
 317         struct sr_scpi_dev_inst *scpi;
 318         struct dev_context *devc;
 319         struct sr_dev_inst *sdi = cb_data;
 320
 321         (void)fd;
 322         (void)revents;
 323
 324         if (!(sdi = cb_data))
 325                 return TRUE;
 326
 327         if (!(devc = sdi->priv))
 328                 return TRUE;
 329
 330         scpi = sdi->conn;
 331
 332         switch (devc->acq_state) {
 333         case ACQ_TRIGGERED_MEASUREMENT:
 334                 ret = sr_scpi_get_double(scpi, NULL, &devc->base_measurement);
 335                 if (ret != SR_OK) {
 336                         retrigger_measurement(scpi, devc);
 337                         return TRUE;
 338                 }
 339
 340                 if (is_highres_enabled(devc))
 341                         request_hires(scpi, devc);
 342                 else
 343                         request_range(scpi, devc);
 344
 345                 break;
 346         case ACQ_REQUESTED_HIRES:
 347                 ret = sr_scpi_get_double(scpi, NULL, &devc->hires_register);
 348                 if (ret != SR_OK) {
 349                         retrigger_measurement(scpi, devc);
 350                         return TRUE;
 351                 }
 352                 request_range(scpi, devc);
 353                 break;
 354         case ACQ_REQUESTED_RANGE:
 355                 ret = sr_scpi_get_double(scpi, NULL, &devc->measurement_range);
 356                 if (ret != SR_OK) {
 357                         retrigger_measurement(scpi, devc);
 358                         return TRUE;
 359                 }
 360                 devc->acq_state = ACQ_GOT_MEASUREMENT;
 361                 break;
 362         default:
 363                 return FALSE;
 364         }
 365
 366         if (devc->acq_state == ACQ_GOT_MEASUREMENT) {
 367                 acq_send_measurement(sdi);
 368                 devc->num_samples++;
 369         }
 370
 371         if (devc->limit_samples && (devc->num_samples >= devc->limit_samples)) {
 372                 sdi->driver->dev_acquisition_stop(sdi, cb_data);
 373                 return FALSE;
 374         }
 375
 376         /* Got more to go. */
 377         if (devc->acq_state == ACQ_GOT_MEASUREMENT) {
 378                 /* Retrigger */
 379                 retrigger_measurement(scpi, devc);
 380         }
 381
 382         return TRUE;
 383 }