Quectel WCDMA UG FILE Series Installation manual

WCDMA UGxx FILE
AT Commands Manual
UMTS/HSPA Module Series
Rev. WCDMA_UGxx_FILE_AT_Commands_Manual_V1.3
Date: 2016-05-05
www.quectel.com

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 1 / 19
Our aim is to provide customers with timely and comprehensive service. For any
assistance, please contact our company headquarters:
Quectel Wireless Solutions Co., Ltd.
Office 501, Building 13, No.99, Tianzhou Road, Shanghai, China, 200233
Tel: [phone]
Email: [email protected]om
Or our local office. For more information, please visit:
http://www.quectel.com/support/salesupport.aspx
For technical support, or to report documentation errors, please visit:
http://www.quectel.com/support/techsupport.aspx
Or email to: [e-mail]
GENERAL NOTES
QUECTEL OFFERS THE INFORMATION AS A SERVICE TO ITS CUSTOMERS. THE INFORMATION
PROVIDED IS BASED UPON CUSTOMERS‟ REQUIREMENTS. QUECTEL MAKES EVERY EFFORT
TO ENSURE THE QUALITY OF THE INFORMATION IT MAKES AVAILABLE. QUECTEL DOES NOT
MAKE ANY WARRANTY AS TO THE INFORMATION CONTAINED HEREIN, AND DOES NOT ACCEPT
ANY LIABILITY FOR ANY INJURY, LOSS OR DAMAGE OF ANY KIND INCURRED BY USE OF OR
RELIANCE UPON THE INFORMATION. ALL INFORMATION SUPPLIED HEREIN IS SUBJECT TO
CHANGE WITHOUT PRIOR NOTICE.
COPYRIGHT
THE INFORMATION CONTAINED HERE IS PROPRIETARY TECHNICAL INFORMATION OF
QUECTEL CO., LTD. TRANSMITTING, REPRODUCTION, DISSEMINATION AND EDITING OF THIS
DOCUMENT AS WELL AS UTILIZATION OF THE CONTENT ARE FORBIDDEN WITHOUT
PERMISSION. OFFENDERS WILL BE HELD LIABLE FOR PAYMENT OF DAMAGES. ALL RIGHTS
ARE RESERVED IN THE EVENT OF A PATENT GRANT OR REGISTRATION OF A UTILITY MODEL
OR DESIGN.
Copyright © Quectel Wireless Solutions Co., Ltd. 2016. All rights reserved.
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 2 / 19
About the Document
History
Revision
Date
Author
Description
1.0
2014-12-10
Jonathan WEN
Initial
1.1
2015-03-02
Bonnie ZHAO
Changed the document name from “UG95”
to “UGxx”.
1.2
2015-04-01
Bonnie ZHAO
Updated applicable modules.
1.3
2016-05-05
Sophie ZHU
Changed <filename> into <file_name>
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 3 / 19
Contents
About the Document...................................................................................................................................2
Contents.......................................................................................................................................................3
1Introduction..........................................................................................................................................5
1.1. The Process of Using File AT Commands ..............................................................................5
2Description of AT Command ..............................................................................................................6
2.1. AT+QFLDS Get the Space Information of the Storage.........................................................6
2.2. AT+QFLST List Files.............................................................................................................7
2.3. AT+QFDEL Delete the File in the Storage............................................................................8
2.4. AT+QFUPL Upload File to the Storage.................................................................................8
2.5. AT+QFDWL Download the File from the Storage...............................................................10
2.6. AT+QFOPEN Open the File ............................................................................................... 11
2.7. AT+QFREAD Read the File................................................................................................12
2.8. AT+QFWRITE Write the File...............................................................................................12
2.9. AT+QFSEEK Seek the File.................................................................................................13
2.10. AT+QFPOSITION Get the Offset of the File Pointer..........................................................14
2.11. AT+QFTUCAT Truncate the File from the File Pointer.......................................................14
2.12. AT+QFCLOSE Close the File.............................................................................................15
3Example ..............................................................................................................................................16
3.1. Upload and Download Files..................................................................................................16
3.1.1. Upload the File...............................................................................................................16
3.1.1.1. NonACK Mode..................................................................................................... 16
3.1.1.2. ACK Mode ............................................................................................................16
3.1.2. Download the File ..........................................................................................................17
3.2. Write and Read the File.........................................................................................................17
3.2.1. Write and Read RAM File..............................................................................................17
4Appendix A Summary of <err> Code...............................................................................................18
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 4 / 19
Table Index
TABLE 1: SUMMARY OF ERROR CODE.................................................................................................18
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 5 / 19
1Introduction
Quectel module provides AT commands to operate files on RAM (Random Access Memory). This
document is a reference guide to these commands. The files in the RAM will be lost when rebooting the
module. The file name must begin with “RAM:”
This document is applicable to Quectel UGxx modules.
1.1. The Process of Using File AT Commands
There are two modes to create, read and write the file in the storage:
1. The file is created and all the content of the file could be uploaded to the storage by command
“AT+QFUPL”. And the content can be outputted/downloaded through the serial interface by
command “AT+QFDWL”.
2. Open the file by “AT+QFOPEN”, then the file can be written or read at any time and any location until
the file is closed by “AT+QFCLOSE”.
When the file is opened by command “AT+QFOPEN”, you can set the file as overwrite mode or
read-only mode or others by the parameter <mode>. (For more information about <mode>, see
Section 2.6). After the file is opened, a <file_handle> is assigned to this file. Then you can
operate this file via this <file_handle>.
After the file is opened, write the file by command “AT+QFWRITE” and read the file by
“AT+QFREAD” from the current file position.
You can set the file position by “AT+QFSEEK” and get the current position by
“AT+QFPOSITION".
“AT+QFTUCAT” will truncate the file from the current position to the end of the file.
Close the file by “AT+QFCLOSE”. Then the <file_handle> becomes meaningless to this file.
There are several commands to manage files in the storage:
1. “AT+QFLDS” gets the storage size.
2. “AT+QFLST” lists files information in the storage.
3. “AT+QFDEL” deletes the file(s).
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 6 / 19
2Description of AT Command
2.1. AT+QFLDS Get the Space Information of the Storage
AT+QFLDS responds the space information of the specified storage.
Parameter
Example
AT+QFLDS="RAM"
+QFLDS: 524288,524288
OK
AT+QFLDS Get the Space Information of the Storage
Test Command
AT+QFLDS=?
Response
OK
Write Command
AT+QFLDS=<name_pattern>
Response
+QFLDS: <free_size>,<total_size>
OK
or
+CME ERROR: <err>
Execution Command
AT+QFLDS
Response
+QFLDS: <free_size>,<total_size>
OK
<name_pattern> Pattern
“RAM” RAM files in the random storage
<free_size> The size of the free space in <name_pattern>
<total_size> The total size of the storage <name_pattern>
<errc> The error code from the module (see the Appendix A)
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 7 / 19
2.2. AT+QFLST List Files
AT+QFLST lists the information of a single file or all files in the required storage medium.
Parameter
Example
AT+QFLST="RAM:*"
+QFLST: "RAM:F_UGxx-1.bmp",56554
+QFLST: "RAM:F_UGxx-10.bmp",56554
+QFLST: "RAM:F_UGxx-11.bmp",56554
OK
AT+QFLST List Files
Test Command
AT+QFLST=?
Response
OK
Write Command
AT+QFLST=<name_pattern>
Response
+QFLST: <file_name>,<file_size>
[+QFLST: <file_name>,<file_size>
[…]]
OK
or
+CME ERROR: <err>
Execution Command
AT+QFLST
Response
Return the information of the RAM files:
+QFLST: <file_name>,<file_size>
[+QFLST: <file_name>,<file_size>
[…]]
OK
or
+CME ERROR: <err>
<name_pattern> The file to be listed
“RAM:*” All the files in RAM
“RAM:<file_name>”The specified file <file_name> in RAM
<file_name> Name of the file
<file_size> Size in bytes of the file
<err> The error code from the module (see the Appendix A)
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 8 / 19
2.3. AT+QFDEL Delete the File in the Storage
AT+QFDEL deletes a single file or all the files in the specified storage.
Parameter
<file_name>The file to be deleted. The max length of <file_name> is 80 bytes
“RAM:*” Delete all the files in RAM
“RAM:<file_name>” Delete the specified file <file_name> in RAM
<err> The error code from the module (see the Appendix A)
2.4. AT+QFUPL Upload File to the Storage
1. AT+QFUPL uploads the file to storage directly. If there is a file in the storage which has the same
name with the file to be uploaded, it will report the error.
2. There are three ways to exit from the transparent transmission mode:
The data uploaded reaches the <file_size>.
The time without any data inputted reaches <timeout>.
When the data is transmitted, the DTR PIN (AT&D1 should be set.) is pulled high or the valid
“+++” is inputted.
3. To prevent the “+++” from being misinterpreted as data, it should comply to the following sequence:
Do not input any character within T1 time (1 second) before inputting “+++”.
Input “+++” during 1s, and no other characters can be inputted during the time.
Do not input any character within T1 time (1 second) after “+++” has been inputted.
The current result “+QFUPL: <upload_size>,<checksum>” is outputted, and the module exits
from the transparent access mode, return OK.
AT+QFDEL Delete the File in the Storage
Test Command
AT+QFDEL=?
Response
+QFDEL: <file_name>
OK
Write Command
AT+QFDEL=<file_name>
Response
OK
or
+CME ERROR: <err>
AT+QFUPL Upload File to the Storage
Test Command
AT+QFUPL=?
Response
+QFUPL: <file_name>[,(1-<free_size>)[,(1-65535)[,(0,1)]]]
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 9 / 19
Parameter
1. It is strongly recommended to use DOS 8.3 file name format for <file_name>.
2. <checksum> is a 16 bit checksum based on bitwise XOR.
If the number of the characters is odd, set the last character as the high 8 bit, and the low 8 bit as 0,
and then use an XOR operator to calculate the checksum. “+++” sequence will cause TA to end the
command and switch to command mode; however, the data previously uploaded will be preserved
into the file.
3. When executing the command, the data must be entered after CONNECT appears.
4. The ACK mode is provided to avoid the loss of data when uploading large files, in case hardware flow
control doesn‟t work. The ACK mode works as follows:
1) RunAT+QFUPL=<file_name>,<file_size>,<timeout>,1 command to enable the ACK mode.
2) The module outputs CONNECT.
3) MCU sends 1K bytes data, and then the module will respond with an „A‟.
OK
Write Command
AT+QFUPL=<file_name>[,<file_size>[
,<timeout>[,<ackmode>]]]
Response
CONNECT
TA switches to the transparent access mode, and the binary
data of file can be inputted. When the total size of the inputted
data reaches <file_size> (unit: byte), TA will return to
command mode and reply the following codes:
+QFUPL: <upload_size>,<checksum>
OK
or
+CME ERROR: <err>
<free_size> The size of the free space in <name_pattern>. Please refer to the “+QFLDS”
<file_name> The name of file to be stored. The max length is 80 bytes
“RAM:<file_name>” The name of file uploaded to RAM
<file_size> The file size expected to be uploaded
Default is 10240. Unit is byte
<upload_size> The actual size of the uploaded data. Unit: byte
<timeout> The delay time in seconds of waiting data to be inputted to USB/UART. Default is 5s
<ackmode> Whether to use ACK mode
0 Turn off the ACK mode by default
1 Turn on the ACK mode
<checksum> The checksum of the uploaded data
<err> The error code from the module (see the Appendix A)
NOTES
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 10 / 19
4) MCU receives this „A‟ and then sends the next 1K bytes data;
5) Repeat step 3) and 4) until the transfer is completed.
2.5. AT+QFDWL Download the File from the Storage
AT+QFDWL downloads the file from the module storage.
Parameter
1. “+++” sequence will cause TA to end the command and switch to command mode.
2. <checksum> is a 16 bit checksum based on bitwise XOR.
AT+QFDWL Download the File from the Storage
Test Command
AT+QFDWL=?
Response
+QFDWL: <file_name>
OK
Write Command
AT+QFDWL=<file_name>
Response
CONNECT
TA switches to data mode, and the bin data of the file will be
outputted. When the file is read over, TA will return to
command mode and reply the following codes:
+QFDWL: <download_size>,<checksum>
OK
or
+CME ERROR: <err>
<file_name> The name of the file to be downloaded. The max length is 80 letters
“RAM: <file_name>” The downloaded file in RAM
<download_size> The size of the downloaded data
<checksum> The checksum of the downloaded data
<err> The error code from the module (see the Appendix A)
NOTES
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 11 / 19
2.6. AT+QFOPEN Open the File
Get the file handle by the “AT+QFOPEN” which is used in other commands, such as “AT+QFWRITE”,
“AT+QFREAD”, “AT+QFSEEK”, “AT+QCLOSE”, “AT+QFPOSITION” and “AT+QFTUCAT”.
Parameter
AT+QFOPEN Open the File
Test Command
AT+QFOPEN=?
Response
+QFOPEN: <file_name>[,(0-2)]
OK
Read Command
AT+QFOPEN?
Response
+QFOPEN: <file_name>,<file_handle>,<mode>
[+QFOPEN: <file_name>,<file_handle>,<mode>
[…]]
OK
Write Command
AT+QFOPEN=<file_name>[,<mode>]
Response
+QFOPEN: <file_handle>
OK
or
+CME ERROR: <err>
<file_name> The file to be operated. The max length is 80 bytes
“RAM: <file_name>” The operated file in the RAM
<file_handle> The handle of the file. The data type is 4 bytes
<mode> The open mode of the file. Default is 0
0 If the file does not exist, it will be created; if the file exists, it will be directly
opened.And both of them can be read and written.
1 If the file does not exist, it will be created; If the file exists, the file will be
overwritten and cleared.And both of them can be read and written.
2 If the file exists, open it and it can be read only. When the file does not exist, it
will respond the error.
<err> The error code from the module (see the Appendix A)
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 12 / 19
2.7. AT+QFREAD Read the File
AT+QFREAD reads the data of the file related to the handle. The data starts from the current position of
the file pointer which belongs to the file handle.
Parameter
2.8. AT+QFWRITE Write the File
AT+QFWRITE writes the data to the file in storage. The data starts from the current position of the file
pointer which belongs to the file handle.
AT+QFREAD Read the File
Test Command
AT+QFREAD=?
Response
+QFREAD: <file_handle>[,<length>]
OK
Write Command
AT+QFREAD=<file_handle>[,<length>
]
Response
CONNECT <read_length>
TA switches to data mode. When the total size of the data
reaches <length> (unit: byte), TA will return to command
mode, display the result and then reply the following codes:
OK
or
+CME ERROR: <err>
<file_handle> The handle of the file to be operated
<length> The length of the file to be read out and the default is the file length
<read_length> The actual read length
<err> The error code from the module (see the Appendix A)
AT+QFWRITE Write the File
Test Command
AT+QFWRITE=?
Response
+QFWRITE: <file_handle>[,<length>[,<timeout>]]
OK
Write Command
AT+QFWRITE=<file_handle>[,<length
>[,<timeout>]]
Response
CONNECT
TA switches to data mode. When the total size of the written
data reaches <length> (unit: byte) or the time, TA will return to
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 13 / 19
Parameter
2.9. AT+QFSEEK Seek the File
Set the current position of the file pointer which belongs to the file handle. This will decide the starting
position of the “AT+QFREAD”, “AT+QFWRITE”, “AT+QFPOSITION” and “AT+QFTUCAT”.
Parameter
command mode and reply the following codes:
+QFWRITE: <written_length>,<total_length>
OK
or
+CME ERROR: <err>
<file_handle> The handle of the file to be operated
<length> The length of the file to be written, the default length is 10K. The range of this
parameter is same with the <free_size> of the “AT+QFUPL”
<timeout> The time of waiting data to be inputted to USB/UART . Default is 5s
<written_length> The actual written length
<total_length> The total length of the file
<err> The error code from the module (see the Appendix A)
AT+QFSEEK Seek the File
Test Command
AT+QFSEEK=?
Response
+QFSEEK: <file_handle>,<offset>[,<position>]
OK
Write Command
AT+QFSEEK=<file_handle>,<offset>[,
<position>]
Response
OK
or
+CME ERROR: <err>
<file_handle> The handle of the file to be operated
<offset> The number of bytes of the file pointer movement
<position> Pointer movement mode. Default is 0
0 The beginning of the file
1 The current position of the pointer
2 The end of the file
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 14 / 19
1. If <position> is 0, and the <offset> exceeds the file size, the command will return ERROR.
2. If <position> is 1, and the total size of the <offset> with the current position of the pointer exceeds the
file size the command will return ERROR.
3. If <position> is 2, the handle will move forth.
2.10. AT+QFPOSITION Get the Offset of the File Pointer
AT+QFPOSITION gets the current position of the file pointer which is relevant to the file handle.
Parameter
2.11. AT+QFTUCAT Truncate the File from the File Pointer
AT+QFTUCAT will truncate all the data behind the position that the file pointer indicates.
<err> The error code from the module (see the Appendix A)
AT+QFPOSITION Get the Offset of the File Pointer
Test Command
AT+QFPOSITION=?
Response
+QFPOSITION: <file_handle>
OK
Write Command
AT+QFPOSITION=<file_handle>
Response
+QFPOSITION: <offset>
OK
or
+CME ERROR: <err>
<file_handle> The handle of the operated file
<offset> The offset from the beginning of the file
<err> The error code from the module (see the Appendix A)
AT+QFTUCAT Truncate the File from the File Pointer
Test Command
AT+QFTUCAT=?
Response
+QFTUCAT: <file_handle>
NOTES
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 15 / 19
Parameter
2.12. AT+QFCLOSE Close the File
AT+QFCLOSE closes the file and ends the operation to the file. The file handle is released and should not
be used again, unless open the file again with “AT+QFOPEN”.
Parameter
OK
Write Command
AT+QFTUCAT=<file_handle>
Response
OK
or
+CME ERROR: <err>
<file_handle> The handle of the operated file
<err> The error code from the module (see the Appendix A)
AT+QFCLOSE Close the File
Test Command
AT+QFCLOSE=?
Response
+QFCLOSE: <file_handle>
OK
Write Command
AT+QFCLOSE=<file_handle>
Response
OK
or
+CME ERROR: <err>
<file_handle> The handle of the operated file
<err> The error code from the module (see Appendix A)
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 16 / 19
3Example
3.1. Upload and Download Files
3.1.1. Upload the File
3.1.1.1. Non ACK Mode
AT+QFUPL="RAM:test1.txt",10 //Upload the text file “RAM:test1.txt” to RAM.
CONNECT
<input file bin data>
+QFUPL: 10,613e //Get the bytes of the uploaded data and the checksum.
OK
3.1.1.2. ACK Mode
The ACK mode can make the data transmission more reliable. When transmitting the large file without
hardware flow control, the ACK mode is used to prevent the data from being lost. About the ACK mode,
please refer to the details of “AT+QFUPL”.
AT+QFUPL="RAM:test.txt",3000,5,1 //Upload the text file “RAM:test.txt” to RAM.
CONNECT
<input file bin data of 1024bytes>
A//After receiving 1024bytes data, the module will respond
an “A”, then next 1024 bytes data can be inputted.
<input file bin data of 1024bytes>
A
<input the rest file bin data>
+QFUPL: 3000,B34A
OK
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 17 / 19
3.1.2. Download the File
AT+QFDWL="RAM:test.txt" //Download the text file “RAM:test.txt” from RAM.
CONNECT
<Output Data>
+QFDWL: 10,613e //Get the bytes of the downloaded data and the checksum.
OK
3.2. Write and Read the File
3.2.1. Write and Read RAM File
AT+QFLDS="RAM" //Query the space information of RAM.
+QFLDS: 524288,524288
OK
AT+QFOPEN="RAM:1",0 //Open the file in the RAM.
+QFOPEN: 3000
OK
AT+QFWRITE=3000,10 //Write 10 bytes to the file.
CONNECT
<Write Data>
+QFWRITE: 10,10 //The actual written bytes and the size of the file are returned.
OK
AT+QFSEEK=3000,0,0 //Set the file pointer to the beginning of the file.
OK
AT+QFREAD=3000,10 //Read the data.
CONNECT
<Read Data>
OK
AT+QFCLOSE=3000 //Close the file.
OK
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 18 / 19
4Appendix A Summary of <err> Code
The result of the final error code is “+CME ERROR: <err>”. <err> indicates an error relating to the ME or
Network. The operation is similar to Error result code. It will be returned when some definition error
happens. The <err> codes listed here are just related to UGxx module of the File.
Table 1: Summary of Error Code
<err>
Meaning
400
invalid input value
401
larger than the size of the file
402
read zero bytes
403
drive full
405
file not found
406
invalid file name
407
file already exists
409
fail to write the file
410
fail to open the file
411
fail to read the file
413
reach the max number of file allowed to be opened
414
the file read-only
416
invalid file descriptor
417
fail to list the file
418
fail to delete the file
419
fail to get disk info
Quectel
Confidential

UMTS/HSPA Module Series
WCDMA UGxx FILE AT Commands Manual
WCDMA_UGxx_FILE_AT_Commands_Manual Confidential / Released 19 / 19
420
no space
421
time out
423
file too large
425
invalid parameter
426
file already opened
Quectel
Confidential