# Si4438 revB1B Command/Property API Documentation

#### Interface Version: 1.0

#### Document Version: 2.0.5

#### Generated: 2015-03-18T10:15:42-05:00

## Introduction

This document provides API descriptions for the commands and properties used to control and configure the part. The interface version tracks any functional changes to the API (command, property, field, enumeration, etc.). The documentation version tracks any text changes to the summary or description text of the API components.
The commands are listed in a summary table with links to command details. The properties are listed in a summary table with links to property details. The feature available column in the summary tables lists the firmware revision which first implemented the command or property.
An entry in the summary table will link to a details section, which contains a register view with fields. Clicking a field in the register view will auto-expand the corresponding field details. An up button in the field detail links back to the register view. Each register view title links back to the summary table entry. These hyper-links provide two-click access from top to bottom.

## Command Summary

| BOOT_COMMANDS
--- | ---
| Number | Name | Summary | Feature Available
| 0x02 | POWER_UP | Command to power-up the device and select the operational mode and functionality. |

| COMMON_COMMANDS
--- | ---
| Number | Name | Summary | Feature Available
| 0x00 | NOP | No Operation command. |
| 0x01 | PART_INFO | Reports basic information about the device. |
| 0x10 | FUNC_INFO | Returns the Function revision information of the device. |
| 0x44 | READ_CMD_BUFF | Used to read CTS and the command response. |

| ADVANCED_COMMANDS
--- | ---
| Number | Name | Summary | Feature Available
| 0x23 | GET_CHIP_STATUS | Returns the interrupt status of the Chip Interrupt Group (both STATUS and PENDING). Optionally, it may be used to clear latched (PENDING) interrupt events. |

## Property Summary

## Command Details

### BOOT_COMMANDS

#### POWER_UP

- Number: 0x02
- Summary: Command to power-up the device and select the operational mode and functionality.
- Purpose:
- Argument Stream:

  POWER_UP Argument Stream
  | Index | Name | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  | 0x00 | CMD | 0x02
  | 0x01 | BOOT_OPTIONS | PATCH | 0 | FUNC
  | 0x02 | RESERVED0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
  | 0x03 | XO_FREQ | XO_FREQ[31:24]
  0x04 | XO_FREQ[23:16]
  0x05 | XO_FREQ[15:8]
  0x06 | XO_FREQ[7:0]

- Reply Stream:

  POWER_UP Reply Stream
  | Index | Name | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  | 0x00 | CTS | CTS

- Argument Fields:

  ###### BOOT_OPTIONS

  PATCH
  Description:
    Select patch mode or normal boot mode.
  Format:
    Enumeration

    Name | Value | Description | Feature Available
    --- | --- | --- | ---
    NO_PATCH | 0 | Power up into functional mode specified by FUNC parameter. |
    PATCH | 1 | Indicates a patch has been applied. Validate patch matches the function selected (indicated by the FUNC parameter) and boot the device. |

  FUNC[5:0]
  Description:
    Selects the functionality of the device by specifying the firmware image to be loaded upon boot-up.
  Format:
    Enumeration

    Name | Value | Description | Feature Available
    --- | --- | --- | ---

  ###### XO_FREQ

  XO_FREQ[31:0]
  Description:
    - Specifies the frequency of the internal crystal oscillator or external TCXO in Hz. The nominal value is 30000000 (30 MHz) = 0x01C9C380.
    - This parameter is used during calibration of the Boot Clock Oscillator and 32kHz R-C Oscillator, but is NOT used for calibration or tuning of the PLL Synthesizer.
  Type:
    U32
  Min:
    0x17d7840
  Max:
    0x1e84800
- Reply Fields:

  ###### CTS

  CTS[7:0]
  Description:
    Clear to Send. Indicates that the previous command has completed execution and the response byte stream (if any) is valid. The next command may be sent.
  Type:
    U8

### COMMON_COMMANDS

#### NOP

- Number: 0x00
- Summary: No Operation command.
- Purpose:
  - This command may be used to ensure that communication with the device has been established. Upon receipt of this command, the chip performs no action except to return CTS.
- Argument Stream:

  NOP Argument Stream
  | Index | Name | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  | 0x00 | CMD | 0x00

- Reply Stream:

  NOP Reply Stream
  | Index | Name | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  | 0x00 | CTS | CTS

- Argument Fields:
- Reply Fields:

  ###### CTS

  CTS[7:0]
  Description:
    Clear to Send. Indicates that the previous command has completed execution and the response byte stream (if any) is valid. The next command may be sent.
  Type:
    U8

#### PART_INFO

- Number: 0x01
- Summary: Reports basic information about the device.
- Purpose:
  - Returns Part Number, Part Version, ROM ID, etc.
- Argument Stream:

  PART_INFO Argument Stream
  | Index | Name | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  | 0x00 | CMD | 0x01

- Reply Stream:

  PART_INFO Reply Stream
  | Index | Name | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  | 0x00 | CTS | CTS
  | 0x01 | CHIPREV | CHIPREV
  | 0x02 | PART | PART[15:8]
  0x03 | PART[7:0]
  | 0x04 | PBUILD | PBUILD
  | 0x05 | ID | ID[15:8]
  0x06 | ID[7:0]
  | 0x07 | CUSTOMER | CUSTOMER
  | 0x08 | ROMID | ROMID

- Argument Fields:
- Reply Fields:

  ###### CTS

  CTS[7:0]
  Description:
    Clear to Send. Indicates that the previous command has completed execution and the response byte stream (if any) is valid. The next command may be sent.
  Type:
    U8

  ###### CHIPREV

  CHIPREV[7:0]
  Description:
    Chip Mask Revision.
  Type:
    U8

  ###### PART

  PART[15:0]
  Description:
    Part Number (e.g., si4461 will return - 0x4461).
  Type:
    U16

  ###### PBUILD

  PBUILD[7:0]
  Description:
    Part Build.
  Type:
    U8

  ###### ID

  ID[15:0]
  Description:
    Id.
  Type:
    U16

  ###### CUSTOMER

  CUSTOMER[7:0]
  Description:
    Customer ID.
  Type:
    U8

  ###### ROMID

  ROMID[7:0]
  Description:
    ROM Id.
  Type:
    U8

#### FUNC_INFO

- Number: 0x10
- Summary: Returns the Function revision information of the device.
- Purpose:
  - Return Function revision numbers for currently loaded functional mode. Contrast with PART_INFO.
- Argument Stream:

  FUNC_INFO Argument Stream
  | Index | Name | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  | 0x00 | CMD | 0x10

- Reply Stream:

  FUNC_INFO Reply Stream
  | Index | Name | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  | 0x00 | CTS | CTS
  | 0x01 | REVEXT | REVEXT
  | 0x02 | REVBRANCH | REVBRANCH
  | 0x03 | REVINT | REVINT
  | 0x04 | PATCH | PATCH[15:8]
  0x05 | PATCH[7:0]
  | 0x06 | FUNC | FUNC

- Argument Fields:
- Reply Fields:

  ###### CTS

  CTS[7:0]
  Description:
    Clear to Send. Indicates that the previous command has completed execution and the response byte stream (if any) is valid. The next command may be sent.
  Type:
    U8

  ###### REVEXT

  REVEXT[7:0]
  Description:
    External revision number.
  Type:
    U8
  Min:
    0x0
  Max:
    0xff

  ###### REVBRANCH

  REVBRANCH[7:0]
  Description:
    Branch revision number.
  Type:
    U8
  Min:
    0x0
  Max:
    0xff

  ###### REVINT

  REVINT[7:0]
  Description:
    Internal revision number.
  Type:
    U8
  Min:
    0x0
  Max:
    0xff

  ###### PATCH

  PATCH[15:0]
  Description:
    - ID of applied patch. This is also the last 2 bytes in the associated patch file (*.csg).
    - 0x0000 = No patch applied.
  Type:
    U16

  ###### FUNC

  FUNC[7:0]
  Description:
    Current functional mode.
  Type:
    U8

#### READ_CMD_BUFF

- Number: 0x44
- Summary: Used to read CTS and the command response.
- Purpose:
  - Processing of API commands is handled by the command handler in the chip. A subsequent command may not be sent until the chip has completed processing of the first command. The chip indicates the ability to receive another command and the availability of response data by issuing a Clear To Send (CTS) signal; it is necessary for the host MCU to poll the chip for this CTS signal. The CTS signal may be polled via SPI command, or monitored on a GPIO line or as an interrupt on the nIRQ pin.
  - This command is used to poll the CTS signal via the SPI bus. The NSEL line should be pulled low, followed by sending the READ_CMD_BUFF command on SDI. While NSEL remains asserted low, an additional eight clock pulses are sent on SCLK and the CTS response byte is read on SDO. If the CTS response byte is not 0xFF, the host MCU should pull NSEL high and repeat the polling procedure.
  - If the CTS response byte is 0xFF, the host MCU should keep NSEL asserted low and provide additional clock cycles on SCLK to read out as many response bytes (on SDO) as necessary. The host MCU should pull NSEL high upon completion of reading the response stream.
  - A primary function of this command is to determine when CTS goes high, and thus by definition this command may be sent while CTS is low. This command itself does not cause CTS to go low.
  - Attempting to read response bytes from the command buffer while CTS is not 0xFF will return invalid results. The response bytes are valid only if CTS = 0xFF.
- Argument Stream:

  READ_CMD_BUFF Argument Stream
  | Index | Name | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  | 0x00 | CMD | 0x44

- Reply Stream:

  READ_CMD_BUFF Reply Stream
  | Index | Name | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  | 0x00 | CTS | CTS
  | 0x01 | BYTE[0] | CMD_BUFF
  | ... | ... | ...
  | 0x10 | BYTE[15] | CMD_BUFF

- Argument Fields:
- Reply Fields:

  ###### CTS

  CTS[7:0]
  Description:
    Clear to Send. Indicates that the previous command has completed execution and the response byte stream (if any) is valid. The next command may be sent.
  Type:
    U8

  ###### BYTE[0...15]

  CMD_BUFF[7:0]
  Description:
    Byte 0-15 of the command response buffer.
  Type:
    U8

### ADVANCED_COMMANDS

#### GET_CHIP_STATUS

- Number: 0x23
- Summary: Returns the interrupt status of the Chip Interrupt Group (both STATUS and PENDING). Optionally, it may be used to clear latched (PENDING) interrupt events.
- Purpose:
  - Returns the current interrupt status of Chip interrupt events (both STATUS and PENDING) and optionally clears PENDING interrupts.
  - Please refer to the GET_INT_STATUS command for more details regarding the difference between STATUS and PENDING interrupts.
  - Sending the GET_CHIP_STATUS command with NO input parameter results in clearing all of the PENDING interrupts.
  - When PENDING interrupts are being cleared, the reply stream reflects their status prior to clearing.
- Argument Stream:

  GET_CHIP_STATUS Argument Stream
  | Index | Name | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  | 0x00 | CMD | 0x23
  | 0x01 | CHIP_CLR_PEND | 0 | CAL_PEND_CLR | FIFO_UNDERFLOW_OVERFLOW_ERROR_PEND_CLR | STATE_CHANGE_PEND_CLR | CMD_ERROR_PEND_CLR | CHIP_READY_PEND_CLR | LOW_BATT_PEND_CLR | WUT_PEND_CLR

- Reply Stream:

  GET_CHIP_STATUS Reply Stream
  | Index | Name | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  | 0x00 | CTS | CTS
  | 0x01 | CHIP_PEND | X | CAL_PEND | FIFO_UNDERFLOW_OVERFLOW_ERROR_PEND | STATE_CHANGE_PEND | CMD_ERROR_PEND | CHIP_READY_PEND | LOW_BATT_PEND | WUT_PEND
  | 0x02 | CHIP_STATUS | X | CAL | FIFO_UNDERFLOW_OVERFLOW_ERROR | STATE_CHANGE | CMD_ERROR | CHIP_READY | LOW_BATT | WUT
  | 0x03 | CMD_ERR_STATUS | CMD_ERR_STATUS
  | 0x04 | CMD_ERR_CMD_ID | CMD_ERR_CMD_ID

- Argument Fields:

  ###### CHIP_CLR_PEND

  CAL_PEND_CLR
  Description:
    If clear, clear any pending CAL interrupt. If set, leave interrupt pending.
  Type:
    BOOL
  FIFO_UNDERFLOW_OVERFLOW_ERROR_PEND_CLR
  Description:
    If clear, clear any pending FIFO_UNDERFLOW_OVERFLOW_ERROR interrupt. If set, leave interrupt pending.
  Type:
    BOOL
  STATE_CHANGE_PEND_CLR
  Description:
    If clear, clear any pending STATE_CHANGE interrupt. If set, leave interrupt pending.
  Type:
    BOOL
  CMD_ERROR_PEND_CLR
  Description:
    If clear, clear any pending CMD_ERROR interrupt. If set, leave interrupt pending.
  Type:
    BOOL
  CHIP_READY_PEND_CLR
  Description:
    If clear, clear any pending CHIP_READY interrupt. If set, leave interrupt pending.
  Type:
    BOOL
  LOW_BATT_PEND_CLR
  Description:
    If clear, clear any pending LOW_BATT interrupt. If set, leave interrupt pending.
  Type:
    BOOL
  WUT_PEND_CLR
  Description:
    If clear, clear any pending WUT interrupt. If set, leave interrupt pending.
  Type:
    BOOL
- Reply Fields:

  ###### CTS

  CTS[7:0]
  Description:
    Clear to Send. Indicates that the previous command has completed execution and the response byte stream (if any) is valid. The next command may be sent.
  Type:
    U8

  ###### CHIP_PEND

  CAL_PEND
  Description:
    If set, a rising edge of the CAL status bit has been detected and therefore a CAL interrupt is pending. See associated CAL status bit for more details.
  Type:
    BOOL
  FIFO_UNDERFLOW_OVERFLOW_ERROR_PEND
  Description:
    If set, a rising edge of the FIFO_UNDERFLOW_OVERFLOW_ERROR status bit has been detected and therefore a FIFO_UNDERFLOW_OVERFLOW_ERROR interrupt is pending. See associated FIFO_UNDERFLOW_OVERFLOW_ERROR status bit for more details.
  Type:
    BOOL
  STATE_CHANGE_PEND
  Description:
    If set, a rising edge of the STATE_CHANGE status bit has been detected and therefore a STATE_CHANGE interrupt is pending. See associated STATE_CHANGE status bit for more details.
  Type:
    BOOL
  CMD_ERROR_PEND
  Description:
    If set, a rising edge of the CMD_ERROR status bit has been detected and therefore a CMD_ERROR interrupt is pending. See associated CMD_ERROR status bit for more details.
  Type:
    BOOL
  CHIP_READY_PEND
  Description:
    If set, a rising edge of the CHIP_READY status bit has been detected and therefore a CHIP_READY interrupt is pending. See associated CHIP_READY status bit for more details.
  Type:
    BOOL
  LOW_BATT_PEND
  Description:
    If set, a rising edge of the LOW_BATT status bit has been detected and therefore a LOW_BATT interrupt is pending. See associated LOW_BATT status bit for more details.
  Type:
    BOOL
  WUT_PEND
  Description:
    If set, a rising edge of the WUT status bit has been detected and therefore a WUT interrupt is pending. See associated WUT status bit for more details.
  Type:
    BOOL

  ###### CHIP_STATUS

  CAL
  Description:
    Self clearing signal that pulses high to indicate a RC32K calibration event is pending. If this occurs, the RC32K oscillator will be calibrated on the next transition to Sleep/Standby state.
  Type:
    BOOL
  FIFO_UNDERFLOW_OVERFLOW_ERROR
  Description:
    Set to indicate that the number of received or transmitted bytes exceeds the size of the RX or TX FIFO, respectively (i.e., 64 bytes for each FIFO, or 129 bytes when sharing the FIFO). Upon such an underflow/overflow event, the FIFO(s) will need to be reset. Cleared by issuing a FIFO_INFO command to reset the FIFOs.
  Type:
    BOOL
  STATE_CHANGE
  Description:
    Set to indicate a successful transition from one state to another operating state. Cleared when a state transition is in progress.
  Type:
    BOOL
  CMD_ERROR
  Description:
    Self clearing signal that pulses high to indicate an error has occurred in the processing of a command. For example, an incorrect command/property ID is sent, or an attempt was made to write a property that is outside of the given property group.
  Type:
    BOOL
  CHIP_READY
  Description:
    Set to indicate the chip (upon completion of the POWER_UP sequence) has reached the state where it is ready to accept commands, or when the IR calibration process is completed. Cleared when the chip is shutdown or when IR calibration has begun.
  Type:
    BOOL
  LOW_BATT
  Description:
    Set to indicate the battery voltage is below the threshold set by GLOBAL_LOW_BATT_THRESH. Cleared to indicate the battery voltage is above the threshold set by GLOBAL_LOW_BATT_THRESH.
  Type:
    BOOL
  WUT
  Description:
    Self clearing signal that pulses high to indicate the WUT (Wake-up timer) has expired.
  Type:
    BOOL

  ###### CMD_ERR_STATUS

  CMD_ERR_STATUS[7:0]
  Description:
    Last command error cause. Only valid if CMD_ERROR status bit is set.
  Format:
    Enumeration

    Name | Value | Description | Feature Available
    --- | --- | --- | ---
    CMD_ERROR_NONE | 0 | No error. |
    CMD_ERROR_BAD_COMMAND | 16 | Bad command issued. |
    CMD_ERROR_BAD_ARG | 17 | Argment(s) in issued command were invalid. |
    CMD_ERROR_COMMAND_BUSY | 18 | Command was issued before previous command was completed. |
    CMD_ERROR_BAD_BOOTMODE | 49 | Invalid bootmode supplied. |
    CMD_ERROR_BAD_PROPERTY | 64 | Bad Property ID was provided. |

  ###### CMD_ERR_CMD_ID

  CMD_ERR_CMD_ID[7:0]
  Description:
    Command ID that was being proccessed at the time of the last command error.
  Type:
    ENUM

## Property Details