stm32samples/F1:F103/FX3U/Readme.md

A usefull thing made of chineese FX3U clone

Works over RS-232 (default: 115200, 8N1), CAN (default: 250000 baud) or MODBUS-RTU (default: 9600, 8N1).

You can see pinout table in file hardware.c.

Serial protocol (each string ends with '\n').

Values in parentheses after flags command is its bit number in whole uint32_t. E.g. to reset flag "f_relay_inverted" you can call f_relay_inverted=0 or flags2=0.

commands format: parameter[number][=setter]
parameter [CAN idx] - help
--------------------------

CAN bus commands:
canbuserr - print all CAN bus errors (a lot of if not connected)
cansniff - switch CAN sniffer mode
s - send CAN message: ID 0..8 data bytes

Configuration:
bounce [14] - set/get anti-bounce timeout (ms, max: 1000)
canid [6] - set both (in/out) CAN ID / get in CAN ID
canidin [7] - get/set input CAN ID
canidout [8] - get/set output CAN ID
canspeed [5] - get/set CAN speed (bps)
dumpconf - dump current configuration
eraseflash [10] - erase all flash storage
f_relay_inverted (2) - inverted state between relay and inputs
f_send_esw_can (0) - change of IN will send status over CAN with `canidin`
f_send_relay_can (1) - change of IN will send also CAN command to change OUT with `canidout`
f_send_relay_modbus (3) - change of IN will send also MODBUS command to change OUT with `modbusidout` (only for master!)
flags [17] - set/get configuration flags (as one U32 without parameter or Nth bit with)
modbusid [20] - set/get modbus slave ID (1..247) or set it master (0)
modbusidout [21] - set/get modbus slave ID (0..247) to send relay commands
modbusspeed [22] - set/get modbus speed (1200..115200)
saveconf [9] - save configuration
usartspeed [15] - get/set USART1 speed

IN/OUT:
adc [4] - get raw ADC values for given channel
esw [12] - anti-bounce read inputs
eswnow [13] - read current inputs' state
led [16] - work with onboard LED
relay [11] - get/set relay state (0 - off, 1 - on)

Other commands:
inchannels [18] - get u32 with bits set on supported IN channels
mcutemp [3] - get MCU temperature (*10degrC)
modbus - send modbus request with format "slaveID fcode regaddr nregs [N data]", to send zeros you can omit rest of 'data'
modbusraw - send RAW modbus request (will send up to 62 bytes + calculated CRC)
outchannels [19] - get u32 with bits set on supported OUT channels
reset [1] - reset MCU
time [2] - get/set time (1ms, 32bit)
wdtest - test watchdog

Value in square brackets is CAN bus command code.

The INs are changed compared to original "FX3U" clone: instead of the absent IN8 I use the on-board button "RUN".

CAN bus protocol

Default CAN speed is 250kbaud. Default CAN ID: 1 and 2 for slave. All data in little-endian format!

BYTE - MEANING

0, 1 - (uint16_t) - command code (value in square brackets upper);

2 - (uint8_t) - parameter number (e.g. ADC channel or X/Y channel number), 0..126 [ORed with 0x80 for setter], 127 means "no parameter";

3 - (uint8_t) - error code (only when device answers for requests);

4..7 - (int32_t) - data.

When device receives CAN packet with its ID or ID=0 ("broadcast" message) it check this packet, perform some action and sends answer (usually - getter). If command can't be execute or have wrong data (bad command, bad parameter number etc) the device sends back the same packet with error code inserted.

When runnming getter you can send only three bytes: command code and parameter number. Sending "no parameter" instead of parno means in some commands "all data" (e.g. get/set all relays or get all inputs).

CAN bus error codes

0 - ERR_OK - all OK,

1 - ERR_BADPAR - parameter is wrong,

2 - ERR_BADVAL - value is wrong (e.g. out of range),

3 - ERR_WRONGLEN - wrong message length (for setter or for obligatory parameter number),

4 - ERR_BADCMD - unknown command code,

5 - ERR_CANTRUN - can't run given command due to bad parameters or other reason.

CAN bus command codes

Number - enum from canproto.h - text command analog

0 - CMD_PING - ping

1- CMD_RESET - reset

2 - CMD_TIME - time

3 - CMD_MCUTEMP - mcutemp

4 - CMD_ADCRAW - adc

5 - CMD_CANSPEED - canspeed

6 - CMD_CANID - canid

7 - CMD_CANIDin - canidin

8 - CMD_CANIDout - canidout

9 - CMD_SAVECONF - saveconf

10 - CMD_ERASESTOR - eraseflash

11 - CMD_RELAY - relay

12 - CMD_GETESW - esw

13 - CMD_GETESWNOW - eswnow

14 - CMD_BOUNCE - bounce

15 - CMD_USARTSPEED - usartspeed

16 - CMD_LED - led

17 - CMD_FLAGS - flags

18 - CMD_INCHNLS - inchannels

19 - CMD_OUTCHNLS - outchannels

20 - CMD_MODBUSID - modbusid

21 - CMD_MODBUSIDOUT - modbusidout

22 - CMD_MODBUSSPEED - modbusspeed

Examples of CAN commands (bytes of data transmitted with given ID)

(all data in HEX)

Get current time: "02 00 00". Answer something like "02 00 00 00 de ad be ef", where last four bytes is time value (in milliseconds) from powering on.

Set relay number 5: "0b 00 85 00 01 00 00 00", answer: "0b 00 05 00 01 00 00 00".

Set relays 0..3 and reset other: "0b 00 ff 00 07 00 00 00", answer: "0b 00 7f 00 07 00 00 00".

Changing flags is the same as for text command: with parameter number (0..31) it will only change given bit value, without ("no par" - 0x7f) will change all bits like whole uint32_t.

MODBUS-RTU protocol

The device can work as master or slave. Default format is 9600-8N1. BIG ENDIAN (like standard requires). Default device ID is 1 ans 2 for target of "relay command" (if ID would be changed to 0 and flag f_send_relay_modbus set.

To run in master mode you should set its modbus ID to zero. Command modbus lets you to send strict formal modbus packet in format "slaveID fcode regaddr nregs [N data]" (all are space-delimited numbers in decimal, hexadecimal (e.g. 0xFF), octal (e.g. 075) or binary (e.g. 0b1100110) format. Here "slaveID" - one byte; "fcode" - one byte; "regaddr" - two bytes big endian; "nregs" - two bytes big endian; "N" - one byte; "data" - N bytes. Optional data bytes allowed only for "multiple" functions. In case of simple setters "nregs" is two bytes data sent to slave.

The command modbusraw will not check your data, just add CRC and send into bus.

In master mode you can activate flag f_send_relay_modbus. In this case each time the IN state changes device will send command with ID=modbusidout to change corresponding relays. So, like for CAN commands you can bind several devices to transmit IN states of one to OUT states of another. If modbusidout is zero, master will send broadcasting command. Slaves non answer for broadcast, only making required action.

The hardware realisation of modbus based on UART4. Both input and output works over DMA, signal of packet end is IDLE interrupt. This device doesn't supports full modbus protocol realisation: no 3.5 idle frames as packet end; no long packets (input buffer is 68 bytes, allowing no more that 67 bytes; output buffer is 64 bytes, allowing no more that 64 bytes). Maximal modbus slave ID is 247. You can increase in/out buffers size changing value of macros MODBUSBUFSZI and MODBUSBUFSZO in modbusrtu.h.

In slave mode device doesn't support whole CAN-bus commands range. Next I describe allowed commands.

There are five holding registers. "[R]" means read-only, "[W]" - write-only, "[RW]" - read and write.

0 - MR_RESET [W] - reset MCU.

1 - MR_TIME [RW] - read or set MCU time (milliseconds, uint32_t).

2 - MR_LED [RW] - read or change on-board LED state.

3 - MR_INCHANNELS [R] - get uint32_t value where each N-th bit means availability of N-th IN channel (e.g. if 9th channel is physically absent 9th bit would be 0).

Supported functional codes

01 - read coil

Read state of all relays. Obligatory regaddr="00 00", nregs="00 N", where "N" is 8-multiple number (in case of 10-relay module: 8 or 16). You will reseive N/8 bytes of data with relays' status (e.g. most lest significant bit is state or relay0, next - relay1 and so on).

Example: "01 01 00 00 00 10" - read state of all relays. If only relay 10 active you will receive: "01 01 02 04 00".

Errors: "02" - "regaddr" isn't zero; "03" - N isn't multiple of 8 or too large.

02 - read discrete input

Read state of all discrete inputs. Input/output parameters are the same like for "read coil".

Example: "01 02 00 00 00 08" - read 8 first INs. Answer if first 4 inputs active (disconnected): "01 02 01 0f".

Errors: like for "read coil".

03 - read holding register

You can read value of non write-only registers. You can read only one register by time.

Example: "01 03 00 01 00 01" - read time. Answer: "01 03 04 00 15 53 01", where 0x00155301 is 1397.505 seconds from device start.

Errors: "02" - "regaddr" is wrong, "03" - "regno" isn't 1.

04 - read input register

Read "nregs" ADC channels starting from "regaddr" number.

Example: "01 04 00 05 00 04" - read channels 5..8.
Answer: "01 04 08 08 6c 00 21 00 33 00 41" - got 0x86c (2156) for 5th channel and so on.

Errors: "02" - wrong starting number, "03" - wrong amount (zero or N+start > last channel available).

05 - write coil

Change single relay state. "nregs" is value (0 - off, non-0 - on), "regaddr" is relay number.

Example: "01 05 00 03 00 01" - turn 3rd relay on. Answer: "01 05 00 03 00 01".

Errors: "02" - wrong relay number.

06 - write holding register

Write data to non read-only register (reset MCU, change time value or turn LED on/off).

Example: "01 06 00 02 00 01" - turn LED on. Answer: "01 06 00 02 00 01".

Errors: "02" - wrong register.

0f - write multiple coils

Change state of all relays by once. Here "regaddr" should be "00 00", "nregs" should be multiple of 8, "N" should be equal ("nregs"+7)/8. Each data bit means nth relay state.

Example: "01 0f 00 00 00 08 01 ff" - turn on relays 0..7. Answer: "01 0f 00 00 00 08".

Errors: "02" - "regaddr" isn't zero, "03" - wrong amount of relays, "07" - can't change relay values.

10 - write multiple registers

You can write only four "registers" by once changing appropriate uint32_t value. The only "register" you can change is 01 - MR_TIME. "nregs" should be equal 1.

Example: "01 10 00 01 00 01 04 00 00 00 00" - clears Tms counter, starting time from zero. Answer: "01 10 00 01 00 01".

Errors: "02" - wrong register.

Error codes

01 - ME_ILLEGAL_FUNCION - The function code received in the request is not an authorized action for the slave.

02 - ME_ILLEGAL_ADDRESS - The data address received by the slave is not an authorized address for the slave.

03 - ME_ILLEGAL_VALUE - The value in the request data field is not an authorized value for the slave.

04 - ME_SLAVE_FAILURE - The slave fails to perform a requested action because of an unrecoverable error.

05 - ME_ACK - The slave accepts the request but needs a long time to process it.

06 - ME_SLAVE_BUSY - The slave is busy processing another command.

07 - ME_NACK - The slave cannot perform the programming request sent by the master.

08 - ME_PARITY_ERROR - Memory parity error: slave is almost dead.

Short programming guide

Adding a new value to flash storage

All storing values described in structure user_conf (flash.h). You can add there any new value but be carefull with 32-bit alignment. Bit flags stored as union confflags_t combining 32-bit and 1-bit access. After you add this new value don't forget to add setter/getter and string describing it in function dumpconf.

Text protocol allows you to work with flags by their semantic name. So to add some flag you should also modify proto.c:

• add text constant with flag name;
• add address of this constant into bitfields array (according to bit order in flags);
• add appropriate enum into text_cmd;
• add appropriate string into funclist: pointer to string constant, enum field and help text;
• modify function confflags for setter/getter of new flag.

Adding a new command

All base commands are processed in files canproto.c and proto.c. modbusproto.c is for modbus-specific commands.

To add CAN/serial command you should first add a field to anonimous enum in canproto.h, which will be number code of given CANbus command. Codes of serial-only commands are stored in enum text_cmd of file proto.c.

Add both CAN/serial command

• add enum in canproto.c;
• add string const with text name of this command in proto.c;
• add string to funclist with address of string const, enum and help;
• add command handler into canproto.c and describer into array funclist (index should be equal to command code, struct consists from pointer to handler, minimal and maximal value and minimal data length of can packet). If min==max then argument wouldn't be checked.

The handler returns one of errcodes and have as argument only pointer to CAN_message structure. So, serial command parser before call this handler creates CAN packet from user data. Format of command is next: "cmd[X][=VAL]", where "cmd" is command text, "X" - optional parameter, "VAL" - value for setter. So the packet would be "C C P 0 VAL0 VAL1 VAL2 VAL3", where "C" - command code, "P" - parameter number (or 0x7f" if X is omit) OR'ed with 0x80 for setter, VALx - xth byte (little endian) of user value.

For setting/getting uint32_t paramegers (especially configuration parameters) you can use handler u32setget. For bit flags - flagsetget.

To work with bit-flags by particular name use confflags handler of proto.c.

Add serial-only command

In this case there's no CAN handler. You work only with proto.c.

• add enum in text_cmd;
• add string const with text name of this command;
• add string to funclist with address of string const, enum and help;
• add command handler;
• add pointer to this handler into textfunctions array.

Handler also returns one of errcodes, but have next arguments:

• const char *txt - all text (excluding spaces in beginning) after command in user string;
• text_cmd command - number of command (useful when you have common handler for several commands).

Working with modbus

All exceptions and functional codes described as enums in modbusrtu.h. To form request or responce use structs modbus_request and modbus_responce. data fields in this structs is big-endian storing bytes in order like they will be sent via RS-485. Amount of data bytes should be not less then datalen value. For requests that don't need data, data may be NULL regardless datalen (for Fcode <= 6). regno is amount of registers or data written to register dependent on Fcode. The responce struct of error codes have NULL in data and datalen is appropriate exception code.

All high-level commands are in modbusproto.c. To add new register you should edit modbus_regusters enum in modbusproto.h.

The main parsing pipeline is parse_modbus_request in modbusproto.c. Here you can add parsing of new functional codes.

To work with new "registers" edit readreg, writereg or writeregs.