Read File

What is the Read File node in Node-RED?

The Read File node in Node-RED is used to read the contents of a file from the file system. In FlowFuse Cloud, the Read File node interacts with a cloud-based storage solution, leveraging AWS S3 for file storage. However, in the Node-RED instance running on edge devices using FlowFuse device agent, this node will read the file from the device's local file system. The Read File node can read both string and binary buffer data, making it versatile for various integration needs within Node-RED flows.

Configuring the Read File node

  • Filename: Specify the filename.
    • Path: Define the path to the file that needs to be read.
    • msg: Use a message property to dynamically set the filename. By default, it will use msg.filename. If msg.filename is used, the file will be closed after every write. For optimal performance, consider using a fixed filename.
    • Expression: Utilize a JSON expression to dynamically set the filename based on data in the flow.
    • Environment Variable (env var): Utilize an environment variable to dynamically set the filename.
  • Output Format:
    • Single UTF string: Output the file contents as a single UTF-8 string.
    • A message per line: Output each line of the file as a separate message.
    • A single buffer object: Output the contents of the file as a single buffer object.
    • A stream of buffers: Output the contents of file as chunks of buffers. The chunk size being operating system dependant, but typically 64k (Linux/Mac) or 41k (Windows).
  • Include all existing properties in each msg: When enabled, all existing properties in the input message (msg) will be included in each output message generated by the node.
  • Encoding: Specify the encoding format to use when reading the file if the output format is set to string.

Tip: Always use an absolute path for the filename to ensure Node-RED can accurately locate and manipulate the specified file.

Output

  • payload: The contents of the file as either a string or binary buffer.
  • filename: If not configured in the node, this optional property sets the name of the file to be read.

Usecases

  1. Configuration Loading: Read configuration files containing parameters or settings for your Node-RED flows or applications. This allows you to dynamically adjust the behavior of your flows without modifying the flow structure.
  2. Data Aggregation: Read multiple data files and aggregate their contents into a single message or dataset for further processing or analysis. This can be useful for tasks like combining multiple CSV files into a unified dataset.
  3. System Monitoring: Read system log files or status reports to monitor the health and performance of various components within your system. You can then analyze this data within Node-RED to trigger alerts or perform diagnostics.
  4. Content Parsing: Read files containing structured data formats, such as XML or JSON, and parse their contents within Node-RED to extract relevant information. This can be useful for tasks like extracting data from API responses or parsing configuration files.
  5. File Transformation: Read files in one format and transform their contents into a different format using Node-RED's processing capabilities. For example, you can read a CSV file and convert its contents into JSON format for further processing or visualization.
  6. External Integration: Read data from files generated by external systems or services and integrate this data into your Node-RED flows for further processing or action. This can facilitate interoperability between different systems or applications.
  7. File Monitoring: Continuously monitor files for changes or updates using the Read File node, triggering flows or actions based on the detected changes. This enables real-time processing of file-based events within your Node-RED application.
  8. Data Backup and Recovery: Read files containing backup data or snapshots and use Node-RED to manage and automate backup and recovery processes.

Examples

  1. In the example flow, we demonstrate how to read the file content using the Read File node and obtain the output as a string.
  1. In the example flow, we demonstrate how to read the file content using the Read File node and obtain the output as a buffer object.

Node help

This is the Read File node's built-in help, mirrored from the Node-RED project. It is the same text the editor shows in its Info sidebar.

Reads the contents of a file as either a string or binary buffer.

Inputs

filename string
The name of the file to be read can be provided in the node configuration, or as a message property. By default it will use msg.filename but this can be customised in the node.

Outputs

payload string | buffer
The contents of the file as either a string or binary buffer.
filename string
If not configured in the node, this optional property sets the name of the file to be read.

Details

The filename should be an absolute path, otherwise it will be relative to the working directory of the Node-RED process.

On Windows, path separators may need to be escaped, for example: \\Users\\myUser.

Optionally, a text file can be split into lines, outputting one message per line, or a binary file split into smaller buffer chunks - the chunk size being operating system dependant, but typically 64k (Linux/Mac) or 41k (Windows).

When split into multiple messages, each message will have a parts property set, forming a complete message sequence.

Encoding of input data can be specified from list of encodings if output format is string.

Errors should be caught and handled using a Catch node.