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