Chapter 4 Core Tools
SDK core tools play an important role in the BLE device development.
ingWizard is the recommended entry point in the whole development life cycle. With it,
we can create & open project, edit project data, and migrate projects,
ingWizard’s new project wizard assists the creation of new projects. We can select favourate IDE, peripheral role, edit advertising and profile data, enable FOTA and logging, etc.
Once a project is created, following files are also created, used by
ingWizardbut not IDE, and they shoule not be deleted, or
ingWizardwill not to function properly:
This file shares the same name with the project with an extension
.ingw. It contains crucial information about the project and SDK. Without this information, it becomes impossible to do migration.
Advertising Data Editor
This editor helps us to generate advertising data. It can also be opened from main menu
Advertising Data Editor ....
GATT Profile Editor (or GATT/ATT Database Editor)
This editor helps us to build GATT profile data. It can also be opened from main menu
Profile Database Editor ....
This editor supports three type of services, SIG defined services, INGChips defined services and user defined services. To add an user defined service, it must be create beforehandle (see below).
Manage Custom Services
This editor can be opened from main menu
Manage Custom GATT Services .... We can add, delete and edit custom services.
Custom Services and characteristics are all named with a prefix which is deduced from company name initialized when installing SDK, and updatable through
In case a new version of SDK is installed, ROM and RAM used by platform might be changed, so projects settings need to be updated accordingly. This process is automated by right click on a project and select
Check & Fix Settings ....
Alway remember to backup your project before perform a migration, either by committing all changes into version control system or making a full backup.
This downloader downloads up-to six images (binaries) to flash through UART connection. It co-operate with bootloader. Bootloader can be made into flash downloading mode either by:
Asserting boot pin (this is used in the vast majority of cases),
Setting entry point which is stored Flash to an invalid address.
When 918xx is powered on, bootloader checks above conditions. If any conditions are true, bootloader sends the handshaking message.
User can download any files, although typically these files are generated by IDE tools.
The load address of image (binary) must be aligned at flash page boundary. Each flash page
0x2000) bytes. Flash starts from
0x4000, so the load address should be
0x4000 + X * 0x2000, where
X is an integer. Downloader complains if the load
address is not correct. Note that when this downloader is started from
binaries have already been correctly configured.
Setup UART ... to configure UART (Figure 4.1).
Users need to set
Port Number to the value shown in Windows Device Manager, for example,
if “COM9” is used, then set
Port Number to
COM9, or simply
Baud rate can be set to a value larger than
115200, such as
to achieve a faster download speed.
The maximum supported baud rate is
921600. Due to the limitation of internal flash characters,
there isn’t any further significant improvement for baud rate larger than
Other fields should be left unchanged.
The whole downloading procedure is composed of several steps, such as downloading, verification,
set entry address, and launching app. These steps can be configured by clicking
0x4000 equals to the load address of platform binary. If “Verify Download” is
enabled, then data will be read back and compare with origin file to ensure data is correctly
downloaded. Data blocks are CRC checked, so “Verify Download” can be kept disabled
on a regular basis.
If downloading keeps failing on specific address, then we can enable it to double check if flash
is malfunctional. In this case, when mismatch is found, read-back data will be stored to a file.
When “Batch” mode is enabled, downloader will keep waiting for bootloader handshaking, and once received handshaking, downloading starts; after downloading completes, downloader will start waiting again. When “Batch” mode is disabled, downloader will no longer wait for handshaking after downloading completes.
Start to start downloading, or rather start waiting for handshaking. Bootloader sends
handshaking message only once, and if chips are already powered up, it may be too late to
receive handshaking. In this case, we can click
Force to skip handshaking and start downloading
4.2.2 Scripting & Mass Production
This downloader supports powerful scripting, making it suitable for mass production. In the script, two event handlers (functions) are required to be defined.
This event handler gets called when each round of downloading starts;
This event handler gets called when a binary starts downloading. Here, binary data can be modified on-the-fly before it is written into flash.
When “Batch” mode is enabled, this downloader keeps a counter which is increased by
1 after downloading
finishes. This counter is shown as
Counter.Current shown in Figure 4.2. There is
also a variable called
Counter.Limit. In “Batch” mode, before a new round of downloading starts,
Counter.Current is checked against this limit, if it is larger than limit, “Batch” mode stops automatically.
For example, if
Counter.Limit are set to
13 respectively, then “Batch” mode will
4 rounds in total, with
Counter.Current equals to
13. After “Batch” mode stops,
Counter.Current equals to
The language used for scripting is RemObjects Pascal Script13,
which is quite similar to
C, and easy to develop. Below is an simple but working example, in which, the
batch round number (
BatchCounter) is written to a fixed location in the binary.
// we can use constants const BD_ADDR_ADDR = $1; // BatchCounter is just Counter.Current procedure OnStartRun(const BatchCounter: Integer; var Abort: Boolean); begin // Use *Print* for logging and debugging Print('OnStartRun %d', [BatchCounter]); // we can abort downloading by assigning True to *Abort* // Abort := True; end; procedure OnStartBin(const BatchCounter, BinIndex: Integer; var Data: TBytes; var Abort: Boolean); begin // Note that BinIndex counts from 1 (not 0), just as shown on GUI if BinIndex <> 2 then Exit; // We can modify binary data before it is downloaded into flash Data[BD_ADDR_ADDR + 0] := BatchCounter and $FF; Data[BD_ADDR_ADDR + 1] := (BatchCounter shr 8) and $FF; Data[BD_ADDR_ADDR + 2] := (BatchCounter shr 8) and $FF; end;
4.2.3 Flash Read Protection
To protect illegal access of data & program stored in flash, 918xx has a read-protection mechanism. Once read-protection is enabled, JTAG/SW and this downloader can not be able to access flash any more. To re-enable JTAG/SW debugging functionality and downloading, the read-protection must be turned off by a procedure called unlock. Flash data is erased in this procedure.
Once the app is ready to ship, and it is decided that data & program must be protected
from illegal access, just enable “Read Protection” as shown in Figure 4.2. To download program into a read protected, check
Unlock Before Download option. As flash data is erased during unlocking, do not
forget to re-download
All configurations are stored in an ini file.
4.2.4 Python Version
SDK also provides a Python version downloader (icsdw.py). It’s open source and easy to be integrated with other tools.
This version is written in Python 3. It uses
package to access serial port,
so run “
pip install pyserial” to install the package.
Python downloader shares the same ini file with only one exception: Scripting. The GUI downloader stores RemObjects Pascal source code with key named “script” in section “options”, while the python version stores the path to a user module. The path can be a full path or a relative path (relative to the location of the ini file).
In the user module,
two methods are required to be defined to handle events as in the GUI downloader,
on_start_bin. Below is an example, in which, the
batch round number (
batch_counter) is written to a fixed location in #2 binary.
# return abort_flag def on_start_run(batch_counter: int): return False # return abort_flag, new_data def on_start_bin(batch_counter: int, bin_index: int, data: bytes): if bin_index != 2: return False, data ba = bytearray(data) addr = batch_counter.to_bytes(4, 'little') ba[1:5] = addr return False, bytes(ba)
ingTracer is the visual tool for inspecting recorded Trace data introduced in
Debugging & Tracing.
To limit items drawn on screen,
ingTracer breaks trace data into frames. Each frame has
a length of 5sec. When a frame is selected, besides the current frame, the previous and the
next one are also shown for continuity.
Graph shows all trace data visually. By clicking an item in Graph,
detailed information is decoded
and shown in Message Decoder and Message Hex Viewer. Graph supports some of
CAD operations, such as zooming, panning, measuring, etc. Checkout menu
detailed information. (Figure 4.3)
To help analyzing app & high layer issues,
ingTrace can generate MSC (message sequence
each connection. While Graph emphasizes on timing between events, MSC emphasizes on
procedure and fits better for protocol analysis. Message can be decoded by clicking on
[+] mark (Figure 4.4).