hardware/common/scpi.c

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2013 poljar (Damir Jelić) <poljarinho@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 "libsigrok.h"
  21 #include "libsigrok-internal.h"
  22
  23 #include <glib.h>
  24 #include <string.h>
  25
  26 #define LOG_PREFIX "scpi"
  27
  28 #define SCPI_READ_RETRIES 100
  29 #define SCPI_READ_RETRY_TIMEOUT 10000
  30
  31 /**
  32  * Parse a string representation of a boolean-like value into a gboolean.
  33  * Similar to sr_parse_boolstring but rejects strings which do not represent
  34  * a boolean-like value.
  35  *
  36  * @param str String to convert.
  37  * @param ret Pointer to a gboolean where the result of the conversion will be
  38  * stored.
  39  *
  40  * @return SR_OK on success, SR_ERR on failure.
  41  */
  42 static int parse_strict_bool(const char *str, gboolean *ret)
  43 {
  44         if (!str)
  45                 return SR_ERR_ARG;
  46
  47         if (!g_strcmp0(str, "1") ||
  48             !g_ascii_strncasecmp(str, "y", 1) ||
  49             !g_ascii_strncasecmp(str, "t", 1) ||
  50             !g_ascii_strncasecmp(str, "yes", 3) ||
  51             !g_ascii_strncasecmp(str, "true", 4) ||
  52             !g_ascii_strncasecmp(str, "on", 2)) {
  53                 *ret = TRUE;
  54                 return SR_OK;
  55         } else if (!g_strcmp0(str, "0") ||
  56                    !g_ascii_strncasecmp(str, "n", 1) ||
  57                    !g_ascii_strncasecmp(str, "f", 1) ||
  58                    !g_ascii_strncasecmp(str, "no", 2) ||
  59                    !g_ascii_strncasecmp(str, "false", 5) ||
  60                    !g_ascii_strncasecmp(str, "off", 3)) {
  61                 *ret = FALSE;
  62                 return SR_OK;
  63         }
  64
  65         return SR_ERR;
  66 }
  67
  68 /**
  69  * Open SCPI device.
  70  *
  71  * @param scpi Previously initialized SCPI device structure.
  72  *
  73  * @return SR_OK on success, SR_ERR on failure.
  74  */
  75 SR_PRIV int sr_scpi_open(struct sr_scpi_dev_inst *scpi)
  76 {
  77         return scpi->open(scpi->priv);
  78 }
  79
  80 /**
  81  * Add an event source for an SCPI device.
  82  *
  83  * @param scpi Previously initialized SCPI device structure.
  84  * @param events Events to check for.
  85  * @param timeout Max time to wait before the callback is called, ignored if 0.
  86  * @param cb Callback function to add. Must not be NULL.
  87  * @param cb_data Data for the callback function. Can be NULL.
  88  *
  89  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
  90  *         SR_ERR_MALLOC upon memory allocation errors.
  91  */
  92 SR_PRIV int sr_scpi_source_add(struct sr_scpi_dev_inst *scpi, int events,
  93                 int timeout, sr_receive_data_callback_t cb, void *cb_data)
  94 {
  95         return scpi->source_add(scpi->priv, events, timeout, cb, cb_data);
  96 }
  97
  98 /**
  99  * Remove event source for an SCPI device.
 100  *
 101  * @param scpi Previously initialized SCPI device structure.
 102  *
 103  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
 104  *         SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
 105  *         internal errors.
 106  */
 107 SR_PRIV int sr_scpi_source_remove(struct sr_scpi_dev_inst *scpi)
 108 {
 109         return scpi->source_remove(scpi->priv);
 110 }
 111
 112 /**
 113  * Send a SCPI command.
 114  *
 115  * @param scpi Previously initialized SCPI device structure.
 116  * @param format Format string, to be followed by any necessary arguments.
 117  *
 118  * @return SR_OK on success, SR_ERR on failure.
 119  */
 120 SR_PRIV int sr_scpi_send(struct sr_scpi_dev_inst *scpi,
 121                          const char *format, ...)
 122 {
 123         va_list args;
 124         int ret;
 125
 126         va_start(args, format);
 127         ret = sr_scpi_send_variadic(scpi, format, args);
 128         va_end(args);
 129
 130         return ret;
 131 }
 132
 133 /**
 134  * Send a SCPI command with a variadic argument list.
 135  *
 136  * @param scpi Previously initialized SCPI device structure.
 137  * @param format Format string.
 138  * @param args Argument list.
 139  *
 140  * @return SR_OK on success, SR_ERR on failure.
 141  */
 142 SR_PRIV int sr_scpi_send_variadic(struct sr_scpi_dev_inst *scpi,
 143                          const char *format, va_list args)
 144 {
 145         va_list args_copy;
 146         char *buf;
 147         int len, ret;
 148
 149         /* Get length of buffer required. */
 150         va_copy(args_copy, args);
 151         len = vsnprintf(NULL, 0, format, args_copy);
 152         va_end(args_copy);
 153
 154         /* Allocate buffer and write out command. */
 155         buf = g_malloc(len + 1);
 156         vsprintf(buf, format, args);
 157
 158         /* Send command. */
 159         ret = scpi->send(scpi->priv, buf);
 160
 161         /* Free command buffer. */
 162         g_free(buf);
 163
 164         return ret;
 165 }
 166
 167 /**
 168  * Begin receiving an SCPI reply.
 169  *
 170  * @param scpi Previously initialised SCPI device structure.
 171  *
 172  * @return SR_OK on success, SR_ERR on failure.
 173  */
 174 SR_PRIV int sr_scpi_read_begin(struct sr_scpi_dev_inst *scpi)
 175 {
 176         return scpi->read_begin(scpi->priv);
 177 }
 178
 179 /**
 180  * Read part of a response from SCPI device.
 181  *
 182  * @param scpi Previously initialised SCPI device structure.
 183  * @param buf Buffer to store result.
 184  * @param maxlen Maximum number of bytes to read.
 185  *
 186  * @return Number of bytes read, or SR_ERR upon failure.
 187  */
 188 SR_PRIV int sr_scpi_read_data(struct sr_scpi_dev_inst *scpi,
 189                         char *buf, int maxlen)
 190 {
 191         return scpi->read_data(scpi->priv, buf, maxlen);
 192 }
 193
 194 /**
 195  * Check whether a complete SCPI response has been received.
 196  *
 197  * @param scpi Previously initialised SCPI device structure.
 198  *
 199  * @return 1 if complete, 0 otherwise.
 200  */
 201 SR_PRIV int sr_scpi_read_complete(struct sr_scpi_dev_inst *scpi)
 202 {
 203         return scpi->read_complete(scpi->priv);
 204 }
 205
 206 /**
 207  * Close SCPI device.
 208  *
 209  * @param scpi Previously initialized SCPI device structure.
 210  *
 211  * @return SR_OK on success, SR_ERR on failure.
 212  */
 213 SR_PRIV int sr_scpi_close(struct sr_scpi_dev_inst *scpi)
 214 {
 215         return scpi->close(scpi->priv);
 216 }
 217
 218 /**
 219  * Free SCPI device.
 220  *
 221  * @param scpi Previously initialized SCPI device structure.
 222  *
 223  * @return SR_OK on success, SR_ERR on failure.
 224  */
 225 SR_PRIV void sr_scpi_free(struct sr_scpi_dev_inst *scpi)
 226 {
 227         scpi->free(scpi->priv);
 228         g_free(scpi);
 229 }
 230
 231 /**
 232  * Send a SCPI command, receive the reply and store the reply in scpi_response.
 233  *
 234  * @param scpi Previously initialised SCPI device structure.
 235  * @param command The SCPI command to send to the device (can be NULL).
 236  * @param scpi_response Pointer where to store the SCPI response.
 237  *
 238  * @return SR_OK on success, SR_ERR on failure.
 239  */
 240 SR_PRIV int sr_scpi_get_string(struct sr_scpi_dev_inst *scpi,
 241                                const char *command, char **scpi_response)
 242 {
 243         char buf[256];
 244         int len;
 245         GString *response;
 246
 247         if (command)
 248                 if (sr_scpi_send(scpi, command) != SR_OK)
 249                         return SR_ERR;
 250
 251         if (sr_scpi_read_begin(scpi) != SR_OK)
 252                 return SR_ERR;
 253
 254         response = g_string_new("");
 255
 256         *scpi_response = NULL;
 257
 258         while (!sr_scpi_read_complete(scpi)) {
 259                 len = sr_scpi_read_data(scpi, buf, sizeof(buf));
 260                 if (len < 0) {
 261                         g_string_free(response, TRUE);
 262                         return SR_ERR;
 263                 }
 264                 g_string_append_len(response, buf, len);
 265         }
 266
 267         *scpi_response = response->str;
 268         g_string_free(response, FALSE);
 269
 270         return SR_OK;
 271 }
 272
 273 /**
 274  * Send a SCPI command, read the reply, parse it as a bool value and store the
 275  * result in scpi_response.
 276  *
 277  * @param scpi Previously initialised SCPI device structure.
 278  * @param command The SCPI command to send to the device (can be NULL).
 279  * @param scpi_response Pointer where to store the parsed result.
 280  *
 281  * @return SR_OK on success, SR_ERR on failure.
 282  */
 283 SR_PRIV int sr_scpi_get_bool(struct sr_scpi_dev_inst *scpi,
 284                              const char *command, gboolean *scpi_response)
 285 {
 286         int ret;
 287         char *response;
 288
 289         response = NULL;
 290
 291         if (sr_scpi_get_string(scpi, command, &response) != SR_OK)
 292                 if (!response)
 293                         return SR_ERR;
 294
 295         if (parse_strict_bool(response, scpi_response) == SR_OK)
 296                 ret = SR_OK;
 297         else
 298                 ret = SR_ERR;
 299
 300         g_free(response);
 301
 302         return ret;
 303 }
 304
 305 /**
 306  * Send a SCPI command, read the reply, parse it as an integer and store the
 307  * result in scpi_response.
 308  *
 309  * @param scpi Previously initialised SCPI device structure.
 310  * @param command The SCPI command to send to the device (can be NULL).
 311  * @param scpi_response Pointer where to store the parsed result.
 312  *
 313  * @return SR_OK on success, SR_ERR on failure.
 314  */
 315 SR_PRIV int sr_scpi_get_int(struct sr_scpi_dev_inst *scpi,
 316                             const char *command, int *scpi_response)
 317 {
 318         int ret;
 319         char *response;
 320
 321         response = NULL;
 322
 323         if (sr_scpi_get_string(scpi, command, &response) != SR_OK)
 324                 if (!response)
 325                         return SR_ERR;
 326
 327         if (sr_atoi(response, scpi_response) == SR_OK)
 328                 ret = SR_OK;
 329         else
 330                 ret = SR_ERR;
 331
 332         g_free(response);
 333
 334         return ret;
 335 }
 336
 337 /**
 338  * Send a SCPI command, read the reply, parse it as a float and store the
 339  * result in scpi_response.
 340  *
 341  * @param scpi Previously initialised SCPI device structure.
 342  * @param command The SCPI command to send to the device (can be NULL).
 343  * @param scpi_response Pointer where to store the parsed result.
 344  *
 345  * @return SR_OK on success, SR_ERR on failure.
 346  */
 347 SR_PRIV int sr_scpi_get_float(struct sr_scpi_dev_inst *scpi,
 348                               const char *command, float *scpi_response)
 349 {
 350         int ret;
 351         char *response;
 352
 353         response = NULL;
 354
 355         if (sr_scpi_get_string(scpi, command, &response) != SR_OK)
 356                 if (!response)
 357                         return SR_ERR;
 358
 359         if (sr_atof(response, scpi_response) == SR_OK)
 360                 ret = SR_OK;
 361         else
 362                 ret = SR_ERR;
 363
 364         g_free(response);
 365
 366         return ret;
 367 }
 368
 369 /**
 370  * Send a SCPI command, read the reply, parse it as a double and store the
 371  * result in scpi_response.
 372  *
 373  * @param scpi Previously initialised SCPI device structure.
 374  * @param command The SCPI command to send to the device (can be NULL).
 375  * @param scpi_response Pointer where to store the parsed result.
 376  *
 377  * @return SR_OK on success, SR_ERR on failure.
 378  */
 379 SR_PRIV int sr_scpi_get_double(struct sr_scpi_dev_inst *scpi,
 380                                const char *command, double *scpi_response)
 381 {
 382         int ret;
 383         char *response;
 384
 385         response = NULL;
 386
 387         if (sr_scpi_get_string(scpi, command, &response) != SR_OK)
 388                 if (!response)
 389                         return SR_ERR;
 390
 391         if (sr_atod(response, scpi_response) == SR_OK)
 392                 ret = SR_OK;
 393         else
 394                 ret = SR_ERR;
 395
 396         g_free(response);
 397
 398         return ret;
 399 }
 400
 401 /**
 402  * Send a SCPI *OPC? command, read the reply and return the result of the
 403  * command.
 404  *
 405  * @param scpi Previously initialised SCPI device structure.
 406  *
 407  * @return SR_OK on success, SR_ERR on failure.
 408  */
 409 SR_PRIV int sr_scpi_get_opc(struct sr_scpi_dev_inst *scpi)
 410 {
 411         unsigned int i;
 412         gboolean opc;
 413
 414         for (i = 0; i < SCPI_READ_RETRIES; ++i) {
 415                 sr_scpi_get_bool(scpi, SCPI_CMD_OPC, &opc);
 416                 if (opc)
 417                         return SR_OK;
 418                 g_usleep(SCPI_READ_RETRY_TIMEOUT);
 419         }
 420
 421         return SR_ERR;
 422 }
 423
 424 /**
 425  * Send a SCPI command, read the reply, parse it as comma separated list of
 426  * floats and store the as an result in scpi_response.
 427  *
 428  * @param scpi Previously initialised SCPI device structure.
 429  * @param command The SCPI command to send to the device (can be NULL).
 430  * @param scpi_response Pointer where to store the parsed result.
 431  *
 432  * @return SR_OK upon successfully parsing all values, SR_ERR upon a parsing
 433  *         error or upon no response. The allocated response must be freed by
 434  *         the caller in the case of an SR_OK as well as in the case of
 435  *         parsing error.
 436  */
 437 SR_PRIV int sr_scpi_get_floatv(struct sr_scpi_dev_inst *scpi,
 438                                const char *command, GArray **scpi_response)
 439 {
 440         int ret;
 441         float tmp;
 442         char *response;
 443         gchar **ptr, **tokens;
 444         GArray *response_array;
 445
 446         ret = SR_OK;
 447         response = NULL;
 448         tokens = NULL;
 449
 450         if (sr_scpi_get_string(scpi, command, &response) != SR_OK)
 451                 if (!response)
 452                         return SR_ERR;
 453
 454         tokens = g_strsplit(response, ",", 0);
 455         ptr = tokens;
 456
 457         response_array = g_array_sized_new(TRUE, FALSE, sizeof(float), 256);
 458
 459         while (*ptr) {
 460                 if (sr_atof(*ptr, &tmp) == SR_OK)
 461                         response_array = g_array_append_val(response_array,
 462                                                             tmp);
 463                 else
 464                         ret = SR_ERR;
 465
 466                 ptr++;
 467         }
 468         g_strfreev(tokens);
 469         g_free(response);
 470
 471         if (ret == SR_ERR && response_array->len == 0) {
 472                 g_array_free(response_array, TRUE);
 473                 *scpi_response = NULL;
 474                 return SR_ERR;
 475         }
 476
 477         *scpi_response = response_array;
 478
 479         return ret;
 480 }
 481
 482 /**
 483  * Send a SCPI command, read the reply, parse it as comma separated list of
 484  * unsigned 8 bit integers and store the as an result in scpi_response.
 485  *
 486  * @param scpi Previously initialised SCPI device structure.
 487  * @param command The SCPI command to send to the device (can be NULL).
 488  * @param scpi_response Pointer where to store the parsed result.
 489  *
 490  * @return SR_OK upon successfully parsing all values, SR_ERR upon a parsing
 491  *         error or upon no response. The allocated response must be freed by
 492  *         the caller in the case of an SR_OK as well as in the case of
 493  *         parsing error.
 494  */
 495 SR_PRIV int sr_scpi_get_uint8v(struct sr_scpi_dev_inst *scpi,
 496                                const char *command, GArray **scpi_response)
 497 {
 498         int tmp, ret;
 499         char *response;
 500         gchar **ptr, **tokens;
 501         GArray *response_array;
 502
 503         ret = SR_OK;
 504         response = NULL;
 505         tokens = NULL;
 506
 507         if (sr_scpi_get_string(scpi, command, &response) != SR_OK)
 508                 if (!response)
 509                         return SR_ERR;
 510
 511         tokens = g_strsplit(response, ",", 0);
 512         ptr = tokens;
 513
 514         response_array = g_array_sized_new(TRUE, FALSE, sizeof(uint8_t), 256);
 515
 516         while (*ptr) {
 517                 if (sr_atoi(*ptr, &tmp) == SR_OK)
 518                         response_array = g_array_append_val(response_array,
 519                                                             tmp);
 520                 else
 521                         ret = SR_ERR;
 522
 523                 ptr++;
 524         }
 525         g_strfreev(tokens);
 526         g_free(response);
 527
 528         if (response_array->len == 0) {
 529                 g_array_free(response_array, TRUE);
 530                 *scpi_response = NULL;
 531                 return SR_ERR;
 532         }
 533
 534         *scpi_response = response_array;
 535
 536         return ret;
 537 }
 538
 539 /**
 540  * Send the *IDN? SCPI command, receive the reply, parse it and store the
 541  * reply as a sr_scpi_hw_info structure in the supplied scpi_response pointer.
 542  *
 543  * The hw_info structure must be freed by the caller via sr_scpi_hw_info_free().
 544  *
 545  * @param scpi Previously initialised SCPI device structure.
 546  * @param scpi_response Pointer where to store the hw_info structure.
 547  *
 548  * @return SR_OK upon success, SR_ERR on failure.
 549  */
 550 SR_PRIV int sr_scpi_get_hw_id(struct sr_scpi_dev_inst *scpi,
 551                               struct sr_scpi_hw_info **scpi_response)
 552 {
 553         int num_tokens;
 554         char *response;
 555         char *newline;
 556         gchar **tokens;
 557         struct sr_scpi_hw_info *hw_info;
 558
 559         response = NULL;
 560         tokens = NULL;
 561
 562         if (sr_scpi_get_string(scpi, SCPI_CMD_IDN, &response) != SR_OK)
 563                 if (!response)
 564                         return SR_ERR;
 565
 566         sr_info("Got IDN string: '%s'", response);
 567
 568         /* Remove trailing newline if present. */
 569         if ((newline = g_strrstr(response, "\n")))
 570                 newline[0] = '\0';
 571
 572         /*
 573          * The response to a '*IDN?' is specified by the SCPI spec. It contains
 574          * a comma-separated list containing the manufacturer name, instrument
 575          * model, serial number of the instrument and the firmware version.
 576          */
 577         tokens = g_strsplit(response, ",", 0);
 578
 579         for (num_tokens = 0; tokens[num_tokens] != NULL; num_tokens++);
 580
 581         if (num_tokens != 4) {
 582                 sr_dbg("IDN response not according to spec: %80.s.", response);
 583                 g_strfreev(tokens);
 584                 g_free(response);
 585                 return SR_ERR;
 586         }
 587         g_free(response);
 588
 589         hw_info = g_try_malloc(sizeof(struct sr_scpi_hw_info));
 590         if (!hw_info) {
 591                 g_strfreev(tokens);
 592                 return SR_ERR_MALLOC;
 593         }
 594
 595         hw_info->manufacturer = g_strdup(tokens[0]);
 596         hw_info->model = g_strdup(tokens[1]);
 597         hw_info->serial_number = g_strdup(tokens[2]);
 598         hw_info->firmware_version = g_strdup(tokens[3]);
 599
 600         g_strfreev(tokens);
 601
 602         *scpi_response = hw_info;
 603
 604         return SR_OK;
 605 }
 606
 607 /**
 608  * Free a sr_scpi_hw_info struct.
 609  *
 610  * @param hw_info Pointer to the struct to free.
 611  *
 612  * This function is safe to call with a NULL pointer.
 613  */
 614 SR_PRIV void sr_scpi_hw_info_free(struct sr_scpi_hw_info *hw_info)
 615 {
 616         if (hw_info) {
 617                 g_free(hw_info->manufacturer);
 618                 g_free(hw_info->model);
 619                 g_free(hw_info->serial_number);
 620                 g_free(hw_info->firmware_version);
 621                 g_free(hw_info);
 622         }
 623 }