Nextion Upload Protocol (v1.2)

Many customers use the Nextion display in their own business projects. They may need to upload the Nextion TFT file through their own MCU or PC. Here we disclose additional considerations to the Upload Protocol for more recent versions of the Nextion Editor. The Upload Protocol is an advanced technique. Understanding the Upload Protocol is not a requirement if you only upload your TFT files through the Nextion Editor or by microSD.

Historical

v1.0] The Original Nextion Upload Protocol was publicly released by Itead on 2016.05.19 coinciding with the 2016.05.12 release of Nextion Editor v0.35. The original was copied to preserve on nextion.tech as the Nextion HMI Upload Protocol. Due to post times and upgrades, the post date vs Original Release Date gets fudged or lost.

v1.1] With the introduction of advanced techniques Protocol Reparse Mode and Address Mode in Nextion Editor v0.53 (released 2017.12.07) the Nextion HMI Upload Protocol v1.1 was released.

v1.2] With the introduction of the Nextion Intelligent Series, the Nextion Editor v0.58 adds 6 new supported baud rates (MIDI:31250, 230400, DMX512:250000, 256000, 512000 and 921600) not previously supported in v0.53 and prior. The Editor also silently implemented an alternate upload skip mode making upload times faster. These are now-to-be-documented as the Nextion Upload Protocol v1.2. (this document).

for each Serial port
 for each baudrate
  change to baudrate  
  send connect
    wait for connect's comok
    if comok then break // found
  pause between baud changes

for each Serial port
  for each baudrate
    change to baudrate  
    send protocol reparse abort
    send address_broadcast connect
      wait for connect's comok
      if comok then break // found
    send connect
      wait for connect's comok
      if comok then break // found
    pause between baud changes

<v0.53: comok 1,30601,NX3224T028_011R,62,61488,DE686D7A37B1C31,4194304ÿÿÿ 
v0.53+: comok 1,37671-0,NX4024K032_011R,99,61489,E46720857602B29,16777216ÿÿÿ
v0.58+: comok 1,1073-815,NX4827P043_011R,276,10501,81F0330C21CEC37,131072000-0ÿÿÿ

  // pre Intelligent Series no whmi-wris
  int32_t filesize=(size of TFT file);
  int32_t baudrate=upload_baud;
  int32_t outbufsize=32;
  int32_t full=filesize/4096;
  int32_t partial=filesize%4096;
  int32_t subs=4096/outbufsize;
  int32_t lastsubs=partial/outbufsize;
  int32_t finalsub=fsize%outbufsize;
  uint16_t i, j;


  send whmi-wri filesize,baudrate,A
  change to baudrate: then wait_for_05
  // full chunks only: no skip <= v0.53
  for(i=0;i<full;i++) {
    for(j=0;j<subs;j++) {
      read_sub()
      send_sub()
    }
    wait_for_05    
  }
  if(partial > 0) {
    for(j=0;j<lastsubs;j++) {
      read_sub()
      send_sub()
    }
    if(finalsub>0) {
      read_finalsub()
      send_finalsub()  
    }
    wait_for_05
  }

  // v0.58 and forward has whmi-wris
  int32_t filesize=(size of TFT file);
  int32_t baudrate=upload_baud;
  int32_t outbufsize=32;
  int32_t full=filesize/4096;
  int32_t partial=filesize%4096;
  int32_t subs=4096/outbufsize;
  int32_t lastsubs=partial/outbufsize;
  int32_t finalsub=fsize%outbufsize;
  uint16_t i, j;
  uint32_t offset;

  send whmi-wris filesize,baudrate,A
  change to baudrate: then wait_for_05
  for(j=0;j<subs;j++) {
    read_sub()
    send_sub()
  }
  offset=4096
  resp=wait_for_05_or_08
  if (resp==0x08) {
    offset=read_offset()
    repos_to_offset()
  }
  skip=offset/4096
  for(i=skip;i<full;i++) {
    for(j=0;j<subs;j++) {
      read_sub()
      send_sub()
    }
    wait_for_05    
  }
  if(partial>0) {
    for(j=0;j<lastsubs;j++) {
      read_sub()
      send_sub()
    }
    if(finalsub>0) {
      read_finalsub()
      send_finalsub()  
    }
    wait_for_05
  }

Discussion and Edge cases

We can not have a super complete Protocol description without mentioning the known outlying edge cases. Many have already been addressed above. Most of the outlying edge cases are either now mostly historical, or are easily overcome when fully understood.

Most pandemic and post pandemic devices (visually identified by a QR code on the microSD slot) cannot revert back to versions before 1.62.2 because the firmware prevents a scenario that would brick the Nextion device (prior version are static snapshots and are not programmed for the alternate ICs). Versions from v0.53 and prior lacked the highspeed baudrates, the resource skip that speeds development up, and the anti-aliased variable width fonts. Most simply wouldn’t and now couldn’t choose the more rustic versions. Reverting back to prior Nextion Editor versions is now mostly out of curiosity and therefore a historical case.

Nextion devices that had set their power on default operational baud rate to one of the supported baud rates will need to have these baud rates included in a modified Upload v1.1. ie: bauds=921600 and then reverting to a v0.38 Editor that does not support 921600 would need to have the Nextion bauds set back to 115200 or below before attempting v0.38.

Starting with the Nextion Editor v0.38 (released 2016.08.16) to avoid crucial bugs Nextion devices can no longer revert to prior versions once the device has been updated to versions v0.38 and forward.

Legacy devices (2015-2016 with Itead logo) required to either progress naturally version to version as versions were released or it could cause an Device NULL or Illegal Model error. The fix was a special LegacyFix.tft only useful for these legacy devices with this specific issue and only needed the one-time. While this fix was later integrated into versions v0.51 and v0.52, discovering a never updated legacy Nextion stashed in a drawer may not be aware of the future upcoming fix. Newer devices with the Nextion logo are NOT Legacy.

Basic and Enhanced models (pre-pandemic) before 2019: While the most natural progression would have been version to version as versions were released, large jumps between versions prevented some devices from utilizing the newer Editors TFTs (v0.58 and later) without an intermediary TFT file to bridge the gap. Example when going from super old TFTs to new (ie: v0.33 and prior to v1.60.0). This issue can only can effect the Basic T Series and Enhanced K Series models (other models had not yet been created in v0.53 and before). While the fix was to use a one-time intermediary TFT created with v0.42 to bridge this gap, then devices without this intermediary could fall fate if reverting back to early versions before v0.42 and then jumping to much newer versions. Once an intermediary TFT has been used on a device, this issue has been fixed and goes away making it only needed the one-time.

Pandemic Global IC shortages and alternate ICs. Pre-pandemic devices used what I will refer to as the original ICs and Editor versions before v1.62.2 only knew of and how to communicate with their one IC. The pandemic and its upcoming global supply chain effect was not something that could be foreseen. However, Pandemic supply shortages created the need for most to use alternate second sourcing ICs to keep going. As a result, the post pandemic Nextion Editors are programmed so devices can communicate with both the original ICs and the alternative ICs starting near v1.62.2 (with v1.63.3 strongly recommended). The Nextion devices with alternate ICs are prevented from using a pre-pandemic TFT that would not be able to communicate with its alternate IC and therefore prevent bricking the device. What this means for your upload is that you should avoid elder TFT files for your post pandemic displays and pay strict attention to what TFT files you are attempting to upload. If a TFT File gets the “File is too old” or “Data Error” message, this is the likely reason as stated in the FAQs. The solution is to compile the elder HMI project with a newer version of the Nextion Editor (v1.63.3 and up strongly recommended) so that the TFT file is no longer too old or at risk of rejection. NOTE: Pandemic and post pandemic Nextion devices can be visually identified by these devices having a QR code on their microSD card slot.

With most users using a Nextion Editor version v1.63.3 and up and newer devices being post-pandemic (preventing early TFT versions), the issue of needing an intermediary is mostly now Historical.

Three cases would cause the instruction to be taken as data and not an instruction
(a) You are in the middle of an upload using addt, wept or twfile instructions
(b) Protocol Reparse is active has not been aborted
(c) Addressing Mode is active and address is not broadcast

Both Address Mode and Protocol Reparse Mode are advanced techniques and should not be used if not fully understood.  However, additional considerations are needed in the Upload Protocol should any of these advanced techniques be used. Ensure you have returned to normal Nextion Instruction Set default serial handling mode before beginning an Upload.

If you are using Transparent Data Mode for the addt instruction (Bulk update of Waveform Data points) or the wept instruction (Bulk update for storing EEPROM bytes) then as there is no abort for these instructions, attempting the Nextion Upload Protocol in the middle these uploads would cause all or part of your Nextion Upload instructions to be consumed as their data until their specified number of bytes has been satisfied. You must therefore wait until they are finished.

If you are using the twfile Packet Mode for uploading files via the twfile instruction and are in the middle of an upload then: while there is an abort packet to escape the upload without completion, the file upload would be deemed lost and need to be re uploaded at another time. The twfile abort packet is a constant of 12 bytes following a minimum of a 20ms period of no packets. Alternatively, wait for the twfile upload to be completed.

uint8_t twAbort[12] = {49,161,187,68,247,255,254,0,255,255,0,0};
delay(25);
Serial2.write(twAbort,12);

Clearing the Instruction Buffer. If you have stray bytes or a partial instruction in the instruction buffer, you can clear it. As Nextion processes its Serial Buffer for the contents preceding an instruction termination, then sending an instruction termination will effectively clear Nextion’s Serial Buffer and be cleanly ready for your next instruction. We can toss in a null byte for good measure.

uint8_t cleanStart[4] = {0,255,255,255};
Serial2.write(cleanStart,4);

If you have Protocol Reparse Mode active (recmod=1) then attempting to send instructions would be consumed and swallowed up by the Protocol Reparse mode as data and not be processed as your intended instructions. Therefore, we would need to abort Protocol Reparse Mode with its specialized 27 byte sequence Protocol Reparse Abort (sets recmod=0)

uint8_t ndt[3] = (255,255,255);
Serial2.print("DRAKJHSUYDGBNCJHGJKSHBDN"); // send as text
Serial2.write(ndt,3); // send 3 bytes of termination from ndt array as bytes.

If you have Address Mode active where the Nextion device’s address is valid (addr>=256)&&(addr<=2815) and not 0 (off) then the Nextion device will ignore all instructions that are not either on its specific address (meant for this Nextion) or on the Broadcast address (meant for all Nextions receiving). To send an instruction specifically for a Nextion with address of 1987, then its two byte address is prepended to the instruction (1987 as bytes in little endian order is 0xC3 0x07). Alternatively, without yet knowing the address of our Nextion device we can use the broadcast address of 65535 which in little endian is the two bytes 0xFF 0xFF). With Protocol Reparse Mode disabled in a previous step we are ready to look for the connect string reply by sending the connect instruction on the broadcast address

uint8_t ndt[3] = {255,255,255};
Serial2.write(ndt,2); // send 2 bytes from ndt array as bytes (our 0xFF 0xFF Address
Serial2.print("connect"); // send out connect instruction as ascii text
Serial2.write(ndt,3); // send 3 bytes from ndt array as bytes to terminate (our 0xFF 0xFF 0xFF);

Not all USB-to-TTL Serial Adapters or MCU UART ports have large 4096 byte buffers. Some are limited and it can be easy to overflow their TX buffers on their way to the Nextion. As such the pseudo code described above provided for an outbufsize to send a 4096 byte chunk in smaller more manageable sub-chunks. outbufsize should be a 2’s compliment (16, 32, 64, 128, 256, 512, 1024, 2048 or 4096). Another consideration would be to allow that sub-chunk to clear the TX buffer before reloading it with more data, this is generally accomplished by a serial.flush() or waiting until the UARTs txempty event has triggered. Your implementation would be specific to your MCU, your programming language, and your compiler.

These should be respected for an always successful Upload Experience.