Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


dash7_mode_2:alp_file

File Access ALP

The filesystem is a fundamental part of DASH7 Mode 2 that provides data interoperability and security, so the DASH7 Mode 2 specification defines a consistent, interoperable Application Layer Protocol (ALP) for accessing the filesystem.

Access Limitations

If a requested file’s permissions are beyond those granted to the user invoking the command, this file’s data and headers will not be accessible. Execution of the command will cease at the point of permission conflict, and and error will be generated. However, data accessed prior to the error will be processed and returned, if a return is required.

File ALP Protocol Format

File ALP data should follow the basic M2ALP structure. Below is what a File ALP header should look like.

M2ALP Header for File Access
Flags Record Length ALP ID ALP Command ALP Payload
1 Byte 1 Byte 1 Byte 1 Byte N-4 Bytes
(normal usage) (N) 0x01 (0x00-FF) (see below)

Commands for File ALP

The File Access ALP supports a structured Command field.

File ALP Command Field
b7 b6 b5 b4 b3 b2 b1 b0
Respond File Block Operand

Respond Bit Field

The respond bit field follows the normal definition. If it is set, the ALP command should be followed by a response. The type of response depends on the command, and it is defined for each operand type of the File ALP.

File Block

File Block ID DASH7 Block Accessed
0 None (Reserved)
1 GFB
2 ISFSB [Series Block]
3 ISFB
4-7 None (Reserved)

Operand

Operand ID DASH7 Block Accessed
0 Read File Permissions
1 Return File Permissions
2 Unused
3 Write File Permissions
4 Read File Data
5 Return File Data
6 Unused
7 Write File Data
8 Read File Headers
9 Return File Headers
10 Delete File (optional)
11 Create New File (optional)
12 Read File Header + Data
13 Return File Header + Data
14 Restore File (optional)
15 Return Error

Payload Data for File ALP

The File ALP Payload Data is dependent on the opcodes, which are examined below.

Opcodes & Command Payloads for File Data ALP

Each File ALP record must contain an opcode, and therefore the payload must be in a format specific to that opcode. Some of the opcodes allow batch input of payload. For these, there is a payload template that can be repeated one or more times. This is especially useful if you want to read data from a list of files, and you only want to send one command.

File Permissions Operands

File permissions are part of the DASH7 filesystem. Each file — a GFB File, ISFSB File, or ISFB File — has a file permissions byte. File permissions may be read or written as record data according to the template shown below. Writes to file permissions have no response, apart from errors.

If Respond bit is set:
Read File Permissions results in response: Return File Permissions
Return File Permissions results in response: Nothing
Write File Permissions results in response: Return Error

Fields:
File ID: (1 Byte) GFB File ID, ISFSB File ID, or ISFB File ID
Permissions: (1 Byte) Number of bytes to read/write after offset

File Permissions Pair
File ID Permissions
1 Byte 1 Byte
Read File Permissions Payload Block
File ID 1 File ID 2 File ID M
1 Byte 1 Byte 1 Byte
Return & Write File Permissions Payload Block
File Perm Pair 1 File Perm Pair 2 File Perm Pair M
2 Bytes 2 Bytes 2 Bytes

File Data Operands

File data from GFB Files, ISFSB Files, or ISFB Files may be read or written as ALP record data according to the templates shown below.

If Respond bit is set:
Read File Data results in response: Return File Data / Return Error
Return File Data results in response: Nothing
Write File Data results in response: Return Error

Fields:
File ID: (1 Byte) GFB File ID, ISFSB File ID, or ISFB File ID
Start Byte Offset: (2 Bytes) Byte offset to begin access (read or write)
Bytes Accessing: (2 Bytes) Number of bytes to access (read or write). Supplying zero (0) accesses all bytes until the end of file
Data: (X Bytes) File Data — unused on read requests.

File Data Access Template
File ID Start Offset Bytes Accessing Data
1 Byte 2 Bytes 2 Bytes X Bytes
Read File Data Payload Block
Data Tmpl 1 Data Tmpl 2 Data Tmpl M
5 Bytes 5 Bytes 5 Bytes
Return & Write File Data Payload Block
Data Tmpl 1 + Data Data Tmpl 2 + Data Data Tmpl M + Data
5+X1 Bytes 5+X2 Bytes 5+X3 Bytes

File Headers Operands

These are ALP records providing access to the following file information: ID, permissions, length in bytes, and allocation (max length) in bytes. Each file — an GFB File, ISFSB File, or ISFB File — has a file header. File headers may be read as ALP record data according to the template shown below.

If Respond bit is set:
Read File Header results in response: Return File Header
Return File Header results in response: Nothing

Fields:
File ID: (1 Byte) GFB File ID, ISFSB File ID, or ISFB File ID
Permissions: (1 Byte) Permissions of the specified File
Length: (2 Bytes) Current length of the file data, in bytes
Allocation: (2 Bytes) Maximum length of the file data, in bytes

File Header
File ID Permissions Length Allocation
1 Byte 1 Byte 2 Bytes 2 Bytes
Read File Header Payload Block
File ID 1 File ID 2 File ID M
1 Byte 1 Byte 1 Byte
Return File Header Payload Block
File Header 1 + Data File Header 2 + Data File Header M + Data
6+X1 Bytes 6+X2 Bytes 6+X3 Bytes

Delete File Operand

This is an optional ALP record that deletes a file in the given file block. Only users with write access permissions to the specified files may delete the files. The ALP record data includes one or more file IDs to delete.

If Respond bit is set:
Delete File results in response: Return Error

Delete File Payload Block
File ID 1 File ID 2 File ID M
1 Byte 1 Byte 1 Byte

Create New File Operand

This is an optional command that creates a new file in the given file block. Data may be written following the creation of the file, using a command with the File Data Operand. Only users granted “user” level permissions or higher (see X.9.2.2) may create files. The ALP record data includes one or more file headers to create as new files.

If Respond bit is set:
Create New File results in response: Return Error

Create New File Payload Block
File Header 1 File Header 2 File Header M
6 Bytes 6 Bytes 6 Bytes

File Header & Data Operands

This is a directive that is identical to the normal File Data Operand except that file header data is streamlined into the response. The access permissions are treated as with the File Data Operand.

If Respond bit is set:
Read File Header & Data results in response: Return File Header / Return Error
Return File Header & Data results in response: Nothing

File Header & Data (H&D) Template
File ID Permissions Length Allocation Start Byte Offset Bytes Accessing
1 Byte 1 Byte 2 Bytes 2 Bytes 2 Bytes 2 Bytes
Read File Header & Data Payload Block
Data Tmpl 1 Data Tmpl 2 Data Tmpl M
5 Bytes 5 Bytes 5 Bytes
Return File Header & Data Payload Block
H&D Tmpl 1 H&D Tmpl 2 H&D Tmpl M
10+X1 Bytes 10+X2 Bytes 10+X3 Bytes

Restore File Operand

This is an optional, write-only directive that replaces the specified file with its default data. The implementer of the device shall decide which files can be restored. Only users with write access permissions to the specified files may restore these files. Its directive data and treatment are identical to those of the Delete File Directive.

Return File Error Operand

This is a write-only, response-only operand for the purpose of reporting errors due to wholly or partially erroneous write directives. The Erroneous Command is a copy of the Directive Command from the directive that yielded the error, and the Erroneous File ID is a File ID whose access yielded a write error. Write Error Codes are listed below. In the event there are multiple errors, the lowest valued code shall be the one that is returned.

Return File Error Payload Block
Erroneous File ID File Error Code
1 Byte 1 Byte
File Error Codes
Code Reason
0x00 No Error
0x01 Cannot access file: File ID does not exist
0x02 Cannot create file: File ID already exists
0x03 Cannot restore file: File is not restorable
0x04 Cannot access file: Insufficient permissions
0x05 Cannot create file: Supplied length (in header) is beyond file limits
0x06 Cannot create file: Supplied allocation (in header) is beyond file limits
0x07 Cannot write: Supplied start offset is out of bounds of file allocation
0x08 Cannot complete write: Supplied data goes beyond file allocation
0xFF Unknown Error
dash7_mode_2/alp_file.txt · Last modified: 2012/03/02 00:35 by jpnorair