GS2K Module Programming and Protocol Reference Rev 1

GS2K Module Programming and Protocol Reference Guide
GS2K Module Programming and Protocol

Reference Guide
1VV0301447 Rev. 1 – 2015-05-05
SPECIFICATIONS ARE SUBJECT TO CHANGE WITHOUT NOTICE
NOTICE
While reasonable efforts have been made to assure the accuracy of this document, Telit
assumes no liability resulting from any inaccuracies or omissions in this document, or from
use of the information obtained herein. The information in this document has been carefully
checked and is believed to be reliable. However, no responsibility is assumed for
inaccuracies or omissions. Telit reserves the right to make changes to any products described
herein and reserves the right to revise this document and to make changes from time to time
in content hereof with no obligation to notify any person of revisions or changes. Telit does not
assume any liability arising out of the application or use of any product, software, or circuit
described herein; neither does it convey license under its patent rights or the rights of others.
It is possible that this publication may contain references to, or information about Telit
products (machines and programs), programming, or services that are not announced in your
country. Such references or information must not be construed to mean that Telit intends to
announce such Telit products, programming, or services in your country.
COPYRIGHTS
This instruction manual and the Telit products described in this instruction manual may be,
include or describe copyrighted Telit material, such as computer programs stored in
semiconductor memories or other media. Laws in the Italy and other countries preserve for
Telit and its licensors certain exclusive rights for copyrighted material, including the exclusive
right to copy, reproduce in any form, distribute and make derivative works of the copyrighted
material. Accordingly, any copyrighted material of Telit and its licensors contained herein or in
the Telit products described in this instruction manual may not be copied, reproduced,
distributed, merged or modified in any manner without the express written permission of Telit.
Furthermore, the purchase of Telit products shall not be deemed to grant either directly or by
implication, estoppel, or otherwise, any license under the copyrights, patents or patent
applications of Telit, as arises by operation of law in the sale of a product.
COMPUTER SOFTWARE COPYRIGHTS

The Telit and 3rd Party supplied Software (SW) products described in this instruction manual
may include copyrighted Telit and other 3rd Party supplied computer programs stored in
semiconductor memories or other media. Laws in the Italy and other countries preserve for
Telit and other 3rd Party supplied SW certain exclusive rights for copyrighted computer pro-
grams, including the exclusive right to copy or reproduce in any form the copyrighted com-
puter program. Accordingly, any copyrighted Telit or other 3rd Party supplied SW computer
programs contained in the Telit products described in this instruction manual may not be cop-
ied (reverse engineered) or reproduced in any manner without the express written permission
of Telit or the 3rd Party SW supplier. Furthermore, the purchase of Telit products shall not be
deemed to grant either directly or by implication, estoppel, or otherwise, any license under the
copyrights, patents or patent applications of Telit or other 3rd Party supplied SW, except for
the normal non-exclusive, royalty free license to use that arises by operation of law in the sale
of a product.
USAGE AND DISCLOSURE RESTRICTIONS
I. License Agreements
The software described in this document is the property of Telit and its licensors. It is
furnished by express license agreement only and may be used only in accordance with the
terms of such an agreement.
II. Copyrighted Materials
Software and documentation are copyrighted materials. Making unauthorized copies is
prohibited by law. No part of the software or documentation may be reproduced, transmitted,
transcribed, stored in a retrieval system, or translated into any language or computer
language, in any form or by any means, without prior written permission of Telit
III. High Risk Materials
Components, units, or third-party products used in the product described herein are NOT
fault-tolerant and are NOT designed, manufactured, or intended for use as on-line control
equipment in the following hazardous environments requiring fail-safe controls: the operation
of Nuclear Facilities, Aircraft Navigation or Aircraft Communication Systems, Air Traffic
Control, Life Support, or Weapons Systems (High Risk Activities"). Telit and its supplier(s)
specifically disclaim any expressed or implied warranty of fitness for such High Risk Activities.
IV. Trademarks
TELIT and the Stylized T Logo are registered in Trademark Office. All other product or service
names are the property of their respective owners.
V. Third Party Rights
The software may include Third Party Right software. In this case you agree to comply with all
terms and conditions imposed on you in respect of such separate software. In addition to
Third Party Terms, the disclaimer of warranty and limitation of liability provisions in this
License shall apply to the Third Party Right software.
TELIT HEREBY DISCLAIMS ANY AND ALL WARRANTIES EXPRESS OR IMPLIED FROM
ANY THIRD PARTIES REGARDING ANY SEPARATE FILES, ANY THIRD PARTY
MATERIALS INCLUDED IN THE SOFTWARE, ANY THIRD PARTY MATERIALS FROM
WHICH THE SOFTWARE IS DERIVED (COLLECTIVELY “OTHER CODE”), AND THE USE
OF ANY OR ALL THE OTHER CODE IN CONNECTION WITH THE SOFTWARE,
INCLUDING (WITHOUT LIMITATION) ANY WARRANTIES OF SATISFACTORY QUALITY
OR FITNESS FOR A PARTICULAR PURPOSE.
NO THIRD PARTY LICENSORS OF OTHER CODE SHALL HAVE ANY LIABILITY FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED
AND WHETHER MADE UNDER CONTRACT, TORT OR OTHER LEGAL THEORY,
ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE OTHER CODE OR
THE EXERCISE OF ANY RIGHTS GRANTED UNDER EITHER OR BOTH THIS LICENSE
AND THE LEGAL TERMS APPLICABLE TO ANY SEPARATE FILES, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES.
APPLICABILITY TABLE
PRODUCT
GS2K based Modules
Note: The features described in the present document are provided by the products equipped
with the software versions equal or higher than the versions shown in the table. See also
the Revision History chapter.
Table of Contents
Chapter 1 Programming the GS2000 Based Modules .................................................................... 19

1.1 Programming Mode ...............................................................................................................19
1.2 GS2000 Boot Procedure .......................................................................................................23
1.2.1 GS2000 Boot ROM Flow in Program Mode .................................................................24
1.3 Host Interface Overview ........................................................................................................25
1.3.1 HI Frame Format ..........................................................................................................25
Chapter 2 Download Class Messages ............................................................................................. 27

2.1 Download Request ................................................................................................................28
2.2 Copy Request ........................................................................................................................29
2.3 Error Indication ......................................................................................................................30
2.4 Ack (Acknowledgment) ..........................................................................................................31
2.5 Transferring Binary ................................................................................................................32
Chapter 3 ROM Debug Class Messages ......................................................................................... 35

3.1 RegPeek ................................................................................................................................36
3.2 RegPoke ................................................................................................................................37
3.3 MemRead ..............................................................................................................................38
3.4 MemWrite ..............................................................................................................................39
3.5 FlashRead .............................................................................................................................40
3.6 FlashErase ............................................................................................................................41
3.7 FlashEraseCheck ..................................................................................................................42
3.8 FlashCheckSum ....................................................................................................................43
3.9 Execute at Address ...............................................................................................................44
3.10 WLAN Start ..........................................................................................................................45
3.11 WLAN Stop ..........................................................................................................................46
Chapter 4 Memory Map and File System Structure ......................................................................... 47

4.1 Flash Structure ......................................................................................................................48
4.1.1 Super Block Structure ..................................................................................................49
4.1.2 Boot ROM Super Block ................................................................................................50
4.1.3 Boot APP Super Block .................................................................................................51
4.1.4 Boot Application ...........................................................................................................52
4.1.5 Backup of Control Block for Boot Application ...............................................................52
4.2 Firmware Block ......................................................................................................................53
4.2.1 Control Block ................................................................................................................54
4.2.2 Application Firmware ....................................................................................................56
4.2.3 WLAN Firmware ...........................................................................................................56
4.2.4 Static File System ........................................................................................................56
4.2.5 Backup of Control Block ...............................................................................................56
4.3 In-Module Flash File System .................................................................................................57
4.3.1 Static File System ........................................................................................................57
4.3.2 Dynamic File System ...................................................................................................58
Chapter 5 Programming Binaries .................................................................................................... 59

5.1 Programming the Binaries .....................................................................................................59
5.2 Programming At One Location ..............................................................................................64
5.3 Programming At Multiple Locations .......................................................................................64
1VV0301447 Rev 1.0 5 of 77 2015-05-05

Appendix A Opcodes .......................................................................................................... 65

Appendix B Firmware Model .............................................................................................. 67
B.1 Memory Map for 5.1.x Releases ...........................................................................................67
B.2 Memory Map for 5.2.x Releases ...........................................................................................72
1VV0301447 Rev 1.0 6 of 77 2015-05-05

About This Manual
This manual provides information required to program the GainSpan® GS2000 based
modules using host interfaces like UART and SPI through individual commands, formats,
and protocols. It describes memory map and file systems used to control how data is
tracked, organized, stored and retrieved during different types of operations.
Refer to the following sections:
• Revision History, page 8
• Audience, page 8
• Standards, page 8
• Documentation Conventions, page 9
• Documentation, page 12
• References, page 14
• Contact Information, Support, page 16
• Returning Products to GainSpan, page 17
• Accessing the GainSpan Portal, page 18
1VV0301447 Rev 1.0 7 of 77 2015-05-05

Revision History
This version of the GainSpan GS2000 Based Module Programming and Protocol
Reference Guide contains the following new information listed in Table 1, page 8.
Table 1 Revision History
Version Date Remarks

1.0 May 2015 Initial Release
Audience
This manual is designed for software engineers who want to know how to program the
on-board Flash and describes the software and host interfaces, memory map file structure
of the GS2000 based module commands, and steps for programming binaries and firmware.
It is also intended for users of boot ROM commands who want to know the available
commands and formats.
Standards
The GainSpan GS module series supports the IEEE 802.11 b/g/n standards.
1VV0301447 Rev 1.0 8 of 77 2015-05-05

Documentation Conventions
This manual uses the following text and syntax conventions:
– Special text fonts represent particular commands, keywords, variables, or window
sessions
– Color text indicates cross-reference hyper links to supplemental information
– Command notation indicates commands, subcommands, or command elements
Table 2, page 9, describes the text conventions used in this manual for software procedures
that are explained using the AT command line interface.
Table 2 Document Text Conventions
Convention Type Description

This monospaced font represents command strings entered on a
command syntax command line and sample source code.
monospaced font
AT XXXX
Proportional font Gives specific details about a parameter.

description <Data> DATA
UPPERCASE Indicates user input. Enter a value according to the descriptions that
follow. Each uppercased token expands into one or more other token.
Variable parameter
lowercase Indicates keywords. Enter values exactly as shown in the command

description.
Keyword parameter
Enclose optional parameters. Choose none; or select one or more an

[] unlimited number of times each. Do not enter brackets as part of any
command.
Square brackets
[parm1|parm2|parm3]
? Used with the square brackets to limit the immediately following token
Question mark to one occurrence.
Each escape sequence <ESC> starts with the ASCII character 27 (0x1B).
<ESC> This is equivalent to the Escape key.
Escape sequence
<ESC>C
<CR>
Each command is terminated by a carriage return.
Carriage return
<LF>
Each command is terminated by a line feed.
Line feed
1VV0301447 Rev 1.0 9 of 77 2015-05-05

Table 2 Document Text Conventions (Continued)
Convention Type Description

<CR> <LF>
Each response is started with a carriage return and line feed with some
Carriage return
exceptions.
Line feed
Enclose a numeric range, endpoints inclusive. Do not enter angle
<> brackets as part of any command.
Angle brackets
<SSID>
Separates the variable from explanatory text. Is entered as part of the
= command.
Equal sign
PROCESSID = <CID>
Allows the repetition of the element that immediately follows it multiple
. times. Do not enter as part of the command.
dot (period)
.AA:NN can be expanded to 1:01 1:02 1:03.
A.B.C.D IPv4-style address.

IP address 10.0.11.123
IPv6-style address.
X:X::X:X
3ffe:506::1
IPv6 IP address Where the : : represents all 0x for those address components not
explicitly given.
Indicates user input of any string, including spaces. No other parameters
LINE may be entered after input for this token.
End-to-line input token
string of words
WORD Indicates user input of any contiguous string (excluding spaces).

Single token singlewordnospaces
1VV0301447 Rev 1.0 10 of 77 2015-05-05

Table 3, page 11, describes the symbol conventions used in this manual for notification and
important instructions.
Table 3 Symbol Conventions
Icon Type Description

Provides helpful suggestions needed in understanding
Note a feature or references to material not available in the
manual.
Alerts you of potential damage to a program, device,

Alert
or system or the loss of data or service.
Cautions you about a situation that could result in

Caution
minor or moderate bodily injury if not avoided.
Warns you of a potential situation that could result in

Warning
death or serious bodily injury if not avoided.
Electro-Static Discharge Notifies you to take proper grounding precautions

(ESD) before handling a product.
1VV0301447 Rev 1.0 11 of 77 2015-05-05

Documentation
The GainSpan documentation suite listed in Table 4, page 12 includes the part number,
documentation name, and a description of the document. The documents are available on
the GainSpan Portal. Refer to , page 17 for details.
Table 4 Documentation List
Part Number Document Title Description
Provides users steps to program the
on-board Flash utilizing either UART
or SPI interface for the GainSpan
GS2000 based modules using DOS or
1VV0301435 GS2K Module Evaluation Board Hardware User Guide
Graphical User Interface utility
provided by GainSpan. The user guide
uses the evaluation boards as a
reference example board.
GS2011M S2W Adapter Command Reference Guide Provides a complete listing of AT serial
GS2100M S2W Adapter Command Reference Guide commands, including configuration
1VV0301463 examples for initiating, maintaining,
GS2101M S2W Adapter Command Reference Guide and evaluating GainSpan WiFi
GS2200M S2W Adapter Command Reference Guide GainSpan series modules.
1VV0301447 Rev 1.0 12 of 77 2015-05-05

Documentation Feedback
We encourage you to provide feedback, comments, and suggestions so that we can improve
the documentation. You can send your comments by logging into Telit Support Portal. If
you are using e-mail, be sure to include the following information with your comments:
– Document name
– URL or page number
– Hardware release version (if applicable)
– Software release version (if applicable)
1VV0301447 Rev 1.0 13 of 77 2015-05-05

References
The GainSpan references listed in Table 5, page 14 are available on the GainSpan Portal.
Refer to , page 17 for details.
Table 5 Other Documents and References

Title Description
GS2000 Based Module Evaluation Board schematics
supporting:
• GS2011M
Schematics • GS2100M
• GS2101M
• GS2200M
• GS2200M SKB
• Smart Phone applications for iOS and Android to
evaluate and demonstrate the Temperature and
Light Sensor (TLS) firmware.
– For use with GS2011M EVK and GS2200
EVB and SKB only
• Android:
– GainSpan Provisioning
– GainSpan Firmware Update
– GainSpan Smartplug
– GainSpan TLS
Smart Phone Applications – Concurrent Provisioning
• iOS:
– GainSpan TLS
– GainSpan Provisioning
– GainSpan-Renesas Wi-Fi Sensor
– GainSpan ConcurrentProvisioning
– GainSpan Freescale Wi- Fi Sensor
– GainSpan Audio
– GainSpan Smartplug
– GainSpan Firmware Update
Serial terminal program to evaluate and demonstrate
Tools and Utilities Serial-to-Wi-Fi (S2W) applications such as
– gs2k_flashprogram.exe
1VV0301447 Rev 1.0 14 of 77 2015-05-05

1VV0301447 Rev 1.0 15 of 77 2015-05-05

Contact Information, Support

For general contact, technical support services, technical questions and to report
documentation errors contact Telit Technical Support at:
[email protected]
We recommend adding “Wi-Fi” in subject of the email. For example, the subject of email
can be “Wi-Fi: Your actual issue or question in brief” like “Wi-Fi: SPI Driver Issue”.
Also, in description of your email, please provide details about the issue, product and
module including software firmware version, module version and type, application being
used, customizations done to application, use case, issue frequency, and ability to recreate
it among other things wherever applicable.
Alternatively, for more Technical Support information or assistance, perform the following
steps:
1. Visit http://www.telit.com, go to Products> Wi-Fi and Blue-tooth, then scroll down to
the Telit Wi- Fi Portal.
2. Click Access the Portal Here icon which will direct you to the GainSpan portal
http://www.gainspan/secure/login.com
1. Log in with your customer Email and Password.
2. Select the Location.
3. Select Q&A tab.
4. Select Ask a New Question.
5. Enter your technical support question, product information, and a brief description.
For detailed information about where you can buy the Telit modules or for
recommendations on accessories and components visit:
http://www.telit.com
Our aim is to make this guide as helpful as possible. Keep us informed of your comments
and suggestions for improvements. Telit appreciates feedback from the users of our
information.
1VV0301447 Rev 1.0 16 of 77 2015-05-05

Returning Products to GainSpan

If a problem cannot be resolved by GainSpan technical support, a Return Material
Authorization (RMA) is issued. This number is used to track the returned material at the
factory and to return repaired or new components to the customer as needed.
NOTE: Do not return any components to GainSpan Corporation unless you have
first obtained an RMA number. GainSpan reserves the right to refuse shipments
that do not have an RMA. Refused shipments will be returned to the customer by
collect freight.
To return a hardware component:

1. Determine the part number and serial number of the component.
2. Obtain an RMA number from Sales/Distributor Representative.
3. Provide the following information in an e-mail or during the telephone call:
– Part number and serial number of component
– Your name, organization name, telephone number, and fax number
– Description of the failure
4. The support representative validates your request and issues an RMA number for
return of the components.
5. Pack the component for shipment.
Guidelines for Packing Components for Shipment

To pack and ship individual components:
– When you return components, make sure they are adequately protected with
packing materials and packed so that the pieces are prevented from moving
around inside the carton.
– Use the original shipping materials if they are available.
– Place individual components in electrostatic bags.
– Write the RMA number on the exterior of the box to ensure proper tracking.
CAUTION! Do not stack any of the components.
1VV0301447 Rev 1.0 17 of 77 2015-05-05

Accessing the GainSpan Portal

To find the latest version of GainSpan documentation supporting the GainSpan product
release you are interested in, you can search the GainSpan Portal website by performing the
following steps:
NOTE: You must first contact GainSpan to set up an account, and obtain a
customer user name and password before you can access the GainSpan Portal.
1. Visit http://www.telit.com, go to Products> Wi-Fi and Blue-tooth, then scroll down

the Telit Wi- Fi Portal.
2. Click Access the Portal Here icon which will direct you to the GainSpan portal
http://www.gainspan/secure/login.com
3. Log in using your customer Email and Password.
4. Click the Getting Started tab to view a Quick Start tutorial on how to use various
features within the GainSpan Portal.
5. Click the Agreements tab to download and upload the SLA for ADK and SDK
respectively.
6. Click on the Documents tab to search, download, and print GainSpan product
documentation.
7. Click the Software tab to search and download the latest software versions.
8. Click the Kits Purchased tab to view customer account history.
9. Click the Legal Documents tab to view GainSpan Non-Disclosure Agreement
(NDA).
10. Click the Certifications tab to view GainSpan certifications.
1VV0301447 Rev 1.0 18 of 77 2015-05-05

GS2K Module Programmiing and Protocol Reference Guide
Chapter 1 Programming the GS2000 Based Modules
This chapter provides information about programming the GS2000 based modules and
describes the procedure to transfer binaries into the modules. It is assumed that the reader
is generally familiar with GainSpan® SoC products, Internet Protocol (IP) networks and
the operation and management of 802.11 wireless devices.
• Programming Mode, page 19
• GS2000 Boot ROM Flow in Program Mode, page 24
• Host Interface Overview, page 25
1.1 Programming Mode

The GS2000 based modules consist of the GS2000 SoC and a Flash. The firmware is
programmed on the Flash through the GS2000 SoC. This Flash can be programmed through
UART or SPI interface using the Host Interface (HI) protocols described in 1.3 Host
Interface Overview, page 25.
For programming the Flash, the GS2000 SoC should be configured for Program mode. The
following describe the key components of the GS2000 system.
• Two CPUs: WLAN CPU and APP CPU where APP CPU is the main CPU that
runs first after power up and boots from its internal boot ROM.
• Code in the boot ROM: It first checks if a firmware download is requested. This
is achieved by putting the module in program mode. To put the module in
program mode, pull up the GPIO27 (GS2011M) or GPIO31 (GS2100M) high and
then reset or power cycle the module. In Program Mode, GPIO33 will be driven
high very briefly. At reset release, the following pins are sampled.
– GPIO27 (on GS2011M) or GPIO31 (on GS2100M) is the “Program Mode”
pin. Value 1 sets Program Mode. Value 0 sets Run Mode.
– GPIO25 is the “Program Select/Previous Restore” pin. Function depends on
Program Mode pin. Selects 921K baud in Program Mode. Selects Previous
Restore in Run Mode.
– GPIO21 is the “Alternate Previous Restore” pin.
1VV0301447 Rev 1.0 19 of 77 2015-05-05

Table 6, page 20 describes the boot control pin functions for the GS2000 based module.
Table 6 Boot Control Pin Functions

Program Program Alternate Boot Control Function
Mode Select/Previous Previous
GPIO27 or Restore Restore
GPIO31 GPIO25 GPIO21
(GS2011M
only)
0 0 0 Normal boot
Previous Code Restore. Restores prior
code revision by invalidating the present
code image. Will NOT invalidate the last
0 0 1 remaining image. Note: below that
GPIO21 and GPIO25 MUST NOT both
be high at reset release in Run mode
(GPIO27=0).
Previous Code Restore. Restores the
prior code revision by invalidating the
0 1 0
present code image. Will NOT invalidate
the last remaining image.
Invalid. DO NOT USE THIS BOOT
CONTROL STATE. This boot control
0 1 1
state can invalidate the last remaining
code image.
Program Mode with: UART0 @ 115.2K
1 0 X baud; nothing on GPIO15-18; SPI0 on
SDIO pins.
Program Mode using: UART0 @ 921.6K
baud; SPI0 on GPIO15-18. Note: that
1 1 X
GPIO15-18 are only available on
GS2000 SoC, and not on the modules.
NOTE: Both GPIO25 and GPIO21 MUST NOT be high in Run Mode at reset
release.
NOTE: GPIO27 (or GPIO31), GPIO25, and GPIO21 should ONLY be used as
outputs, and should not be used as inputs.
NOTE: In Run Mode, Boot ROM leaves all GPIO pins as input with pull resistor
enabled until flash code sets them.
1VV0301447 Rev 1.0 20 of 77 2015-05-05

NOTE: In Program Mode, only the pins required for the Program Mode specified
interfaces are set to non-gpio mode.
• UART0 Interface: It is used to program the module flash and it runs with the
following settings:
Baud rate: 115200/921600 bps
Data: 8 bits
Parity: None
Stop: 1 bit
Flow control: None
NOTE: GPIO25 should be pulled up high for 921K.
Figure 1, page 21 shows the UART interface between the GS2000 based module and a
Host.
Figure 1 UART Interface Between GS2000 Based Module and Host
1VV0301447 Rev 1.0 21 of 77 2015-05-05

• SPI0 Interface: It is used to program the module flash using a SPI master.
SPI Mode: Mode 1
SPI Clock: Up to 1.3MHz using Cheetah SPI adapter, 4MHz using Aardvark SPI
adapter (www.totalphase.com for SPI adapters)
SPI Bit Order: MSB first
Slave Select: Active Low
Figure 2, page 22 shows the SPI interface between the GS2000 based module acting as an
SPI Slave and a SPI Master.
Figure 2 SPI Interface Between GS2000 Based Module and SPI Master
1VV0301447 Rev 1.0 22 of 77 2015-05-05

1.2 GS2000 Boot Procedure

Figure 3, page 23 shows the GS2000 Based Modules Boot Procedure Flow Diagram.
Figure 3 GS2000 Boot Procedure
1VV0301447 Rev 1.0 23 of 77 2015-05-05

1.2.1 GS2000 Boot ROM Flow in Program Mode

The following is the Boot ROM flow in Program mode.
1. Initialize the clocks.
2. Initialize the low level OTP driver.
3. Initialize the OTP memory management module.
4. Initialize the GPIOs.
5. Initialize the Flash interface.
6. Check if flash exist:
a. Read Flash ID (Issues a Flash Read ID command and reads the RX FIFO)
b. If Flash ID is 0, then it assumes flash device is not present and do not configure
anything for flash.
c. If Flash is present, depending on the ID, configure the lanes (single lane / quad
lane)
7. Initialize the flash cache.
8. Check the GPIO mode select pin (PROGRAM/RUN).
9. In Program mode, ideal loop waiting for Host interface commands over UART0 /
SPI0.
1VV0301447 Rev 1.0 24 of 77 2015-05-05

1.3 Host Interface Overview

The Host Interface (HI) allows external systems to access the on-chip APP CPU and
WLAN CPU services. The HI allows the external system to perform programming on the
on-module Flash of the GS2000 based modules through UART0 or SPI0 interface.
1.3.1 HI Frame Format

All messages carried over the Host Interface have a common format. They are composed
of a HI header, and parameters depending on the header. HI frames are composed, in
addition to the HI header and parameters, of a start delimiter and a HI HEADER checksum.
In programming mode, the boot ROM running on APP CPU always waits for incoming
frames on the UART0 or SPI0 interface that it controls. This format is defined in Figure 4,
page 25 below.
Figure 4 HI Frame Format (From Host Side)
An HI frame consists of:

1. Start-of-frame (SOF) delimiter: It is a single byte with a value of 0xA5 which is
used to ensure synchronization at the frame level. The driver starts the reception
process when it recognizes the delimiter. The length of the delimiter has been reduced
to 1 byte to avoid alignment problems when waiting for the start element. However,
no provisions are made to ensure that the subsequent data stream does not contain a
byte with value 0xA5, so it is possible for the driver to mistake a data byte for a
delimiter. Therefore, a header checksum has been added to ensure correct
synchronization.
2. Host Interface header: It consists of the following fields:
a. Class: It is the service class that determines the format of the data in HI
Parameters. The service class of a frame is signaled by the value of this field. The
Download class used to program the on-module flash is represented as 0x02.
ROM debug class is represented as 0x07.
b. Reserved: Reserved for future purposes (value = 0x00)
c. Additional Info: It is a general-purpose field which is of 2 bytes whose contents
depend on the service class of the message. (This is not applicable for Download
class and its value is 0x00.)
d. Length: It is 2 bytes long field which uses 11 bits to specify the length of HI
parameters and it cannot exceed 1514 bytes. The length field does not include the
1 byte SOF and 7 bytes of HI header. Depending on the PHY used to carry the HI
frame, it is possible that only the 11 significant bits will be transmitted.
1VV0301447 Rev 1.0 25 of 77 2015-05-05

e. Checksum: It is computed as the 1’s complement of the 8-bit long (modulo-256)

sum of first 6 bytes of the HI Header.
NOTE: Each byte is independently added to the sum, as an integer between 0

and 255, without regard for its significance within its own data field.
3. HI Parameters: It is the section that consists of data specific for relevant messages.
For more information, refer Chapter 2 Download Class Messages, page 27.
NOTE: The multi-byte fields in all of the commands are specified with lower byte
first. That means 0x40080000 would be seen as 00 00 08 40.
1VV0301447 Rev 1.0 26 of 77 2015-05-05

Chapter 2 Download Class Messages
This chapter describes the format of different messages in download class. Figure 5,
page 27 shows the HI frame for Download Class Messages. The class field of HI Header
contains value 0x02 for Downloaded Class Messages.
• Download Request, page 28
• Copy Request, page 29
• Error Indication, page 30
• Ack (Acknowledgment), page 31
Figure 5 Download Class Messages
1VV0301447 Rev 1.0 27 of 77 2015-05-05

2.1 Download Request

The Download request is composed of six fields (see Figure 6, page 28).
Figure 6 Download Request Format
Table 7, page 28 describes the Download Request Format.
Table 7 Download Request Format

Identifier Description
Opcode It is 7 bits with a value of 0x01 (Bit 7 is reserved).
It is 1 byte and specifies the sequence number of the current request. It starts
SeqNbr
from 0x00 and increments by 1 with every request.
FileLength It is 4 bytes and specifies the total length of the downloaded File.
BundleLength It is 2 bytes and specifies the length (in bytes) of the Data field.
It is 4 bytes and provides the address where the current code bundle must be
stored in shared SRAM. In GainSpan gs2k_flashprogram tool the RamAddr
RamAddr
starts at 0x00000000 location and is then incremented in steps based on the
BundleLength.
Data <BundleLength> It provides the data to be written to SRAM.
NOTE: What is a File? The binary which needs to be downloaded is divided into
multiple fragments and each fragment (maximum of 16KB) is termed as a File.
Example - Download Table 8, page 28 shows the Download Request Command and Response that is
Request Command sent/received to/from the GS2000 based module.
and Response
Table 8 Download Request Command and Response
Command Response Ack
A5 02 00 00 00 ED 03 0D 01 00 00 40 A5 02 00 00 00 02 00 FB 05 00
00 00 E1 03 00 00 00 00 66 77 6F 6B
FF FF FF FF 50 00 00 00 04 30 00 00
00 ……
1VV0301447 Rev 1.0 28 of 77 2015-05-05

2.2 Copy Request

The Copy request is composed of eight fields (see Figure 7, page 29).
Figure 7 Copy Request Format
Table 9, page 29 describes the Copy Request Format.
Table 9 Copy Request Format

It is 7 bits (Bit 0 to Bit 6) with value 0x02 and Bit 7 is the field More which indicates if there
is any pending File.
Opcode • 0x02 - indicates that it is the last Copy Request and there is not further Files to be
downloaded.
• 0x82 - indicates that there is another File for download.
It is 1 byte and specifies the sequence number of the current request. It is incremented by 1
SeqNbr
with every next request.
FlashAddr It is 4 bytes and specifies the destination address (flash memory) of the File to be copied.
Length It is 4 bytes and specifies the length (in bytes) of the File to be copied.
It is 4 bytes and specifies the source address (SRAM) of the File to be copied. In GainSpan
RamAddr gs2k_flashprogram tool the RamAddr is always 0x00000000 indicating where the 16K
Download Request chunk starts in the SRAM.
Checksum It is 4 bytes and it is 1’s complement of sum of all the bytes in a File.
It is 4 bytes and provides the address of the flash memory that is to be used as Swap Flash
SwapFlashAddr
(reserved for future use).
Example - Copy Table 10, page 29 shows the Copy Request Command and Response that is sent/received
Request Command to/from the GS2000 based module.
and Response
Table 10 Copy Request Command and Response
Command Response Ack
A5 02 00 00 00 16 00 E7 82 11 00 00 A5 02 00 00 00 02 00 FB 05 11
01 00 00 40 00 00 00 00 00 00 3A D9
EC FF 00 00 00 08
NOTE: It is recommended for everyone to do an explicit erase because of the

dynamic file system data. Although the Copy Request performs an erase before
writing to the flash, it is a safe practice to do an explicit erase.
1VV0301447 Rev 1.0 29 of 77 2015-05-05

2.3 Error Indication

The Error Indication is composed of three fields (see Figure 8, page 30).
Figure 8 Error Indication Format
Table 11, page 30 describes the Error Indication Format.
Table 11 Error Indication Format

Opcode It is 7 bits with a value of 0x04 and Bit 7 (8th bit is reserved).
It is 1 byte and specifies the sequence number of the current
SeqNbr
error indication.
It is 2 bytes and specifies a failure code. Different types of
supported failure codes are:
• 0x01 (ModuleBusy): It specifies that the module is busy and
the Firmware update module was not ready to receive a
command. After receiving the error, the Host retries the
command.
ErrorCode • 0x02 (ParamError): It specifies that the Copy Request
contains inconsistent parameters.
• 0x12 (ChecksumError): It specifies that the computed
checksum is different from the one passed in the Copy
Request.
• 0x14 (SeqNumError): It specifies that a bad sequence
number has been detected.
1VV0301447 Rev 1.0 30 of 77 2015-05-05

2.4 Ack (Acknowledgment)

The Ack message is composed of two fields (see Figure 9, page 31).
Figure 9 Ack Message Format
Table 12, page 31 describes the Acknowledgment Indication.
Table 12 Acknowledgment Indication Format

It is 7 bits with a value of 0x05 and the Bit 7 (8th bit is
Opcode
reserved).
It is 1 byte and specifies the sequence number of the
SeqNbr
request being acknowledged.
1VV0301447 Rev 1.0 31 of 77 2015-05-05

2.5 Transferring Binary

Binary is the data (Super Block, Control Block, Firmware, or any type of information) that
is transferred from a host to the GS2000 based modules.
Consider a scenario where the host has to transfer a binary of 18KB to GS2000 based
module. The host is connected to the GS2000 based module through the UART0 or SPI0
interface and transfers binary (see Figure 10, page 32).
Figure 10 Transferring Binary
1VV0301447 Rev 1.0 32 of 77 2015-05-05

The step-by-step procedure followed to transfer binary is as follows:

1. The host sends the first Download Request (Opcode=0x01, SeqNbr=0x00) which is a
subset of the first File (16 KB of binary) to the GS2000 based module.
2. If the Download Request (Opcode=0x01, SeqNbr=0x00) is successfully downloaded
on the RAM of GS2000 based module, then it sends an acknowledgment (Ack) with
Opcode=0x05 and SeqNbr=0x00 (sequence number of the downloaded DR).
Otherwise, it sends and error indication (Error) and the host resends the Download
Request).
3. Host sends rest of the DRs similarly till the File is completely downloaded on GS2000
based module.
4. Once one complete File which is 16KB of the binary is successfully sent, the Host
sends a Copy Request (Opcode=0x82, SeqNbr=0x0B) to the GS2000 based module.
5. GS2000 based module computes the checksum of the downloaded File in its SRAM
and compares the computed File with checksum received in the Copy Request
message.
6. After successful checksum verification, the GS2000 based module erases the flash,
programs the flash, and sends an acknowledgment (Ack) with Opcode=0x05 and
SeqNbr=0x0B (sequence number of the Copy Request) which indicates that the File is
transferred successfully.
7. Host sends the next Download Request (Opcode=0x01, SeqNbr=0x0C) which is a
subset of the next File (remaining 2KB of Binary) to the GS2000 based module.
8. Step 2 to Step 6 are repeated till the host sends the complete File to GS2000 based
module.
1VV0301447 Rev 1.0 33 of 77 2015-05-05

- This page intentionally left blank -
1VV0301447 Rev 1.0 34 of 77 2015-05-05

Chapter 3 ROM Debug Class Messages
This chapter provides various boot ROM commands for the GS2000 based module for
reading and writing registers, memory and external flash through flash interface. This
chapter also describes the commands and their responses with examples. The HI Frame
Format including Download Class, Download Request, Copy Request, Error Indication,
and Ack are described in Chapter 1 Programming the GS2000 Based Modules, page 19.
• RegPeek, page 36
• RegPoke, page 37
• MemRead, page 38
• MemWrite, page 39
• FlashRead, page 40
• FlashErase, page 41
• FlashEraseCheck, page 42
• FlashCheckSum, page 43
• Execute at Address, page 44
• WLAN Start, page 45
• WLAN Stop, page 46
Figure 11, page 35 shows the ROM debug message format that forms the data portion of
messages, i.e., HI Parameters portion.
Figure 11 ROM Debug Message Format
1VV0301447 Rev 1.0 35 of 77 2015-05-05

3.1 RegPeek
Command Table 13, page 36 describes the RegPeek Command Format.
Table 13 RegPeek Command Format

Opcode It is 8 bits - 0x41.
NumRegs It is 4 bytes. Number of Registers.
It is 4 bytes. Address of Register n. Unaligned accesses are allowed; i.e., the
Addr [Reg n]
address need not be 4 byte aligned.
It is 4 bytes. Value of the Register n. For each operation, this should be set to
Val [Reg n] zero. The value field is always 4 bytes wide irrespective of the width field;
i.e., even 1 byte value takes 4 bytes space.
Number of bytes to read. Allowed values are 1 byte, 2 byte, and 4 byte; i.e.,
Width [Reg n]
the width values are 1, 2, and 4 respectively.
Response Table 14, page 36 describes the RegPeek Response Format.
Table 14 RegPeek Response Format

Addr [Reg n]
It is 4 bytes. Value of the Register n. For each operation, this should be set to
Val [Reg n] zero. The value field is always 4 bytes wide irrespective of the width field;
i.e., even 1 byte value takes 4 bytes space.
Width [Reg n] Number of bytes to read. Allowed values are 1 byte, 2 byte, and 4 bytes.
Notes:
1. Both request and response contain [addr, val, width] tuples even though request does
not really need to contain val.
2. The maximum number of registers is limited by maximum HI frame size; i.e., 1500
bytes.
3. HI Header Additional Info field set to 1 to send the message to WLAN.
4. There shall be additional Addr, Val and Width fields (tuple) required in case there are
more than one register.
5. Content of the response frame in this case shall be same as request frame except the
response opcode = (request opcode + 0x40).
1VV0301447 Rev 1.0 36 of 77 2015-05-05

Example - RegPeek Table 15, page 37 shows the RegPeek Command and Response that is sent/received to/from
Command and the GS2000 based module.
Response
Table 15 RegPeek Command and Response
Command Response
A5 07 00 00 00 11 00 E7 41 01 00 00 A5 07 00 00 00 11 00 E7 81 01 00 00 00
00 00 00 08 40 00 00 00 00 04 00 00 00 00 08 40 50 50 41 00 04 00 00 00
00
3.2 RegPoke
Command Table 16, page 37 describes the RegPoke Command Format.
Table 16 RegPoke Command Format

Addr [Reg n]
It is 4 bytes. Value of the Register n. The value field is always 4 bytes wide
Val [Reg n]
irrespective of the width field; i.e., even 1 byte value takes 4 bytes space.
Width [Reg n] Number of bytes to written. Allowed values are 1 byte, 2 byte, and 4 bytes.
Notes:
1. Request contain [addr, val, width] tuples.
bytes.
4. There shall be additional Addr, Val, and Width fields (tuple) required in case there are
more than one register.
response opcode = (request opcode + 0x040).
1VV0301447 Rev 1.0 37 of 77 2015-05-05

Example - RegPoke Table 17, page 38 shows the RegPoke Command that is sent to the GS2000 based module.
Command
Table 17 RegPoke Command
Command Response
A5 07 00 00 00 11 00 E7 42 01 00 00 -
00 18 00 08 40 78 56 34 12 04 00 00
00
NOTE: There is no response to RegPoke.
3.3 MemRead
Command Table 18, page 38 describes the MemRead Command Format.
Table 18 MemRead Command Format

It is 4 bytes. Address of Memory location. Unaligned accesses are allowed; i.e.,
Addr
the address need not be 4 byte aligned.
Len It is 4 bytes. Number of bytes to be written to the specified Memory location.
Response Table 19, page 38 describes the MemRead Response Format.
Table 19 MemRead Response Format

Addr
Len It is 4 bytes. Number of bytes to be read from the specified Memory location.
Data Len bytes. This will contain the data present in the specified memory location.
Notes:
bytes.
response code = (request code + 0x40).
1VV0301447 Rev 1.0 38 of 77 2015-05-05

Example - MemRead Table 20, page 39 shows the MemRead Command and Response that is sent/received
Command and to/from the GS2000 based module.
Response
Table 20 MemRead Command and Response
Command Response
A5 07 00 00 00 09 00 EF 43 00 05 04 A5 07 00 00 00 19 00 DF 83 00 05 04 20
20 10 00 00 00 10 00 00 00 00 00 00 00 33 33 00 3E 45
49 4D 31 31 30 32 00
3.4 MemWrite
Command Table 21, page 39 describes the MemWrite Command Format.
Table 21 MemWrite Command Format

Addr
Len It is 4 bytes. Number of bytes to be written to the specified Memory location.
Data [Len bytes] Number of bytes to the specified memory location.
Notes:
bytes.
Example - MemWrite Table 22, page 39 shows the MemWrite Command that is sent to the GS2000 based module.
Command
Table 22 MemWrite Command
Command Response
A5 07 00 00 00 F7 03 FE 44 00 00 03 -
20 EE 03 00 00 80 B5 00 F0 ED FA 01
BD 2D E9 F2 4F 84 B0 07 00 15 00 1C
00 5F ……
NOTE: There is no response to MemWrite.
1VV0301447 Rev 1.0 39 of 77 2015-05-05

3.5 FlashRead
Command Table 23, page 40 describes the FlashRead Command Format.
Table 23 FlashRead Command Format

Addr It is 4 bytes. Address of the Flash location.
Len It is 4 bytes. Number of bytes to be read from the specified Flash location.
Response Table 24, page 40 describes the FlashRead Response Format.
Table 24 FlashRead Response Format

Data Len bytes. This will contain the data from Flash.
Notes:
1. The maximum read data is limited by maximum HI frame size; i.e., 1500 bytes.
Example - FlashRead Table 25, page 40 shows the FlashRead Command and Response that is sent/received
Command and to/from the GS2000 based module.
Response
Table 25 FlashRead Command and Response
Command Response
A5 07 00 00 00 09 00 EF 46 00 00 01 A5 07 00 00 00 15 00 E3 86 00 00 01 00
00 0C 00 00 00 0C 00 00 00 66 77 6F 6B FF FF FF FF 50
00 00 00
1VV0301447 Rev 1.0 40 of 77 2015-05-05

3.6 FlashErase
Command Table 26, page 41 describes the FlashErase Command Format.
Table 26 FlashErase Command Format

Note:
1. The minimum erase size for Flash erase is 4096 bytes. Less than that would yield
success but no operation.
Response Table 27, page 41 describes the FlashErase Response Format.
Table 27 FlashErase Response Format

Addr It is 4 bytes. Address of Flash location.
Len It is 4 bytes. Number of bytes to be erased from the specified Flash location.
Notes:
1. The maximum read data is limited by maximum HI frame size; i.e., 1500 bytes.
Example - Table 28, page 41 shows the FlashErase Command and Response that is sent/received
FlashErase to/from the GS2000 based module.
Command and
Response
Table 28 FlashErase Command and Response
Command Response
A5 07 00 00 00 09 00 EF 49 00 00 00 00 00 A5 07 00 00 00 09 00 EF 89 00 00 00 00 00
00 40 00 00 40 00
Notes:
1. If the length is 4095 bytes, then nothing will get erased. However you will see boot
ROM returning success.
2. If the length is 4096 bytes are erased, then 4K sector of the Flash gets erased.
3. If the length is 4097 bytes get erased, then it will erase 8K sector (assuming the start
address is 0x00000000).
1VV0301447 Rev 1.0 41 of 77 2015-05-05

3.7 FlashEraseCheck
Command Table 29, page 42 describes the FlashEraseCheck Command Format.
Table 29 FlashEraseCheck Command Format

Opcode It is 8 bits - 0x4d.
It is 4 bytes. Address of Flash memory where to check. The address needs to be
Addr
4 byte aligned.
Len It is 4 bytes. Number of bytes to be checked in Flash.
Response Table 30, page 42 describes the FlashEraseCheck Response Format.
Table 30 FlashEraseCheck Response Format

Opcode It is 8 bits - 0x8d.
It is 4 bytes. Address of the Flash memory where it got erased. The address
Addr
needs to be 4 byte aligned.
Len It is 4 bytes. Number of contiguous words that has FF FF FF FF.
Example - Flash Table 31, page 42 shows the Flash Erase Check Command and Response that is
Erase Check sent/received to/from the GS2000 based module.
Command and
Response
Table 31 Flash Erase Check Command and Response
Command Response
A5 07 00 00 00 09 00 EF 4D 00 00 20 00 00 00 20 A5 07 00 00 00 09 00 EF 8D 00 00 20 00
00 00 00 06 00
The use of FlashEraseCheck is to reduce the erase time. Erasing an entire 2MB flash is a
costly operation. The erase command takes the longest time to execute in the GS2000. In
order to save time for erasing, perform an erase check which returns how much of the flash
is erased. Based on this value, you can calculate how much flash needs to be erased and
erase only that portion.
As mentioned previously in this document, you can do a binary search operation type Erase
check in our FlashProgram tool; so for a 2MB:
1. Check from 0x100000 to 0x200000. If this check returns with a value indicating “not
erased.” it is assumed there would be data between 0x000000 to 0x200000 and erase
entire 2MB from 0x00 location.
2. Check from 0x80000 to 0x100000. If check returns with a value indicating “not
erased,” then it is assumed there would be data between 0x000000 to 0x100000 and
erase 1MB from 0x00 location.
1VV0301447 Rev 1.0 42 of 77 2015-05-05

3. Check from 0x80000 to 0x100000. If this check returns with a value indicating “not
erased,” it is assumed there would be data between 0x000000 to 0x80000 and erase
512KB from 0x00 location.
4. Continue the check till you find some data and execute the erase command else
indicate flash was erased already.
Erasing 4MB takes 22 seconds, but erasing 2MB takes around 12 seconds. So with the
combination of erase check and erase, you might have to do an erase of only 1MB of
the flash (since the single image firmware and Super Block is less than 1MB
combined). This could save a few seconds.
3.8 FlashCheckSum
Command Table 32, page 43 describes the FlashCheckSum Command Format.
Table 32 FlashCheckSum Command Format

Opcode It is 8 bits - 0x4c.
It is 4 bytes. Address of the Flash memory where to check. The address needs
Addr
to be 4 byte aligned.
Len It is 4 bytes. Length of bytes to check the checksum.
Response Table 33, page 43 describes the FlashCheckSum Response Format.
Table 33 FlashCheckSum Response Format

Opcode It is 8 bits - 0x8c.
Checksum It is 4 bytes. Checksum.
Example - Flash Table 34, page 43 shows the Flash Checksum Command and Response that is sent/received
Checksum to/from the GS2000 based module.
Command and
Response
Table 34 Flash Checksum Command and Response
Command Response
A5 07 00 00 00 09 00 EF 4C 00 10 01 00 00 E0 0F A5 07 00 00 00 05 00 F3 8C 52 1B 09 B7
00
1VV0301447 Rev 1.0 43 of 77 2015-05-05

3.9 Execute at Address

Command Table 35, page 44 describes the Execute at Address Command Format.
Table 35 Execute at Address Command Format

Addr It is 4 bytes. Address of the Memory location of the executable instruction.
Note:
1. Thumb bit has to be set for execute command (0x20010000 is address to write data
then in execute command give it as 01 00 01 20).
Response Table 36, page 44 describes the Execute at Address Response Format.
Table 36 Execute at Address Response Format

Addr It is 4 bytes. Address of the Memory location of the executable instruction.
Note:
1. HI Header Additional Info field is set to 1 to send the message to WLAN.
Example - Execute at Table 37, page 44 shows the Execute at Address Command and Response that is
Address Command sent/received to/from the GS2000 based module.
and Response
Table 37 Execute at Address Command and Response
Command Response
A5 07 00 00 00 05 00 F3 45 01 00 03 20 A5 07 00 00 00 05 00 F3 85 00 01 00 03
1VV0301447 Rev 1.0 44 of 77 2015-05-05

3.10 WLAN Start

Command Table 38, page 45 describes the WLAN Start Command Format.
Table 38 WLAN Start Command Format

Response Table 39, page 45 describes the WLAN Start Response Format.
Table 39 WLAN Start Response Format

Example - WLAN Table 40, page 45 shows the WLAN Start Command and Response that is sent/received
Start Command and to/from the GS2000 based module.
Response
Table 40 WLAN Start Command and Response
Command Response
A5 07 00 01 00 01 00 F6 47 -
NOTE: There is no response to WLAN Start.
1VV0301447 Rev 1.0 45 of 77 2015-05-05

3.11 WLAN Stop

Command Table 41, page 46 describes the WLAN Stop Command Format.
Table 41 WLAN Stop Command Format

Response Table 42, page 46 describes the WLAN Stop Response Format.
Table 42 WLAN Stop Response Format

Example - WLAN Table 43, page 46 shows the WLAN Stop Command and Response that is sent/received
Stop Command and to/from the GS2000 based module.
Response
Table 43 WLAN Stop Command and Response
Command Response
A5 07 00 01 00 01 00 F6 48 -
NOTE: There is no response to WLAN Stop.
1VV0301447 Rev 1.0 46 of 77 2015-05-05

Chapter 4 Memory Map and File System Structure
This chapter provides an overview about the Memory Map and types of file system
structure used in GainSpan® GS2000 based modules. This manual also reviews the Flash
structure and provides necessary information required to understand. The GS2000 based
modules use different types of memory maps and file systems to control how data is stored
and retrieved. Applications use these memory maps and file system to track, organize,
store, and retrieve files during various operations. The chapter mainly focuses on the
in-module flash.
• Flash Structure, page 48
• Firmware Block, page 53
• In-Module Flash File System, page 57
1VV0301447 Rev 1.0 47 of 77 2015-05-05

4.1 Flash Structure

The Memory Map in-module Flash contains Super Block, Firmware Blocks, and File
Systems. The size of the memory map in the GS2011M is 4MB and for the GS2100M is
2MB. The memory map of an in-built module Flash in a GS2000 based module is shown
in Figure 12, page 48.
Figure 12 GS2000 Based Module Flash
The Memory Map of in-module Flash contains:

• Flash Structure, page 48
• Firmware Block, page 53
• In-Module Flash File System, page 57
1VV0301447 Rev 1.0 48 of 77 2015-05-05

4.1.1 Super Block Structure

The Super Block consists of the following fields (see Figure 13, page 49).
Figure 13 Super Block Structure
1VV0301447 Rev 1.0 49 of 77 2015-05-05

4.1.2 Boot ROM Super Block

The Boot ROM Super Block contains the address where the Control Block and Backup of
Control Block for the Boot application should be. Table 44, page 50 describes the Boot APP
Super Block fields.
Table 44 Boot ROM Super Block

Field Size (in bytes) Description
FLOK string to indicate that Super Block has been
Signature 4
read.
It contains the Control Block address for the Boot
FW0 Control Block Address 4
application’s FW0 firmware.
It is the backup of the Control Block address for the
FW0 Backup of Control Block Address 4
Boot application’s firmware.
It is filled with invalid address as there is only one
boot application in Boot ROM Super Block.
It contains the factory default elements such as
Factory Default Location 2
OTP or Flash address. It is reserved for future use.
It is the total content size of the factory default
Factory Default Size 2
elements. It is reserved for future use.
It is the starting address of the factory default
Factory Default Address 4 elements (OTP or Flash address). It is reserved for
future use.
It is the address of the Dynamic file system which
File System Address 4
will contain configuration files.
File System Size 4 it is the total size of the Dynamic file system.
DMA Read Control Word 4 It is the Read control word for Flash interface.
It is the clock divider of the DMA controller which
DMA Controller Clock Divider 2
is used to access the Flash interface.
It is the read command OPCODE for reading the
DMA Read Command 2 Flash. This is always set to QUAD I/O FAST
READ (0xEB).
1VV0301447 Rev 1.0 50 of 77 2015-05-05

4.1.3 Boot APP Super Block

The Boot Application Super Block contains the following:
• Addresses of all the Control Blocks in the module flash which specifies the
number of firmwares supported.
• Address of the Configuration file system.
• Size of the Configuration file system.
Table 45, page 51 describes the APP Super Block fields.
Table 45 Boot APP Super Block

FLOK string to indicate that Super Block has been
Signature 4
read.
It is the Control Block address for the FW0
Firmware Block.
it is the backup of Control Block address for the
FW0 Firmware block.
Firmware block.
It is the backup of Control Block address for the
FW1 Firmware block.
Firmware block.
It is the backup of Control Block address for the
FW2 Firmware block.
It contains the factory default elements such as
Factory Default Location 2
OTP or Flash address. It is reserved for future use.
It is the total content size of the factory default
Factory Default Size 2
elements. It is reserved for future use.
It is the starting address of the factory default
Factory Default Address 4 elements (OTP or Flash address). It is reserved for
future use.
It is the address of the Dynamic file system which
File System Address 4
will contain configuration files.
File System Size 4 It is the total size of the Dynamic file system.
DMA Read Control Word 4 It is the Read control word for Flash interface.
It is the clock divider of the DMA controller which
DMA Controller Clock Divider 2
is used to access the Flash interface.
It is the read command OPCODE for reading the
DMA Read Command 2 Flash. This is always set to QUAD I/O FAST
READ (0xEB).
1VV0301447 Rev 1.0 51 of 77 2015-05-05

4.1.4 Boot Application

It is the application used to select the firmware to be loaded upon module boot up.
4.1.5 Backup of Control Block for Boot Application

It is the backup of Control Block for Boot application.
1VV0301447 Rev 1.0 52 of 77 2015-05-05

4.2 Firmware Block

The GS2000 based modules support two-firmware model and three-firmware model. The
two-firmware model contains two-firmware blocks and the three-firmware model contains
three-firmware blocks.
Each firmware block contains the following:
• Control Block, page 54
• Application Firmware, page 56
• WLAN Firmware, page 56
• Static File System, page 56
• Backup of Control Block, page 56
• Static File System, page 57
• Dynamic File System, page 58
1VV0301447 Rev 1.0 53 of 77 2015-05-05

4.2.1 Control Block

The Control Block comes after the Super Block (see Figure 14, page 54).
Figure 14 Control Block in Module Flash
1VV0301447 Rev 1.0 54 of 77 2015-05-05

Table 46, page 55 describes the Control Block in Module Flash fields.
Table 46 Control Block in Module Flash

FWOK string similar to Super Block that validates the
Signature 4
Control Block.
It specifies the firmware version in Control Block. The
Revision Number 4 latest firmware is identified with a highest Revision
number.
Control Block Size 4 It specifies the size of block descriptors.
It is used to find the absolute address of the static file
Offset 4
system in module flash.
Size 4 It is the size of the static file system.
It is the address generated by the IAR tool while building
Program Address 4
firmware.
It is the physical address of the firmware in SRAM.
When APU executes an instruction, it always executes
SRAM Address 4
Block Descriptors - the Program address which is mapped to the SRAM
address.
This is a four block
descriptors and each Defines who loads the static file system.
block descriptor Owner of the Block 0x00 - App Boot ROM
contains the - It specifies the
following 2 0x01 - Application Firmware
owner of the block
information about descriptor. 0x02 - WLAN Boot ROM
the static file system
in module flash. 0x03 - WLAN Firmware
Flags - It specifies a Special indicators.
value which
indicates one or Hex Value 0x01 - Load, remap, and run
more combinations
2 Hex Value 0x02 - Load and remap
of the following
operations: Hex Value 0x03 - Load
(Loading, Mapping,
Hex Value 0x04 - Load and run
Executing)
1VV0301447 Rev 1.0 55 of 77 2015-05-05

4.2.2 Application Firmware

The GS2000 architecture includes the following components:
• Two ARM Cortex M3 CPUs
• WLAN CPU subsystem for WLAN firmware
• APP CPU subsystem for network services and application firmware
The Application Firmware implements networking protocol stacks and user application
software. The Application software can be either Serial-to-WiFi, Temperature and Low
Sensor (TLS), TLS Low Power, or any customer specific application.
4.2.3 WLAN Firmware

The WLAN Firmware is a GainSpan specific firmware provided to the customer as a binary
file which implements 802.11 b/g/n WLAN and/or 802.15.4 protocol services.
4.2.4 Static File System

The Static File System consists of Webpages, SSL certificates, etc. For more information
on Static File System, refer to 4.3 In-Module Flash File System, page 57.
4.2.5 Backup of Control Block

Back Control Block is the same as Control Block (see 4.2.1 Control Block, page 54) and
it is used for validating the firmware. If the content in the Control Block and Backup
Control Block are not the same in a firmware, then it is considered an invalid firmware.
1VV0301447 Rev 1.0 56 of 77 2015-05-05

4.3 In-Module Flash File System

The In-Module Flash File System contains the following:
• Static file system: The Static file system in the module flash contains the web
pages and security certificates
• Dynamic file system: The Dynamic file system in the module flash contains
default configurations.
4.3.1 Static File System

The Static File System in module flash is used to store Webpages (*.html, *.js, *.css) and
security related certificates such as RootCA and Public Key in a predefined location of the
module flash. The information about the predefined location of the Static file system is
specified in the Control Block of each Firmware Block.
One Firmware Block contains one static file system and a three firmware model contains
three static file systems.
When a Webpage access is requested from a web browser, the GS2000 module uses the
Webpage binary to access Webpages from the Static file system.
The file system partition of the Static file system in module flash is 1 and the Drive name
is B.
For more information regarding available size and actual usage, refer to Appendix B
Firmware Model, page 67.
NOTE: It is not recommended to modify the static file system using Application
software. For example, adding new file using API fopen, write operations, or
modify operations are not recommended.
1VV0301447 Rev 1.0 57 of 77 2015-05-05

4.3.2 Dynamic File System

Application software uses the file system API (fopen, fread, fwrite, and so on) to create
Dynamic File System during the first boot-up. For more information regarding available
size and actual usage, refer to Appendix B Firmware Model, page 67.
The Dynamic File System consists of the following information:
• WLAN calibration information
• Certificates (AT command Adding and Web Page SSL Upload)
• Profile
• MAC Address
The Dynamic File System is represented with the following naming conventions:
• Drive 0
• Drive A
NOTE: It is recommended to use the Dynamic File System for storing custom
information (e.g., sensor data, data logs, etc.). Custom applications that need
data logging size of lesser than 128KB can use the On-module Dynamic File
System. If the requirement is more than 128KB, it is highly recommended to use
the external flash system.
1VV0301447 Rev 1.0 58 of 77 2015-05-05

Chapter 5 Programming Binaries
This chapter provides instructions on how to program binaries and how the information
given in the previous chapters are implemented in the GainSpan® gs2k_flashprogram tool.
This will allow you to build your own programming tool.
• Programming the Binaries, page 59
• Programming At One Location, page 64
• Programming At Multiple Locations, page 64
5.1 Programming the Binaries

There are two binaries that needs to be programmed:
• Super Block (in this chapter we are using superblock_4MB_3_Copy.bin as an
example).
• Single Image Firmware (in this chapter we are using gs2011_s2w_5.1.1.bin as an
example).
For more information on flash structure refer to Chapter 4 Memory Map and File System
Structure, page 47.
Before programming the Super Block and the Single Image Application Firmware, it is
recommended to explicitly erase the in-module flash. Although it is not necessary to erase
explicitly it is recommended that you check the entire flash is erased before you do a fresh
programming. The reason is that the module will have GainSpan® Factory Test Code.
During the production process, there might be some dynamic file system data left on the
flash. That’s why it is recommended to erase the entire flash. You can use the Flash Erase
Check command and get the size of the flash that needs to be erased in order to have a
completely erased flash. Then do an erase check again to verify if it is completely erased.
This is implemented in the GainSpan gs2k_flashprogram tool.
The Memory Map Module Flash is described in 4.1 Flash Structure, page 48 and in Figure
12, page 48.
1VV0301447 Rev 1.0 59 of 77 2015-05-05

Super Block
The Super Block binary gets programmed at the 0x00000000 location (see Figure 15,
page 60). “superblock_4MB_3_Copy.bin” is the name of the Super Block provided. Every
Super Block includes a Boot ROM Super Block and an Application Super Block. The
address where the Single Image Firmware would get programmed is taken from the
Application Super Block. The Application Super Block starts at 0x1000 location of the
main Super Block (see 4.1.1 Super Block Structure, page 49).
Figure 15 Super Block
1VV0301447 Rev 1.0 60 of 77 2015-05-05

Single Image Firmware
Single Image Firmware: The Single Image gets programmed at FW0 Control Block
Address Field as shown in the illustrations below. This address would change based on the
Super Block being used so it has to be read from the Super Block. In case of the
superblock_4MB_3_Copy.bin, this address would be 0x00010000.
After the Single Image is programmed, you need to extract the first 4KB of the Single
Image and Program it at the FW0 Backup Control Block address which is 0x001f0000 in
case of the binaries sent. This 4KB is called as the Control Block. The Control Block is a
part of the Single Image at the beginning but in order to complete the Firmware Block you
need to put the same Control Block copied from the Single Image at the Backup Control
Block location.
Update the REVISION Number field in both the Control Block areas. The default revision
field of the Control Block (copied from the first 4KB of Single Image) contains
0xFFFFFFFF (see Figure 17, page 63). This should be modified to 0x01 (see 4.2.1 Control
Block, page 54).
Programming
Every GainSpan module flash can have one or more than one firmware at a time. The
firmware with the highest REVISION number is the copy that would be active and is called
as the CURRENT VERSION.
The firmware with the lowest REVISION number is called the FACTORY VERSION and
the firmware with a REVISION number between the highest and the lowest REVISION
numbers is the PREVIOUS VERSION.
Select three options for firmwares other than for Super Block Image:
• Current Version
• Previous Version
• Factory Version
1VV0301447 Rev 1.0 61 of 77 2015-05-05

Figure 16, page 62 shows the flash memory structure for Two Firmware Model or Three
Firmware Model.
Figure 16 Flash Memory Structure
The firmware image provided by GainSpan contains 0xFFFFFFFF in the REVISION

number field. This field should be modified on the flash with the appropriate REVISION
Number. You should have the capability to program one image, two images or three images
based upon his selection and the Super Block you are using.
There can be four different types of Super Blocks:
• Superblock_4MB_3_Copy
Three cases for programming:
Case 1 - Regardless of the Super Block file selected, program the firmware at FW0 Control Block
Programming Only address with REVISION Number 0x01. This firmware would be the CURRENT
One Firmware Image VERSION.
Case 2 - Use any of the above mentioned four Super Blocks and program the CURRENT VERSION
Programming Two firmware at FW1 Control Block address with REVISON Number 0x02 and the PREVIOUS
Firmware Images VERSION firmware at the FW0 Control Block address with REVISION Number 0x01.
Case 3 - You could use only Superblock_4MB_3_Copy or Superblock_2MB_3_Copy images and

Programming Three program the CURRENT VERSION firmware at FW2 Control Block address with
Firmware Images REVISON Number 0x03, and the PREVIOUS VERSION firmware at the FW1 Control
Block address with REVISION Number 0x02 the FACTORY VERSION firmware at the
FW0 Control Block address with REVISION Number 0x01.
1VV0301447 Rev 1.0 62 of 77 2015-05-05

NOTE: The Control Block is part of the Single Image Firmware that is provided.
This is the first 4KB of the image.
The REVISION Number field in this image would be 0xFFFFFFFF and should be modified
on the flash appropriately based upon which copy is it, and which Super Block type is
selected. The same Control Block needs to be programmed at the Backup Control Block
Address as explained in the document we sent.
Figure 17 Control Block Revision Number Field
1VV0301447 Rev 1.0 63 of 77 2015-05-05

5.2 Programming At One Location

To program at one location, perform the following:
1. Select the Super Block Image and a Working Copy Image.
2. Program Super Block at 0x00000000
3. Verify that programmed Super Block has a valid “FLOK” signature.
4. Read the Application Super Block that starts from 0x1000 location and store the
Control Block and Backup Control Block Addresses for FW0
5. Write the Single Image at the Control Block address for FW0 and modify the
REVISION field in the Control Block from 0xFFFFFFFFFF to 0x01.
6. Copy the same modified Control Block and program it at the Backup Control Block
address for FW0.
5.3 Programming At Multiple Locations

To program at multiple locations, perform the following:
1. Select the Super Block Image and a Working Copy Image, Previous Copy Image
and/or Factory Copy Image
2. Program Super Block at 0x00000000
3. Verify that programmed Super Block has a valid “FLOK” signature.
4. Read the Application Super Block that starts from 0x1000 location and store the
Control Block and Backup Control Block Addresses for FW0, FW1, and FW2.
5. Write the Factory Copy Image at the Control Block address for FW0 and modify the
address for FW0.
7. Write the Previous Copy Image at the Control Block address for FW1 and modify the
address for FW1.
9. Write the Factory Copy Image at the Control Block address for FW2 and modify the
address for FW2.
NOTE: For detailed explanation at byte level, refer to Chapter 2 Download Class
Messages, page 27, and Chapter 3 ROM Debug Class Messages, page 35.
1VV0301447 Rev 1.0 64 of 77 2015-05-05

Appendix A Opcodes
This chapter provides an overview of the Opcodes for the GS2000 based modules. Table
47, page 65 describes the Opcode message and command response examples.
Table 47 Opcode Message and Command Response

Message Command Response
OpCode Example OpCode Example
A5 02 00 00 00 ED 03 0D 01 00 00 40 00 00 E1
Download 0x01 03 00 00 00 00 66 77 6F 6B FF FF FF FF 50 00 - A5 02 00 00 00 02 00 FB 05 00
00 00 04 30 00 00 00 ……
0x02, A5 02 00 00 00 16 00 E7 82 11 00 00 01 00 00
Copy - A5 02 00 00 00 02 00 FB 05 11
0x82 40 00 00 00 00 00 00 3A D9 EC FF 00 00 00 08
Error Indication - - 0x04 -

Ack - - 0x05 -
A5 07 00 00 00 11 00 E7 41 01 00 00 00 00 00 A5 07 00 00 00 11 00 E7 81 01 00 00 00 00
RegPeek 0x41 0x81
08 40 00 00 00 00 04 00 00 00 00 08 40 50 50 41 00 04 00 00 00
A5 07 00 00 00 11 00 E7 42 01 00 00 00 18 00
RegPoke 0x42 - -
08 40 78 56 34 12 04 00 00 00
A5 07 00 00 00 19 00 DF 83 00 05 04 20 10
A5 07 00 00 00 09 00 EF 43 00 05 04 20 10 00
MemRead 0x43 0x84 00 00 00 00 00 00 00 33 33 00 3E 45 49 4D
00 00
31 31 30 32 00
A5 07 00 00 00 F7 03 FE 44 00 00 03 20 EE 03
MemWrite 0x44 00 00 80 B5 00 F0 ED FA 01 BD 2D E9 F2 4F 84 - -
B0 07 00 15 00 1C 00 5F ……
A5 07 00 00 00 09 00 EF 46 00 00 01 00 0C 00 A5 07 00 00 00 15 00 E3 86 00 00 01 00 0C
FlashRead 0x46 0x86
00 00 00 00 00 66 77 6F 6B FF FF FF FF 50 00 00 00
A5 07 00 00 00 09 00 EF 49 00 00 00 00 00 00 A5 07 00 00 00 09 00 EF 89 00 00 00 00 00
FlashErase 0x49 0x89
40 00 00 40 00
A5 07 00 00 00 09 00 EF 4C 00 10 01 00 00 E0
FlashChecksum 0x4C 0x8C A5 07 00 00 00 05 00 F3 8C 52 1B 09 B7
0F 00
A5 07 00 00 00 09 00 EF 4D 00 00 20 00 00 00 A5 07 00 00 00 09 00 EF 8D 00 00 20 00 00
FlashEraseCheck 0x4D 0x8D
20 00 00 06 00
Execute at
0x45 A5 07 00 00 00 05 00 F3 45 01 00 03 20 0x85 A5 07 00 00 00 05 00 F3 85 00 01 00 03
Address
WLAN Start 0x47 A5 07 00 01 00 01 00 F6 47 - -
WLAN Stop 0x48 A5 07 00 01 00 01 00 F6 48 - -
1VV0301447 Rev 1.0 65 of 77 2015-05-05

1VV0301447 Rev 1.0 66 of 77 2015-05-05

Appendix B Firmware Model
This chapter provides an overview of the Firmware Model Memory Map for software
releases 5.1.x and 5.2.x.
B.1 Memory Map for 5.1.x Releases

Table 48, page 67 lists the available size and currently used size for file systems 5.1.x
releases.
Table 48 Firmware Model File System Sizes for 5.1.x Releases

5.1.x Releases Two Firmware Three Firmware Two Firmware Three Firmware
Model (2MB) Model (2MB) Model (4MB) Model (4MB)
Available Static File
320KB 64KB 1088KB 576KB
System (Webpage)
Used Static File
System (currently 64KB 64KB 64KB 64KB
used)
Available Dynamic
File System 448KB 448KB 512KB 512KB
(Webpage)
Used Dynamic File
System (currently 256KB 256KB 256KB 256KB
used)
1VV0301447 Rev 1.0 67 of 77 2015-05-05

Figure 18, page 68 shows the memory map for a 2MB Two Firmware Model in 5.1.x
releases.
Figure 18 Two Firmware Model for 5.1.x Releases (2MB)
1VV0301447 Rev 1.0 68 of 77 2015-05-05

Figure 19, page 69 shows the memory map for a 2MB Three Firmware Model in 5.1.x
releases.
Figure 19 Three Firmware Model for 5.1.x Releases (2MB)
1VV0301447 Rev 1.0 69 of 77 2015-05-05

Figure 20, page 70 shows the memory map for a 4MB Two Firmware Model in 5.1.x
releases.
1VV0301447 Rev 1.0 70 of 77 2015-05-05

Figure 21, page 71 shows the memory map for a 4MB Three Firmware Model in 5.1.x
releases.
1VV0301447 Rev 1.0 71 of 77 2015-05-05

B.2 Memory Map for 5.2.x Releases

Table 49, page 72 lists the available size and currently used size for file systems 5.2.x
releases.
Table 49 Firmware Model File System Sizes for 5.2.x Releases

5.2.x Releases Two Firmware Two Firmware Three Firmware
Model (2MB) Model (4MB) Model (4MB)
Available Static File
124KB 892KB 380KB
System (Webpage)
Used Static File System
64KB 64KB 64KB
(currently used)
Available Dynamic File
448KB 512KB 512KB
System (Webpage)
Used Dynamic File
256KB 256KB 256KB
System (currently used)
1VV0301447 Rev 1.0 72 of 77 2015-05-05

Figure 22, page 73 shows the memory map for a 2MB Two Firmware Model 5.2.x releases.
1VV0301447 Rev 1.0 73 of 77 2015-05-05

Figure 23, page 74 shows the memory map for a 4MB Two Firmware Model 5.2.x releases.
1VV0301447 Rev 1.0 74 of 77 2015-05-05

Figure 24, page 75 shows the memory map for a 4MB Three Firmware Model 5.2.x
releases.
1VV0301447 Rev 1.0 75 of 77 2015-05-05

1VV0301447 Rev 1.0 76 of 77 2015-05-05

GS2K Module Programming and Protocol Reference Rev 1

Uploaded by

Copyright:

Available Formats

GS2K Module Programming and Protocol Reference Rev 1

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

GS2K Module Programming and Protocol Reference Rev 1

Uploaded by

Copyright:

Available Formats

GS2K Module Programming and Protocol Reference Guide

GS2K Module Programming and Protocol

COMPUTER SOFTWARE COPYRIGHTS

Chapter 1 Programming the GS2000 Based Modules .................................................................... 19

Chapter 2 Download Class Messages ............................................................................................. 27

Chapter 3 ROM Debug Class Messages ......................................................................................... 35

Chapter 4 Memory Map and File System Structure ......................................................................... 47

Chapter 5 Programming Binaries .................................................................................................... 59

1VV0301447 Rev 1.0 5 of 77 2015-05-05

Appendix A Opcodes .......................................................................................................... 65

1VV0301447 Rev 1.0 6 of 77 2015-05-05

About This Manual

1VV0301447 Rev 1.0 7 of 77 2015-05-05

Table 1 Revision History

Version Date Remarks

1VV0301447 Rev 1.0 8 of 77 2015-05-05

Table 2 Document Text Conventions

Convention Type Description

Proportional font Gives specific details about a parameter.

lowercase Indicates keywords. Enter values exactly as shown in the command

Enclose optional parameters. Choose none; or select one or more an

1VV0301447 Rev 1.0 9 of 77 2015-05-05

Table 2 Document Text Conventions (Continued)

Convention Type Description

A.B.C.D IPv4-style address.

WORD Indicates user input of any contiguous string (excluding spaces).

1VV0301447 Rev 1.0 10 of 77 2015-05-05

Table 3 Symbol Conventions

Icon Type Description

Alerts you of potential damage to a program, device,

Cautions you about a situation that could result in

Warns you of a potential situation that could result in

Electro-Static Discharge Notifies you to take proper grounding precautions

1VV0301447 Rev 1.0 11 of 77 2015-05-05

1VV0301447 Rev 1.0 12 of 77 2015-05-05

1VV0301447 Rev 1.0 13 of 77 2015-05-05

Table 5 Other Documents and References

1VV0301447 Rev 1.0 14 of 77 2015-05-05

1VV0301447 Rev 1.0 15 of 77 2015-05-05

Contact Information, Support

1VV0301447 Rev 1.0 16 of 77 2015-05-05

Returning Products to GainSpan

To return a hardware component:

Guidelines for Packing Components for Shipment

CAUTION! Do not stack any of the components.

1VV0301447 Rev 1.0 17 of 77 2015-05-05

Accessing the GainSpan Portal

1. Visit http://www.telit.com, go to Products> Wi-Fi and Blue-tooth, then scroll down

1VV0301447 Rev 1.0 18 of 77 2015-05-05

Chapter 1 Programming the GS2000 Based Modules

1.1 Programming Mode

1VV0301447 Rev 1.0 19 of 77 2015-05-05

Table 6 Boot Control Pin Functions

1VV0301447 Rev 1.0 20 of 77 2015-05-05

NOTE: GPIO25 should be pulled up high for 921K.

Figure 1 UART Interface Between GS2000 Based Module and Host

1VV0301447 Rev 1.0 21 of 77 2015-05-05

1VV0301447 Rev 1.0 22 of 77 2015-05-05

1.2 GS2000 Boot Procedure

Figure 3 GS2000 Boot Procedure