1. Home
  2. OnLogic Systems
  3. Rugged Line
  4. Karbon Series
  5. Karbon Series – Using The Serial Interface

Karbon Series – Using The Serial Interface

The Karbon series’ serial and DIO interfaces are connected to the microcontroller (MCU), which allows it to be programmed to suit your applications. When it comes to using the serial interface, there are options of different methods to use. Here we will introduce those methods and provide technical details on commands you can use in your serial interface.

Method 1 – Serial Terminal Program

Using a serial terminal program to interface with the MCU provides the most ‘terminal like’ experience, but is the least automatable option. The following example uses the popular terminal program ‘PuTTY’, however, provided it has the local line editing, the serial terminal of your preference should work just as well. The steps are as follows:

  1. Download and launch PuTTY
  2. You should now see a window that looks like this:
  3. Select ‘Serial’ from connection type
  4. Under ‘Serial line’ enter the name of the serial terminal device. Generally, this will be COM4 on Windows and /dev/ttyACM1 on Linux
  5. Select the ‘Terminal’ category on the left menu and force ‘Local echo’ and ‘Local line editing’ on as such:
  6. Click ‘Open’ to launch the interface. You can now enter commands directly to this terminal

Method 2 – Pykarbon

  1. Download and install Python 3
  2. Install the pySerial module by running the following line from a command terminal:
    python -m install pykarbon
  3. See the tech resource site for further reference on how to set up and work with Pykarbon

Serial Interface Technical Details – Connection Specs

  1. Baudrate
    • Recommended baud rate: 9600
    • Note: Because the Karbon series operates using a virtual serial port, it is able to support a broad range of baud rates. It is not required to operate the serial interface at the recommended rate.
  2. Flow Control
    • XON/XOFF
  3. Command Format
    • Commands are expected to be sent by line instead of by character, such that each command requires a single transaction. Line terminating characters will be ignored. The system is not sensitive to CRLF vs LF termination.
  4. Received Data Format
    • Each line of returned data will be “/n/r” terminated

Karbon Serial Interface – Commands

Commands sent to the Karbon computer should be in all lower case, and transmitted to the Serial Terminal port in a single transaction. Commands are not sensitive to line termination.

An error response will be sent if an unsupported command is sent or if the command is transmitted with the wrong number of accompanying arguments. 

Serial Commands – CAN Bus

Some CAN configuration settings, alongside limited CAN messaging are supported through the Karbon Serial Interface. Sending complex messages, and receiving data, is handled by the dedicated CAN virtual serial port. More information is available in the CAN Bus FAQ.

Note: The CAN device is not internally terminated; a properly terminated cable or bus is required for correct CAN operation.

The commands available through the serial terminal include:

can-message [id] [data]
  Description:
      Formats and sends a standard can data frame.
  Parameters:
      id   --> The message id. A three character hex string (1 - 7FF)
      data --> Data to transmit: A sixteen character hex string.
  Example:
      can-message 123 1122334455667788
can-autobaud
  Description:
      Attempts to detect the baudrate and propagation delay of the bus.
      This is achieved by sending messages with the id 7FF, and may not
      work in every possible configuration.

      To maintain a detected baudrate across hard power cycles, please see
      the 'save-config' terminal command.
  Parameters:
      -
  Example:
      can-autobaud
set can-baudrate [baud]
  Description:
      Sets the baudrate for CAN bus communication.

      To maintain a set baudrate across hard power cycles, please see the
      'save-config' terminal command.
  Parameters:
      baud --> The system baudrate, in thousands: 100 - 1000 (k)
  Example:
      set can-baudrate 1000

Serial Commands – Digital IO

Controlling the Karbon Digital IO (DIO) is handled entirely through the serial terminal interface. The DIO state may be read, and output states may be set. Additionally, when an input changes state, that event will be passed to the serial terminal.

Note: The digital io is isolated, and requires external power for proper operation. The system manual has additional information on these electrical characteristics.

The commands available through the serial terminal interface include:

dio-state
  Description:
      Reports the current logical states of the digital inputs/outputs.
      This is represented by eight characters, each a '1' or '0'.
      
      The bit order is: I0 - I1 - I2 - I3 - O0 - O1 - O2 - O3
      Where 'I' is a digital input and 'O' is a digital output.

      For example: 10010110
  Parameters:
      -
  Example:
      dio-state
set-do [value]
  Description:
      Sets the output state of the four digital outputs.
  Parameters:
      value --> A four character string of '1', '-' or '0'.
          A '1' or '0' will set the output to the corresponding state,
          while a '-' will not change the sate of the matching output pin.
  Example:
      set-do 0--1
set dio-power-switch [enable]
  Description:
      When enabled, any of the front digital inputs can be used to power
      the system on. Once the system is powered on, they will behave as a
      typical digital input.
  Parameters:
      enable --> Enable or disable: 'on' or 'off'
  Example:
      set dio-power-switch on

Serial Commands – System Information

The serial terminal can report various system information to the host. This covers firmware version and build date, alongside physical and electrical status information. For instance, the K700 can report the current system input voltage, internal temperature, and internal humidity.

The available information is system dependent, and is not unified across all Karbon systems.

Commands for reporting this information include:

version
  Description:
      Reports the firmware version number and build date.

      Uses the format: < version | date >
  Parameters:
      -
  Example:
      version
status
  Description:
      Reports the firmware version number and system dependent status
      information. 
  Parameters:
      -
  Example:
      status
get-voltage
  Description:
      Reports the current system input voltage.

      This command is currently only available on the K700.
  Parameters:
      -
  Example:
      get-voltage

Serial Commands – System Configuration

The Karbon series has several configuration options that effect system behavior. These primarily include automotive features, like ignition sensing and battery drain protection.

The system can store up to four different configurations, one of which will be loaded as default when the system is first powered on. This allows for temporarily disabling automotive features, like low voltage shutdown. The active configuration may be cycled by pressing the settings switch.

The available commands for controlling system configurations include:

config
  Description:
      Reports the current microcontroller configuration settings.
  Parameters:
      -
  Example:
      config
save-config
  Description:
      The description of what the command does.
  Parameters:
      param1 --> The message id. A three character hex string (1 - 7FF)
      param2 --> Data to transmit: A sixteen character hex string.
  Example:
      command arg1 arg2
user-config [config-number]
  Description:
      Sets the currently active user configuration.
  Parameters:
      config-number --> The configuration number: 1 - 4
  Example:
      user-config 2

Several configuration parameters may also be set. The include:

set ignition-sense [enable]
  Description:
      Enables or disables ignition sensing. The system will turn on when
      the ignition pin goes high, and power off if the pin falls for more
      than the specified shutdown-timer.

      This is achieved by emulating a front power button press, and can be
      interrupt by the OS. Therefore, after the hard-off timer has expired,
      the system will force a power down. 
  Parameters:
      enable --> Enable or disable: 'on' or 'off'
  Example:
      set ignition-sense off
set startup-timer [time]
  Description:
      Sets the delay before the system powers on after detecting ignition.
  Parameters:
      time --> Time delay in seconds: 0 - 9999 (s)
  Example:
      set startup-timer 15
set shutdown-voltage [volts]
  Description:
      Designed to protect automotive systems from battery drain, the system
      will turn off the input voltage drops below this level for more than
      the specified shutdown-timer.

      This is achieved by emulating a front power button press, and can be
      interrupt by the OS. Therefore, after the hard-off timer has expired,
      the system will force a power down.

      Setting this voltage to a value of '6' or less disables the feature.
  Parameters:
      volts --> The low voltage shutdown level: 0 - Max System Voltage (V)
          On the K700 this value may be a float (12.5, 19.2) but is 
          required to be an int (12, 19) on the K300. 

          Floating point shutdown voltages will be added to the K300 as
          part of a future firmware update.
  Example:
      set shutdown-voltage 12
set hotplug [enable]
  Description:
      Enables or disables display port hotplug detection.

      Disabling hotplug detection will keep displays from re-arranging if a
      monitor goes down. When disabled, the host will assume that all
      displays are always connected. 
  Parameters:
      enable --> Enable or disable: 'on' or 'off'
  Example:
      set hotplug 'on'
set shutdown-timer [time]
  Description:
      Sets the delay before the system powers off after ignition falls or
      the system voltage drops below the safe level.
  Parameters:
       time --> Time delay in seconds: 0 - 9999 (s) 
  Example:
      set shutdown-timer 20
set hard-off-timer [time]
  Description:
      Sets the delay until the system forces a power off after ignition
      falls or the system voltage drops below a safe level.  
  Parameters:
       time --> Time delay in seconds: 0 - 9999 (s)
  Example:
      set hard-off-timer 150
set boot-config [true | false]
  Description:
      Determines which user configuration is loaded when the system is
      first connected to AC power. Only one configuration may have this
      value set as true.

      By default, user configuration one is loaded at boot.
  Parameters:
      true | false: If the config is loaded at boot: 'true' or 'false'
  Example:
      set boot-config true
Updated on November 14, 2019

Was this article helpful?

Related Articles