Commands
Commands are used to control, configure and monitor the target board. All commands follow the syntax of name=value. Commands can be sent to the target board via the following methods:
UDP or TCP: Commands are sent, and data requested via the Network - Not available yet, in future version!
Web pages and HTTP: Command are sent, and data requested via the HTTP GET and POST commands. Various HTML elements, like button, check boxes, radio buttons and more can be used!
Serial ports: This enables commands via different protocols, like RS-232, RS-485, TTL Serial port and others. - Not available yet, in future version!
USB: Commands are sent, and data requested via USB HID messages. The free Netcruzer USB Terminal app can be used. For details, see modtronix.com/info/usbterminal. Full source code for the Netcruzer USB Terminal is also available, and can be modified if required.
For example, to set port pin Y2, the following methods can be used (see “o – Output Command“ section below for syntax):
Send the following HTTP GET command from a web page: http://10.1.0.1/?oy2=1
Add a button to a web page that uses HTTP POST to send the following command: oy2=1
Send the following UDP message to the UDP Command Port: oy2=1 - Not available yet, in future version!
In this example the name part of the command is "oy2", and the value part is “1”.
UDP Commands
Any of the commands listed below can be executed on the target by sending them to UDP port 54123. This port is configurable, and can be changed. For example, to set Port pin X7, the following UDP message can be sent to the target board:
ox7=1
Multiple commands can be send by separating each command with a '&' character. For example, to set Port pin X0, and clear Port X1, we can send the following UDP
message to the target board:
ox0=1&ox1=0
HTTP Get Commands
Any of the commands listed below can be executed on the target by using the HTTP GET command. To issue a HTTP GET command, simply append the command to the web page address, after a '?' character. For example, to set Port pin X2, we can send the following HTTP GET command to the target board:
http://10.1.0.1/?ox2=1
Multiple commands can be send by separating each command with a '&' character. For example, to set Port pin X2, and clear Port Y0, we can send the following HTTP GET command to the target board:
http://10.1.0.1/?ox2=1&oy0=0
Value format specifier
For numbers, where no format specifier is supplied, it is in hex format. The following formats are defined:
[0-FFFF] represents a hex number from 0 to 0xFFFF (0 to 65,535). The characters A-F must be uppercase! For example: cmd=1F09
b[0-FF] represents a hex BYTE from 0 to 0xFF (0 to 255). The characters A-F must be uppercase! For example: cmd=1F
w[0-FFFF] represents a hex WORD from 0 to 0xFFFF (0 to 65,535). The characters A-F must be uppercase! For example: cmd=051F
l[0-FFFFFFFF] represents a hex DWORD from 0 to 0xFFFFFFFF (0 to 4,294,967,295). The characters A-F must be uppercase! For example: cmd=051F
d[0-65,535] represents a decimal number from 0 to 65,535. For example: cmd=d1038
d[b,w,l][0-65,535] represents a decimal BYTE, WORD or DWORD. For example: cmd=db255, or cmd=dw60000
’String’ represents a string. For example: cmd=’Hello World’
c - Configuration Command
The following configuration commands are defined.
Command Syntax | Description |
cs[0,1]=cfgVal | Configure Port S0 to S1 - The following example will configure port S0 as an Digitial Input: cs0=in The cfgVal parameter can be one of the following:
|
ct[0,1]=cfgVal | Configure port T0 to T1 - The following example will configure port T0 as an Digitial Input: cs0=id See “cs” command above for details on the cfgVal value |
cx[0-11]=cfgVal | Configure port X0 to X11 - The following example will configure port X2 as an PWM Channel 2: cx2=w2 See “cs” command above for details on the cfgVal value |
cy[0-11]=cfgVal | Configure port Y0 or Y11 - The following example will configure port Y10 as an Digitial Input with pull-up: cy10=iu See “cs” command above for details on the cfgVal value |
k - Configuration Block Command
This feature has not been implemented yet! Will be implemented in a future version!
The following commands are used for modifying the application properties stored in CFG_BLOCK s. The following commands are defined:
Command Syntax | Description |
k[0-f][00-ff][00-ff]=f[value] | Writes 1-16 bytes to a CFG_BLOCK.
The value can have a format specifier, as defined in “Value format specifier“ section above. |
Some examples:
k12010=4B will write 0x4B to offset 0x20 of CFG_BLOCK with id 0x0110 (0x0100+10).
l - General Command
The general command has various uses. The following commands are defined:
Command Syntax | Description |
lk(1-4)=str | Write byte array to LCD2S serial display - Write given bytes to a LCD2S type serial display. The 'lk' command can include the LCD display address, which has to be a value from 1-4. If omitted, 1 is used. The address is set by a 2-position DIP switch on the back of the LCD2S display. A '_' escape character can be used to send hex values. The two bytes following the escape character gives the hex code. See LCD2S documentation for list of all commands, and their syntax. For example, the syntax for the LCD brightness command is "0x81, value", where value is the new brightness value in hex from 00-FF (decimal 0-255). To set the brightness to a hex value of A0 (160 decimal), the following command can be send: lk=_81_A0 To instruct the LCD display to remember the brightness setting after the power is removed, the command above must be preceded by a "Remember Command" (0x8D). Commands are separated by a '&' character. The syntax for sending a remember command, followed by the set brightness command shown above will be: To include a '_' character, two '_' characters must be send after each other. For example |
ll(1-4)=str | Write String to LCD Display - Writes the given string to the LCD display. The 'll' command can include the LCD display address, which has to be a value from 1-4. If omitted, 1 is used. The address is set by a 2-position DIP switch on the back of the LCD2S display. A '_' escape character can be used to include one of the following LCD string escape sequences: The following example clears the display, goes to the beginning of the first line and writes "Hello": The following example clears display, writes "Hello" on first line, and "world" on second line: The following example will write "Hello World" to the LCD2S display with address 4 (both positions of DIP switch set to on): To include a '_' character, two '_' characters must be send after each other. |
o – Output Command
The following commands are defined:
Command Syntax | Description |
ow[0-7]=[0,n] | Set PWM output - Write value to a PWM channel. |
os[0-7]=[1,0] | Write Port S0 or S1 - Write value of Netcruzer Port S0 or S1. |
ot[0-7]=[1,0] | Write Port T0 or T1 - Write value of Netcruzer Port T0 to T7. |
ox[0-10]=[1,0] | Write Port X0 or X10 - Write value of Netcruzer Port X0 to X10. |
oy[0-10]=[1,0] | Write Port Y0 or Y10 - Write value of Netcruzer Port Y0 to Y10. |
p - PLC Process Image Command
This feature has not been implemented yet! Will be implemented in a future version!
The following commands are defined:
Command Syntax | Description |
p[0-F,Z][0-FF]f=value | Write discrete bit to PLC Ram
Some examples:
|
s - Serial Data Port Command
The Serial Data Port Command provides read and write access to a variety of serial peripherals via Serial Data Ports (SDP). This should not be confused with the UART and USART Serial Port. The term Serial Data Port as referred to in this documentation refers to a variety of serial peripherals and protocols like I2C, SPI, USART, UDP, TCP and more. Each Serial Data Port is identified by a number, the Serial Data Port ID. Each Serial Data Port has a transmit and receive buffer. They are identified by their Serial Data Port Buffer IDs.
- The Serial Data Port Buffer ID for the transmit buffer = (Serial Data Port ID * 2
- The Serial Data Port Buffer ID for the receive buffer = ((Serial Data Port ID)* 2) + 1)
For example, the Serial Data Port ID for I2C 1 is 7 (as given in table above). It's transmit buffer will have the Serial Data Port Buffer ID of 14 (7*2), and it's receive buffer will be 15.
The currently defined Serial Data Port IDs, and their associated Serial Data Port Buffer IDs are:
ID | Buf ID | Serial Port | ID | Buf ID | Serial Port | ||||
Dec | Hex | Tx | Rx |
| Dec | Hex | Tx | Rx |
|
0 | 00 | 00 | 01 | Debug Port (USB by default) | 13 (d) | 0D | 1A | 1B | TCP 1 |
1 | 01 | 02 | 02 | UART 1 | 14 (e) | 0E | 1C | 1D | TCP 2 |
2 | 02 | 04 | 05 | UART 2 | 15 (f) | 0F | 1E | 1F | TCP 3 |
3 | 03 | 06 | 07 | UART 3 | 16 (g) | 10 | 20 | 21 | USB HID Port 1 |
4 | 04 | 08 | 09 | UART 4 | 17 (h) | 11 | 22 | 23 | User 1 General Purpose Serial Data Port |
5 | 05 | 0A | 0B | SPI 1 | 18 (i) | 12 | 24 | 25 | User 2 General Purpose Serial Data Port |
6 | 06 | 0C | 0D | SPI 3 | 19 (j) | 13 | 26 | 27 | User 3 General Purpose Serial Data Port |
7 | 07 | 0E | 0F | I2C 1 | 20 (k) | 14 | 28 | 29 | User 4 General Purpose Serial Data Port |
8 | 08 | 10 | 11 | I2C 2 | 21 (l) | 15 | 2A | 2B | User 5 General Purpose Serial Data Port |
9 | 09 | 12 | 13 | I2C 3 | 22 (m) | 16 | 2C | 2D | User 6 General Purpose Serial Data Port |
10 (a) | 0A | 14 | 15 | UDP 1 | 23 (n) | 17 | 2E | 2F | User 7 General Purpose Serial Data Port |
11 (b) | 0B | 16 | 17 | UDP 2 | 24 (o) | 18 | 30 | 31 | User 8 General Purpose Serial Data Port |
12 (c) | 0C | 18 | 19 | UDP 3 |
|
|
|
|
|
The serial data port command has the following syntax:
Command Syntax | Description |
si(f)=asciiCmd | Write “ASCII Command” to Serial Date Port - Writes an ASCII formatted string (with control characters) to the given Serial Data Port:
|
Format of asciiCmd part of command
The asciiCmd (value part of command) is an ASCII Formatted String, with Escape Sequences (Control Characters). It uses 2 upper case characters to represent a single hex character. Strings must be enclosed within single quotation marks('). Lower case characters 'a' to 'z' are used to represent "Control characters". It has the following format:
Format | Description |
XX | Two upper case characters representing a single byte (hex value). |
c | Lower case character 'a' to 'z' represents a "control character". |
s, p | 's' an 'p' control characters represent the start and stop of a message. |
^^ | Two "escape characters" represents a single '^' character. |
^x | Use this format to represent a "control character" that is not lower. Lower case characters do not have to be escaped. Currently not used, but reserved for future use! |
' | Enclose string with single quotes. A double ' character will not end the string, but represents a single ' character. |
I2C Serial Ports Commands
The s7, s8 and s9 commands are for the 3 available I2C serial ports, I2C 1 to I2C 3. The asciiCmd string can contain the following control characters:
s and p - Put Start(s) and Stop(p) Condition on bus. A second 's' character (anywhere in string) before 'p' character will cause a repeated Start condition
rNN - Read from bus, where NN is two upper case hex characters stating how many bytes to read.
rNNuAA - Read from bus, where NN is two upper case hex characters stating how many bytes to read. Write result to given User Ram location, where AA is two upper case hex characters giving User Ram address.
rNNtAA - Read from bus, where NN is two upper case hex characters stating how many bytes to read. Write result to given Serial Data Port Buffer location, where AA is two upper case hex characters giving Serial Data Port ID address.
When sending this command via a packet based protocol (like USB, TCP...), the s and p control characters are not required. The contents of each packet will automatically be placed in a single I2C message, preceded by a Start condition, and ended with a Stop condition. When a streaming protocol is used (line UDP, UART serial port...), there are no message packets, and the s and p control characters must be used to indicate the start and stop of an I2C message. These control characters can however be used at any time to send multiple I2C messages in a single packet, or to send a repeated Start Condition (have a 's' character in message).
The following example will write the given message to I2C 1 (s7). It writes a Start condition, 3 bytes (0x50, 0xA8, 0x31) and a Stop Condition to the bus.
s7=50A831
The following example will write the given message to I2C 1 (s7). It writes a Start condition, writes 1 byte(0x51), reads 2 bytes, and writes a Stop condition to the bus:
s7=51r02
The following example will write the given message to I2C 2 (s8). It will put a Start condition on bus, Send 2 bytes (0x30, 0xA8), Send 3 characters = 'abc', put Stop condition on bus:
s8=30A8'abc'
This example will write a message to a LCD2S type display connected to I2C 1 port. It will put a Start condition on bus, Send 0x50 hex byte (LCD2S address), Send 0x80 hex byte (LCD2S Write Parsed String Command), Send 0x0C hex byte (Clear display and go to beginning of first line), Send 5 characters = 'Hello', Send 0x0A hex byte (Go to beginning of next line), Send 5 characters = 'World', put Stop condition on bus:
s7=50800C'Hello'0A'World'
This example will write the given message to Serial Port 7, which is I2C 1. It will put a Start condition on bus, Send 0x50 hex byte, put a Repeated Start condition on bus, Send 0x31 hex byte, put Stop condition on bus:
s7=50s31
The following examples assume the command is being sent via a streaming protocol, like UDP. The 's' and 'p' characters are required so that a Start and Stop Condition is put on the I2C bus. This example will write the given message to Serial Port 8, which is I2C 2. It will put a Start condition on the bus, Send 0x50 hex byte, Send 0xA8 hex byte, Send 0x31 hex byte, put Stop condition on bus:
s8=s50A831p
u - User Memory (volatile Memory) Command
The following commands are used to write to the User Memory. The user memory is a section in RAM that can be used by the user for storing variables. There are also Tags (see Tag chapter below) for displaying the contents of the User Memory. By default, 256 bytes of user memory is available! This means the address part of the commands must be in the range 0-FF (0-255 decimal). The user memory can be increased by adding the following line to the projdefs.h file in the source code. This example increases it to 1024 bytes:
#define CMD_USER_RAM_SIZE 1024
The address[adr] and value[val] in following commands can be in decimal or hex format. Default is hex format. The 'd' format specifiers can be used to specify decimal format. For example:
uA0=60 - Will write 0x60 (decimal 96) to address 0xA0 (decimal 160)
ud150=d60 - Will write 60 (decimal 60) to address 150 (decimal 150)
The following commands are defined:
Command Syntax | Description |
u(d)[adr]=(d)[val] | Write Byte to User Memory - Writes a byte(decimal or hex format) to user Memory(decimal or hex address). An optional 'd' preceding the [adr] or [val] indicates a decimal number (default is hex). For example:
|
u(d)[adr]w=(d)[val] | Write Word(2 bytes) to User Memory - Writes a word(decimal or hex format) to user Memory(decimal or hex address). For example:
|
u(d)[adr]s=’string’ | Write string to User Memory - Write string to user Memory (decimal or hex address). The given string it written to user memory from the given address. A NULL termination is added to the end of the string. For example, if “Hello” is written, it will cause 6 bytes to be written, the 5 bytes required for “Hello”, and a 0 (NULL termination). It is very important to keep track of what user memory addresses are used for what data, and not to overwrite locations used for other variables! The following example shows how to write the string “Hello World” to address 0xB0. It will write 12 bytes to user memory.
|
v - User EEPROM (non-volatile Memory)
This feature has not been implemented yet! Will be implemented in a future version!
The following Commands are used to write to User EEPROM Memory. TheUser EEPROM Memory is a section in the external EEPROM that can be used by the user for storing variables. There are also Tags (see Tags chapter below) for requesting the contents of the User EEPROM Memory. By default, 250 bytes of user EEPROM memory is available! This means the address part of the Tag must be in the range 0-FA (0-250 decimal). The format is exactly the same as for the “u - User Memory Command”, except that all Commands start with a 'v' and not 'u' character!
For example, to write 106 to User EEPROM address 10 (0x0A hex), use following command:
v0A=106 Write decimal value to User EEPROM (hex address).
x,y,z - User Commands
The x, y and z commands are reserved for user commands. If a user want to a custom commands, they should start with x, y or z.
For example, if a command is required to turn on the pool light, the following command could be used:
xpl1=[0-1] Turn pool light on or off