Table of Contents generated with DocToc

• 1 KITRA520 COMPUTING BLOCK DIAGRAM
• 2 KITRA520 SYSTEM BLOCK DIAGRAM
• 3 INTRODUCTION
  • 3.1 Parameters
• 4 PROTOCOL DESCRIPTION
  • 4.1 Command structure
  • 4.2 Checksum calculation
• 5 STM32 PROTOCOL INPUT
  • 5.1 SYSTEM COMMAND
    • 5.1.1 Change Baud Rate
    • 5.1.2 Get firmware version
    • 5.1.3 Start fw upgrade
    • 5.1.4 Reserved
    • 5.1.5 Get kitra520 status
    • 5.1.6 Kitra520 reset
    • 5.1.7 Kitra520 sleep
  • 5.2 DIGITAL INPUT COMMAND
    • 5.2.1 Enable/Disable
    • 5.2.2 Read state
    • 5.2.3 Configure activation
  • 5.3 ANALOG INPUT COMMAND
    • 5.3.1 Enable/Disable
    • 5.3.2 Change operating mode
    • 5.3.3 Change configuration
    • 5.3.4 Read last sample
    • 5.3.5 Set notification
  • 5.4 DIGITAL OUPUT & PWM COMMAND
    • 5.4.1 Enable/Disable
    • 5.4.2 Change state
    • 5.4.3 Init/Configure PWM
    • 5.4.4 Change mode PWM
  • 5.5 CAPACITIVE TOUCH COMMAND
    • 5.5.1 Enable Disable
    • 5.5.2 Read state
    • 5.5.3 Configure notifications
    • 5.5.4 Configure
  • 5.6 LRA HAPTIC DRIVER COMMAND
    • 5.6.1 Enable/Disable
    • 5.6.2 Configuration
    • 5.6.3 Change mode
  • 5.7 PROXIMITY & LUX
    • 5.7.1 Enable/Disable
    • 5.7.2 Read lux
    • 5.7.3 Read proximity
    • 5.7.4 Sensor configuration
    • 5.7.5 Sensor notifications
    • 5.7.6 Sensor managed notifications
  • 5.8 LED RGB COMMAND
    • 5.8.1 Enable/Disable
    • 5.8.2 Set
    • 5.8.3 Set managed
    • 5.8.4 Change mode
  • 5.9 ACCELEROMETER/GYROSCOPE/MAGNETOMETER COMMAND
    • 5.9.1 Enable/Disable
    • 5.9.2 Read raw
    • 5.9.3 Read euler angles
    • 5.9.4 Configuration
    • 5.9.5 Read calibration state
    • 5.9.6 Read step counter
  • 5.10 ENVIRONMENT SENSORS COMMAND
    • 5.10.1 Enable/Disable
    • 5.10.2 Read value
    • 5.10.3 Enable notification
  • 5.11 MICROPHONE COMMAND
    • 5.11.1 Enable/Disable
    • 5.11.2 Get localization angle
  • 5.12 NEOPIXEL COMMAND
    • 5.12.1 Enable/Disable
    • 5.12.2 Set
    • 5.12.3 Change mode
  • 5.13 RESERVED
  • 5.14 BUZZER COMMAND
    • 5.14.1 Enable/Disable
    • 5.14.2 Change state
  • 5.15 I2C COMMAND
    • 5.15.1 Read I2C
    • 5.15.2 Write I2C
• 6 STM32 PROTOCOL OUTPUT
  • 6.1 SYSTEM COMMAND
    • 6.1.1 Power up
    • 6.1.2 Acknowledgment
    • 6.1.3 Error/Nack
    • 6.1.4 Get firmware version response
    • 6.1.5 Get kitra520 status response
  • 6.2 DIGITAL INPUT COMMAND
    • 6.2.1 Read state response
    • 6.2.2 State notification
  • 6.3 ANALOG INPUT COMMAND
    • 6.3.1 Read last sample response
    • 6.3.2 Sample notification
    • 6.3.3 Threshold notification
  • 6.4 CAPACITIVE TOUCH COMMAND
    • 6.4.1 Read state response
    • 6.4.2 Notification
  • 6.5 PROXIMITY & LUX
    • 6.5.1 Read lux response
    • 6.5.2 Read proximity response
    • 6.5.3 Notification
    • 6.5.4 Managed notification
  • 6.6 ACCELEROMETER/GYROSCOPE/ MAGNETOMETER COMMAND
    • 6.6.1 Read raw response
    • 6.6.2 Read euler angles response
    • 6.6.3 Notification raw
    • 6.6.4 Notification euler
    • 6.6.5 Managed notification
    • 6.6.6 Read calibration state
    • 6.6.7 Read step counter
  • 6.7 SENSORS COMMAND
    • 6.7.1 Read value response
    • 6.7.2 Notification
    • 6.7.3 Threshold notification
  • 6.8 MICROPHONE COMMAND
    • 6.8.1 Get localization response
    • 6.8.2 Localization notification
  • 6.9 I2C COMMAND
    • 6.9.1 I2C Read response

The KITRA520 platform is made of two computational level: the first one is real time and the second one is high level processing. The real time section is on an STM32F411 microcontroller and its role is to handle low level drivers and communicate with embedded modules like Artik 5. The high level computing, based on ARTIK 5 IoT core module is capable to manage audio, video and high-speed communication interfaces. These two embedded worlds communicate using only one communication peripheral and the programmer of one side do not need to study the other side but only send commands and read answers.

• 115200 bps

• 1 stop bit

• No parity

• No flow control

KITRA520 protocol enables you to control low level peripherals connected to a real time system through high level messages, providing direct and managed modes. Both modes are high level: direct expect you to manually manage data, managed mode manages data for you using built-in patterns and provide the final result. For example, polling touch coordinates fo a display and check if the user performed a swipe by software is considered direct mode. Instead, waiting for a notification like “SWIPE LEFT” or “SWIPE RIGHT” is considered managed. Both modes can be used simultaneously, there is no command to explicitly enable direct or managed mode. If you configure a peripheral to send you a swipe event that doesn’t disable the possibility to poll.

Commands are composed by comma separated ASCII strings, all start with $KITRA string. Commands are followed by a 8bit checksum and ended with < CR >< LF >. Command structure is the same of the NMEA protocol used in many GPS receivers. Every field of the packet must be ordered as shown in the command table, it is possible to leave fields empty if they are optional.

Ex.$KITRA,523,2,1,1,,,*1F< CR >< LF > valid

Ex.$KITRA,523,2,1,1*33< CR ><LF > valid

Communication is mostly master-slave, except for start command, errors and notifications.

The checksum is appended at the end of the command and is composed by a "*" character and a checksum 8 bit value calculated over the whole packet string ("$" and "*" not included), represented as two hex characters. It is calculated xoring every character.

C:

void getChecksum(char* packet, char* chks) {
    char n_chks = 0;
    int len = strlen(packet);
    for (int c = 0; c < len; c++) {
        n_chks = (char)(n_chks ^ packet[c]);
    }
    sprintf(chks, "%02X", n_chks);
}

Javascript:

function getChecksum(packet)
{
   // Compute the checksum by XORing all the character values in the string.
   var checksum = 0;
   for(var i = 0; i < packet.length; i++) {
      checksum = checksum ^ packet.charCodeAt(i);
   }
}

Online calculator

Serial command sent from the high level stack to the real time system. For every non-polling input command the stm32 will answer with an acknowledgment packet.

We describe every command with a table, if the CMD field is bold that means that the field is mandatory, if it isn't then it's an optional field.

Check the Kitra-COM introduction to see how to handle optional field.

Change baud rate. Mcu will change it after it sent the acknoledgement. Default baud rate at startup is 115200, changes are not retained.

Max allowed baud rate is 1Mbps.

Sends mcu in fw upgrade phase (115200 bps).

Get kitra520 statuses, for example battery status.

Resets the Kitra520 board. This command also reboots Artik without any power off sequence, it can be dangerous for the file system. Before sending this command you must put Artik in a secure state.

Only from firmware V1

Sends Kitra520 to deep sleep mode. Kitra520 will go to an unreachable state, allowing very low power consuption. Useful if you need Kitra520 only to power Artik.

option not yet used.

Enable or disable input pin by hardware. The kitra520 board has 5 input pins, the first 4 are the DI on the external connector (see schematics), the 5th is the power-button. If pressed for less then 4 seconds it can be used as user button. Disabling a pin cause loss of its configurations.

Read state input pin.

If configuration_target is notification and enabled is true, mcu will send a packet as soon as the pin change its state. A sampling time of 0 means that state will change as soon as it is detected. Active_state field is applied to both targets. Not bold fields are optional.

filter_activation can be between 0 and 4095.

Enable or disable analog pin by hardware. Disabling a pin cause loss of his configurations.

Change operating mode of the analog input pin. Resetting the value will clear current value.

average can be any any power of two till 1024.

Note: If you enable notifications with a high sampling_time, you need a high baud rate.

Read last analog input sample, data is with average. Mcu will send a response with a value between 0 and 65536 proportional to the voltage level.

Configure notification for new packet and threshold interrupt of the analog pin (they are two different notifications).

Enable or disable output pin by hardware. Disabling a pin cause loss of its configurations.

Read state input pin.

Configure pwm duty cycle. Configuring a pin while pwm is on cause a stop.

frequency can be between 1Hz and 1Mhz.

Set autostart to 1 if you want the pwm to start after the command.

After configuring the PWM you must start it with the change mode command. Stop and pause command bring the output LOW, stop cause loss of configurations.

Enable or disable touch button. Disabling a pin cause loss of its configurations.

sensivity can be between 0 (most sensitive) and 255 (less sensitive).

Read touch state,no threshold or filter is applied.

By default all notifications are disabled.

threshold_level_press can be between 0 and 4095.

frequency must be multiple of 8. Internal frequency used by the sensor to read keys.

High ms reduce power consuption. 0 means off.

Enable or disable haptic. Disabling cause loss of its configurations.

Using managed mode a buil-in effect will be performed. Percetange isn’t used if managed mode is true.

Effect_number isn’t used if managed mode is false.

percetange is mandatory if managed is disbled. effect_number is mandatory if managed is enabled. Can be between 1 and 127. Check drv2605 datasheet for informations about each effect.

After configuring haptic you must start it with the change mode command.

Kitra520 board embeds two proximity sensors:

• VL53L0X (pin 1): Proximity sensor for long dinstance measurement. Up to 2 meters on appropriate enviroment condition.
• VL6180X (pin 2): Proximity sensor for short distance measurement and light. This sensor is also used with enviroment commands when reading light.

Disabling cause loss of its configurations.

V0 Note: they are automatically disabled if microphone is active.

Read lux intensity request, measured in lx.

Working only for pin 1.

Read proximity, measured in mm.

Disabling lux or prox will grant better performance on the proximity measurement.

On pin 1:

On pin 2:

V0 Note: Remember that if you disable lux here you won’t be able to read its value with the enviroment command.

Notification regarding samples, not managed. Notification provide values for both lux and proximity. Not bold fields are optional.

Enabling managed notification the mcu will send a notification when a common gesture is recognized. To have a good performance we recommend to disable the lux sensor (through the configure command). Note that this command will change internal average of the sensor. VL53L0X will be put in HIGH_SPEED mode and VL6180X in 200mm mode. Disabling will restore the previous modes.

V0 Note: not avaiable for this firmware version

Each command has a pin field pointing to which led the command must be applied.

It is also possible to indicate a combination on led using a bit mask, each bit of the pin field is a led. To prevent conflict with the previous pin values you must set the 7th bit of the field to 1.

Only from firmware V1

Enable or disable rgb pin by hardware.

A pin value 0 means all leds.

Set color and intensity of a RGB LEG.

A pin value 0 means all leds.

Only from firmware V1

After each loop, a timeout of loop_delay is applied.

REDIRECT is like START but keeps current leds state if they are handling another transition.

Enable or disable IMU sensors.

Toggling the enable will cause the magnetometer calibration to be reset.

Request read of X,Y,Z of accellerometer and magnetometer, and dps (degree per second) of gyroscope.

Filter mask let you dedice what value receive, other fields of the response will be left empty. Every bit correspond to a field of the response, ordered as shown in the read raw response.

Request read of roll, pinch, yaw parameters. Values and not raw but filtered and calculated over all sensors.

Filter mask let you dedice to what raw value the enable field is applied, disabled fields on the response will be left empty. Filter mask is applied only during enable, during disable all notifications are removed. Every bit correspond to a field of the response, ordered as shown in the read raw response.

sampling_frequency can be between 1 and 100.

Every bit of the notification mask corresponds to a managed notification. Every notification is enabled or disabled according to the bits.

The first 2 bits of the full scale fields indicate the full scale of the accellerometer, the bits 2-3 indicate the full scale of the gyroscope.

Example: 0x05 (acc 4g and gyro 500dps)

V0 Note: gyro full scale is fixed for this firmware version.

You shouldn't use euler notifications with a custom full scale combination.

Yaw needs to be calibrated rotating the device in a 8 figure.

Reads pedometer step counter.

Enable or disable sensors.

Filter_mask tells what sensors to apply enable or disable. Each bit correspond to a sensors, ordered as: PRESSURE/TEMPERATURE/HUMIDITY/LUX Not bold fields are optional.

Read sensor value or values. Values aren't raw.

Enable notification or threshold notification for a certain sensor.

notification_freq is global.

Sampling and Beamforming supported only from version V1E2.

Enable disable microphones.

mic_out_sel_1_2 is mandatory for sampling or beamforming. Defines stereo or mono streaming by checking the first 4 bits and the last 4 bits to identifiy the two microphone we want to record. A zero value means no microphone (can be used for mono streaming).

Ex. 0x14 for first and third microphones.

bf_alg_type and bf_gain are mandatory for beamforming.

Note: Beamforming and Sampling require very high baud rate, suggested speed is 1Mbit.

Localization mode must be enabled.

Supported from firmware V1E2.

Note: To drive more then one led use an external supply.

A pin value of 0 means all leds.

Use this command to apply multiple set commands in a single shot.

toggle_ms toggles the buzzer each time the duration exprires, if you do not need this feature do not send the parameter or buzzer won't start.

Read/Write to the I2C bus via Kitra-COM. You can read/write up to 4 bytes.

Not bold fields for 16bit address must be left as optional or the command won't work.

Not bold fields are optional.

size can be between 1 to 4.

Not bold fields for 16bit address must be left as optional or the command won't work.

Command sent from the real time system to the high level stack. All the response command follow a master-slave relation (mcu is the slave) but power up, error and notification are async.

We describe every command with a table, if the CMD field is bold that means that the field is mandatory, if it isn't then it's an optional field.

Check the Kitra-COM introduction to see how to handle optional field.

Message sent by the mcu at powerup.

Message sent as response to a non-polling command.

ref_id is the id corresponding to the command the ack is referring to.

Message sent when something wrong happends, it can be relative to a certain request or not.

Firmware version start from 0.

The extra field is a 16bit value used to hold subversion information and manufacturer data for custom firmwares.

The official Kitra-COM firmware has 0 as firmware identification.

Note Bootloader from V1 (bootloader firmware, KitraIAP_VX.bin) answer to this command too with a fixed extra value of 0xFFFF.

battery_mv is the battery voltage, with the provided battery you should read between 3400mV and 4300mV.

Under 3400mV the kitra520 board should be turned off.

Read state input pin.

Report state change if notification is enable.

Mcu will send a response with a value between 0 and 4095 proportional to the voltage level.

This message is sent if the threshold is reached and the threshold notification is enabled.

By default all notifications are disabled.

Read lux intensity requst, misured in lx.

Read proximity, measured in mm.

Left and right swipe notification.

Send X,Y,Z and angle parameters.

Send roll, pinch, yaw parameters. Filtered and calculated over all sensors.

Values sent depend of the filter mask configuration in the request. By default all are sent.

Values not raw but filtered and calculated over both sensors.

At least one of the three field required. Not bold are optional.

extra field contains the step counter value if a step notification is being received.

Yaw (heading) needs to be calibrated rotating the device in a 8 figure.

Send pedometer cumulative step counter.

Read sensors values (not raw).

Only values of sensors with notification enabled are sent.

Tells the angle that received louder sounds.

Tells the angle that received louder sounds.

Read/Write to the I2C bus via Kitra-COM. You can read/write up to 4 bytes.