I2C SPI Custom Script Programming [TUTORIAL & EXAMPLES]

[ArT]

One of the new features in v1.6 is Custom Script Programming tool for I2C or SPI bus. In this tutorial I'll describe what is it, how to use it and example of use. I'll also share few example scripts for REVELPROG-IS.

What is I2C SPI custom script programming in REVELPROG-IS?

Custom script programming for I2C or SPI bus in case of REVELPROG is a some kind of "bus pirate" tool for serial communication. This tool is still in developement phase but it is already powerful and functional. With REVELPROG-IS Customs Script tool there is possibility to execute any commands in any sequence with precise delays on SPI or I2C bus. You can write script to execute commands for unclocking device, read and write hidden (or not) registers, change sector protection bits, write OTP registers and much more.

In practice it is also very useful tool for electronic enginners and embedded programmers, because there is possibility to communicate with any serial (I2C or SPI) device. External device or module can be also powered from REVELPROG-IS (1.0 - 5.0V with 0.1V threshold). Only few connection lines are required for communication (4 wires for SPI or 2 wires for I2C + optional 2 wires for external device power supply).

CustomScriptProgrammingI2cSPIrevelprog.jpg (61.35 KiB) Viewed 22650 times

Script construction

Typical script consists of:

• script header - information about software version,
• hardware settings - voltage selection (VPP), bus selection (I2C/SPI) and communication speed,
• operations (1 to n).

Each operation constists of:

• operation parameters: number of bytes to read/write, delay settings,
• instruction- sequence of bytes for single instruction,
• data to write (optional) - sequence of optional bytes for write after single instruction

Each script has to have at least one operation defined

Example construction of typical script with header (software version v.1.6.0), hardware settings (SPI bus, 3.3V voltage, slowest speed) and single operation with 1-byte 9Fh command.

Code: Select all

// example script construction
#SCRIPT HEADER;
SCRIPT:v1.6.0;
#HARDWARE SETTINGS;
HW:SPI,3.3V,SLOW;
#OPERATION;
SW:0,0,1,3,5,5,10,0,100,1000;
INSTR:9F;


Script syntax:

• hash character "#" defines sections, e.g. #SCRIPT HEADER; (header), #HARDWARE SETTINGS; (hardware settings), #OPERATION; (for each operation),
• semicolon ";" placed at the end of each command,
• colon ":" placed directly after command words, e.g. SCRIPT: (script version), HW: (hardware settings), SW: (software settings - operation parameters), INSTR: (instruction), DATA: (write data);
• comma "," separates parameters for each command (eg. between "INSTR:" and ";" comma separates instruction bytes)
• double slash "//" precedes comments which are ignored by script executor

Script maker

Script maker will help you prepare multiple operations with correct syntax.

ScriptMaker.jpg (69.04 KiB) Viewed 22650 times

Software settings for single instruction:

• WREN (Write Enable) + number of bytes to write in single operation,
• RDEN (Read Enable) + number of bytes to read in single operation,
• DBO (Delay Before Operation) - optional delay in miliseconds before operation,
• DAI (Delay After Instruction) - optional delay in miliseconds after instruction,
• DAW (Delay After Write) - optional delay in miliseconds after write,
• DAO (Delay After Operation) - optional delay in miliseconds after operation,
• BSYO (Busy Operation) - maximum time in miliseconds for write end (e.g. maximum wait time for busy flag in FLASH SPI or for ACK in I2C devices)
• TOUT (Timeout) - maximum PC timeout in miliseconds for operation end (it is recommended to set timeout greater than sum of all other delays).

Operation code generated by script maker from above example::

Code: Select all

#OPERATION;
SW:0,0,1,3,5,5,10,0,100,500;
INSTR:9F;


As you can see SW parameters are equal to script maker parameters:

Code: Select all

SW:WREN[0-1], WriteLength[0-255], RDEN[0-1], ReadLength[0-255], DBO[0-250], DAI[0-250], DAW[0-250], DAO[0-250], BSYO[0-n], TOUT[0-n];

Please note that:
- read and write length are 0 based (0 means 1 byte, 255 means 256 bytes)
- with WREN = 0 writelength is ignored, with RDEN = 0 readlength is ignored.
- "SW:" and "HW:" byte format is decimal
- "INSTR:" and "DATA:" byte format is hexadecimal

edit: please check scriptmaker changes since v1.8.5 (possibility to repeat operations and import data from buffer):
viewtopic.php?f=32&t=280&p=3657#p3657

Script execution sequence

1. SET HW (BUS, VPP, SPEED)
2. EXECUTE OPERATION 1 (SET SW -> DBO -> INSTR -> DAI -> WRITE -> DAW -> BSYO -> READ -> DAO)
3. EXECUTE OPERATION 2
4. ...
5. EXECUTE OPERATION N
6. RESET HARDWARE

Remarks

Script execution is not immune for syntax error at the moment - you should check syntax carefuly before execution because you may be not informed about execution errors and program may be unstable. Please remember about all syntax elements

In next posts I'll show few script examples.

[ArT]

Let's start with easy example such as read device ID (JEDEC) for FLASH SPI device. In script maker description we have generated single operation with 1-byte "9F" instruction and read length of 4 bytes - this is exactly JEDEC instruction for FLASH SPI. In this example we will only change VPP voltage to 2.6V because it is safer for reading unknown chip. VPP = 2.6V will be safe in case of low voltage 1.8V chip (it should not damage it) and - in most cases - it should be enough to read id for 3V device (it may not be enough for write operations).

Read ID (JEDEC) for FLASH SPI:

Code: Select all

#SCRIPT HEADER;
SCRIPT:v1.6.0;

#HARDWARE SETTINGS;
HW:SPI,2.6V,SLOW;

// Read ID (JEDEC) for FLASH SPI
#OPERATION;
SW:0,0,1,3,5,5,10,0,100,1000;
INSTR:9F;


After script execution the device will read 4 bytes of data (it is JEDEC ID):

Result-of-read-JEDEC-ID-of-W25Q64.jpg (17.87 KiB) Viewed 22647 times

Please take a look at Winbond W25Q64FV datasheet (page 21)

W25Q64FV_JEDEC.jpg (45.52 KiB) Viewed 22647 times

First byte is manufacturer ID (EFh means Winbond), second byte is device family (40h means W25Q... family) and third byte means device capacity (17h means 64Mbit device). Fourth byte 00h is not supported by Winbond (it is extended device id used by some manufacturers).

Read SR1 and SR2 registers for FLASH SPI:

Code: Select all

#SCRIPT HEADER;
SCRIPT:v1.6.0;

#HARDWARE SETTINGS;
HW:SPI,2.8V,SLOW;

// Status Register 1 Read
#OPERATION;
SW:0,0,1,0,5,5,0,0,100,500;
INSTR:05;

// Status Register 2 Read
#OPERATION;
SW:0,0,1,0,5,5,0,0,100,500;
INSTR:35;

We have changed instruction from "9F" to "05" and set only 1 byte length for read to read single byte SR1 register. For SR2 we need to change instruction byte code to "35" (other parameters are the same)

W25Q64CV_instructions.jpg (166.91 KiB) Viewed 22647 times

As a results we read 2 bytes: 00 (SR1 register) and 02 (SR2 register)

W25Q64FV_SR1_SR2_values.jpg (16.84 KiB) Viewed 22647 times

hexadecimal 00h is euqal to binary 00000000b
hexadecimal 02h is euqal to binary 00000010b
and it means that device has enabled QSPI mode (QUAD SPI) because S9 bit is set (1):

W2564CV_SR1_SR2_QSPI.jpg (81.43 KiB) Viewed 22647 times

Write SR2 register for FLASH SPI:
Let's say we need to disable QSPI mode. We need to change SR2 register (reset S9 bit). For Winbond W25Q series there is required to write SR1 and SR2 registers in single operation to success (please check device data sheet page 28 - Write Status Register (01h)).
For other devices procedure may be different so there is always required to check details in datasheet for specific device.

Code: Select all

//Winbond W25.. (64Mbit+) disable QUAD SPI
#SCRIPT HEADER;
SCRIPT:v1.6.0;

#HARDWARE SETTINGS;
HW:SPI,2.8V,SLOW;

// WRITE ENABLE (06h)
#OPERATION;
SW:0,0,0,0,5,5,0,0,100,500;
INSTR:06;

// WRITE STATUS REGISTER 1&2 (01h + REG1 + REG2)
#OPERATION;
SW:0,0,0,0,5,5,10,0,100,500;
INSTR:01,00,00;

// READ STATUS REGISTER 2 (35h)
#OPERATION;
SW:0,0,1,0,5,5,0,0,100,500;
INSTR:35;

At the beginning we use WREN (Write Enable - 06h) command to unlock registers for write. In next operation we execute Write Status Register (01h) command with additional 2 bytes: SR1 (00h) value and SR2 (00h) value. At the end we read SR2 to verify operation (it should read new value SR2 = 00h).

That's it! There are simple examples, but as you can see, there is need to read device datasheet carefully to get knowledge about device commands and instructions. Please feel free to ask if you will have any questions or need help - our support will help you write a script for a specific not typical operation for any device.

[ArT]

Read SFDP data table for FLASH SPI

Code: Select all

#SCRIPT HEADER;
SCRIPT:v1.6.0;

#HARDWARE SETTINGS;
HW:SPI,2.8V,SLOW;

// SFDP 256 Byte table read (5A + 3B start addr + dummy byte + 256B read)
#OPERATION;
SW:0,0,1,255,5,5,0,0,100,500;
INSTR:5A,0,0,0,0;

Results for Spansion S25FL512SA (512Mbit FLASH SPI 3V):

S25FL512A_SFDP_Register.jpg (158.18 KiB) Viewed 22647 times

[Pityu]

Hello !

My knowledge is limitation, i try to make custom script for read/enable/disable Quad SPI, not sure watt i'm doing.

I have GD25Q128 (25Q128CVIG) to play with, and it is not fun
Datasheet: http://www.elm-tech.com/en/products/spi ... 25q128.pdf
For read I make this script:

#SCRIPT HEADER;
SCRIPT:v1.6.1;
#HARDWARE SETTINGS;
HW:SPI,2.8V,SLOW;
#OPERATION;
SW:0,0,1,0,5,5,10,0,100,500;
INSTR:35;

After execute I have 00 (it loook quad is disable)

what I have to change for make quad enable?

// WRITE STATUS REGISTER 1&2 (01h + REG1 + REG2)
#OPERATION;
SW:0,0,0,0,5,5,10,0,100,500;
INSTR:01,00,00;

[ArT]

This is good question - GD25Q128 has not typical status register map (page 20 in datasheet)

GD25Q128_status_register.jpg (80.63 KiB) Viewed 22402 times

QE bit.
The Quad Enable (QE) bit is a non-volatile Read/Write bit in the Status Register that allows Quad operation.
When the QE bit is set to 0 (Default) the WP# pin and HOLD#/RESET# pin are enable. When the QE pin is set
to 1, the Quad IO2 and IO3 pins are enabled.

QuadEnable (QE) is bit 9 (S9).
S9 is placed in Status Register 2 (S15-S8).
You can read it with 35h command:

GD25Q128_commands.jpg (105.95 KiB) Viewed 22402 times

So your read instruction is correct.
00h means that all bits (S15-S8) are zeros, so QE is disabled also.

To enable QE you need to set S9 to "1"
So Status Register 2 (S15-S8) should has binary value 0000 0010, which is 0x02 in hex (you can use windows calculator for conversion between binary and hex if you not familiar with that).

So you need to write 0x02 to Status Register2.
Write Status Register 2 command is 31h (table above).

But, here is the tricky. Before you write status register you need to unlock the device (write enable command)
You can use slightly modified example from 2nd post:

Code: Select all

#SCRIPT HEADER;
SCRIPT:v1.6.1;

#HARDWARE SETTINGS;
HW:SPI,2.8V,SLOW;

// WRITE ENABLE (06h)
#OPERATION;
SW:0,0,0,0,5,5,0,0,100,500;
INSTR:06;

// WRITE STATUS REGISTER 2 (31h + register value)
#OPERATION;
SW:0,0,0,0,5,5,10,0,100,500;
INSTR:31,02;

// READ STATUS REGISTER 2 (35h)
#OPERATION;
SW:0,0,1,0,5,5,0,0,100,500;
INSTR:35;

Crucial part is "INSTR:31,02;", first byte is instrucion command (31h is write status register 2 for this memory), and second byte is your new register value (02h).

PS. At the end I added read status register 2 (35h) to verify operation (it should read new SR2 value - 02h in this case if operation success) but it is not required and you can read it using other script.

PS2. In this way you can modify any bit in status registers (SR1/SR2/SR3) you want (you have 24 configuration bits in total)

[Pityu]

Hi ArT, thanks for answer.
Your script work perfect, mine is not. I think I don't know to set write operation in script maker.
Mine is: "SW:0,0,1,0,5,5,0,0,100,500;"
and yours is: "SW:0,0,0,0,5,5,10,0,100,500;"

Code: Select all

#SCRIPT HEADER;
SCRIPT:v1.6.1;
#HARDWARE SETTINGS;
HW:SPI,2.8V,SLOW;
#OPERATION;
SW:0,0,1,0,5,5,10,0,100,500;
INSTR:06;
#OPERATION;
SW:0,0,1,0,5,5,10,0,100,500;
INSTR:31,02;
#OPERATION;
SW:0,0,1,0,5,5,10,0,100,500;
INSTR:35;

Can you help?
......
I figure it out!
For write comand, the script maker I leave it default. Nothing to check.

Thanks!

[ArT]

The difference is that I used instruction command only:

Code: Select all

#OPERATION;
SW:0,0,0,0,5,5,10,0,100,500;
INSTR:31,02;

It is possible to use up to 16 bytes as instruction (INSTR command) without additional DATA command (write enabled = 0).

The same effect with DATA command (write enabled = 1) will be:

Code: Select all

#OPERATION;
SW:0,0,1,0,5,5,10,0,100,500;
INSTR:31;
DATA:02;


Please note "DATA:" command line after "INSTR:" line.
3rd parameter in SW parameters is "WRITE ENABLE" (= 1), write length (4th parameter) is 0 fixed so 0 means 1 byte to write (and 255 means 256). When you use write enable than "DATA:" command is required in operation.

It may be confusing but I hope that it is clear now.
If you will have any further questions please ask.

[kissubin]

good information!!!

[CoraDias]

Hi...i am new to this. As per my knowledge the Control Center Serial Software supports XML-based batch scripts, which you can use with the Aardvark I2C/SPI Adapter. With this feature, you can create, run, and save custom batch scripts to automate your tasks. The scripting language supports I2C, SPI, and GPIO functions.

assembly circuit board

[ArT]

At the moment CS tool in REVELPROG-IS is not for task automation - it is used to change custom registers, lock protections, OTP registers etc. How would you like automate your tasks? Please write an example step by step - maybe we can add such feature.