foc.us v2 controller BLE API

Advertising data

Advertising packet of the device includes manufacturer-specific data:

Byte

0

1

2

3

4

Value

Company identifier

FW version

Flags

List of services

Standard BLE services:

Special services:

1 tDCS Service

UUID: 0000AAB0-F845-40FA-995D-658A43FEEA4C

Service characteristics:

1.1 Control command

UUID: 0000AAB1-F845-40FA-995D-658A43FEEA4C

Size: 6 bytes.

Permissions: Write.

Byte

0

1

2

3

4

5

Value

Command ID

Subcommand ID

Data

Command IDs:

1.1.1 Activate sleep mode (CID = 0)

Data: not used.

Description: stop all tasks and enter into sleep mode immediately.

Note: command terminates BLE connection.

Example: 00 00 00 00 00 00

1.1.2 Manage time (CID = 1)

Subcommand ID:

1.1.2.1 Get time (CID = 1, SCID = 0)

Data: not used.

Description: when this command received, device will update the Control command response with device’s time. Time format is 4-bytes UNIX timestamp.

Example: 01 00 00 00 00 00

1.1.2.2 Set time (CID = 1, SCID = 1)

Data: time (4-bytes UNIX timestamp).

Description: set device’s time.

Example: 01 01 3B F6 90 55 (set time to 29 Jun 2015 07:39:39)

1.1.3 Manage programs (CID = 2)

Data format:

Byte

0

1

2

3

Value

Program ID

Program descriptor ID

-

-

Subcommand ID:

Description.

Device has a defined number of memory cells for programs. This number can be retrieved using “Get the maximum number of programs” subcommand.

Each program has its own identifier - Program ID. The minimum Program ID value is 0 and the maximum - equals to number of memory cells for programs minus 1.

Any program can be in one of two states: valid or invalid. The state can be retrieved using “Get program status” subcommand. When new program written into device it gets invalid status. “Enable program” subcommand should be executed to verify new program and switch its state to valid. Valid state means that the program passed verification and can be started using “Start program” subcommand. Only valid programs are displayed at device’s display.

Program’s settings are stored in 2 descriptors (Descriptor 0 and Descriptor 1).

Descriptor 0:

Byte

0

1

2

3

4

5

6

7

8

9

Value

Valid

Name

Byte

10

11

12

13

14

15

16

17

18

19

Value

Mode

Duration

Sham

Duration (sham)

Current

Current offset

Descriptor 1:

Byte

0

1

2

3

4

5

6

7

8

9

Value

Volt.

Bipolar

Frequency/Min frequency

Max frequency/Duty cycle

Byte

10

11

12

13

14

15

16

17

18

19

Value

Rand current

Rand freq

Pola-

rity

-

-

-

-

-

-

-

Example. Read all programs.

  1. Execute “Get the maximum number of programs” subcommand to get the maximum Program ID value (max ID = max N - 1).
  2. Optional. Get the state of each program by executing the “get program status” subcommand for each Program ID.
  3. Execute “read program” subcommand with Descriptor ID parameter set to 0.
  4. Read program’s descriptor 0 from Data buffer.
  5. Execute “read program” subcommand with Descriptor ID parameter set to 1.
  6. Read program’s descriptor 1 from Data buffer.
  7. Repeat steps 3-6 for each Program ID or only for valid programs (valid programs obtained at the step 2).

Example. Write and enable a program.

  1. Write program’s Descriptor 0 to the Data buffer.
  2. Execute “write program” subcommand with Descriptor ID parameter set to 0.
  3. Write program’s Descriptor 1 to the Data buffer.
  4. Execute “write program” subcommand with Descriptor ID parameter set to 1.
  5. Execute “enable program” subcommand to verify and enable the command.

1.1.3.1 Get the maximum number of programs (CID = 2, SCID = 0)

Program ID, Program descriptor ID: not used.

Description: when this command received, device will update the Control command response with the maximum number of programs available in device.

Example.

Control command: 02 00 00 00 00 00

Control command response: 02 00 08 00 00 00 (8 programs).

1.1.3.2 Get the number of valid programs (CID = 2, SCID = 1)

Program ID, Program descriptor ID: not used.

Description: when this command received, device will update the Control command response with the number of valid programs available in device.

1.1.3.3 Get program status (CID = 2, SCID = 2)

Program ID: 0…(maximum number of programs - 1)

Program descriptor ID: not used.

Description: when this command received, device will update the Control command response with the status of the selected program (0 - invalid, 1 - valid).

1.1.3.4 Read program (CID = 2, SCID = 3)

Program ID: 0…(maximum number of programs - 1)

Program descriptor ID: 0/1.

Description: when this command received, device will update the Data buffer with the selected descriptor of the selected program.

1.1.3.5 Write program (CID = 2, SCID = 4)

Program ID: 0…(maximum number of programs - 1)

Program descriptor ID: 0/1.

Description: when this command received, device will copy contents of Data buffer to internal memory to update the selected descriptor of the selected program.

1.1.3.6 Enable program (CID = 2, SCID = 5)

Program ID: 0…(maximum number of programs - 1)

Program descriptor ID: not used.

Description: enable selected program; device sets to true the valid flag in the program descriptor 0.

Note. When this command received, device will check correspondings to the program descriptors. If its content is wrong program won’t be enabled.

1.1.3.7 Disable program (CID = 2, SCID = 6)

Program ID: 0…(maximum number of programs - 1)

Program descriptor ID: not used.

Description: disable selected program; device sets to false the valid flag in the program descriptor 0.

1.1.3.8 Start program (CID = 2, SCID = 7)

Program ID: 0…(maximum number of programs - 1)

Program descriptor ID: not used.

Description: start selected program.

Note: the program should be enabled before start.

Example: 02 07 01 00 00 00 (starts program with ID = 1).

1.1.3.9 Stop program (CID = 2, SCID = 8)

Program ID, Program descriptor ID: not used.

Description: stop active program.

1.1.4 Manage session logs (CID = 3)

Subcommand ID:

Device creates a new log file for each tCS session. Manage session logs commands allow to get information about logs and download log files.

Algorithm for log files downloading:

  1. (Optional) Get number of saved log files.
  2. (Optional) Get overall size of saved log files.
  3. Get session log file. If command responses with “No file” error, finish the algorithm.
  4. Check CRC of the downloaded file (see “Session log file format” document). If file corrupted go to the step 3.
  5. Obtain file ID from the file’s header.
  6. Delete session log file from device’s memory
  7. Go to step 3.

If error occured (e.g. BLE link was dropped) during file downloading, the transfer can be started from the necessary position by setting the Block index field in the Get session log file command.

1.1.4.1 Get number of saved log files (CID = 3, SCID = 0)

Data: not used. 

Description: when this command received, device will update the Control command response with the number of saved log files.

Example.

Control command: 03 00 00 00 00 00

Control command response: 03 00 05 00 00 00 (5 logs available)

1.1.4.2 Get overal size of saved log files (CID = 3, SCID = 1)

Data: not used.

Description: when this command received, device will update the Control command response with the overall size (bytes) of all saved log files.

Example.

Control command: 03 01 00 00 00 00

Control command response: 03 00 10 01 00 00 (272 bytes)

1.1.4.3 Get session log file (CID = 3, SCID = 3)

Data:

Byte

0

1

2

3

Value

Flag

Block index

-

Flag:

Description. When this command received, device will update the Control command response with the size of the request (oldest or newest) file and start uploading of the file from the position defined by Block index. File uploading performed by series updating of the Data buffer with index of the block and 18-bytes block of data.

Data buffer format:

B

0

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

V

Block index

Data block

Example.

Control command: 03 03 00 00 00 00 (get oldest log file)

1.1.4.4 Delete session log file (CID = 3, SCID = 4)

Data: file ID (obtained from the log file header, see “Session log file format” document).

Description: delete session log file from device’s memory.

Example.

Control command: 03 04 09 00 00 00 (delete file with ID = 9)

1.1.4.5 Stop uploading of the log file (CID = 3, SCID = 5)

Data: not used.

Description: when this command received, device will stop uploading of the log file.

Example.

Control command: 03 05 00 00 00 00

1.2 Control command response

UUID: 0000AAB2-F845-40FA-995D-658A43FEEA4C

Size: 6 bytes.

Permissions: Read, Notify.

Byte

0

1

2

3

4

5

Value

Command ID

Status

Data

Description: returns status of the executed command and (if available) data.

Status:

1.3 Data buffer

UUID: 0000AAB3-F845-40FA-995D-658A43FEEA4C

Size: 20 bytes.

Permissions: Read, Write, Notify.

Description: data buffer for some control commands.

1.4 Actual current

UUID: 0000AAB4-F845-40FA-995D-658A43FEEA4C

Size: 2 bytes, signed.

Permissions: Read, Notify.

Description: actual current value (uA) in active mode.

1.5 Active mode duration

UUID: 0000AAB5-F845-40FA-995D-658A43FEEA4C

Size: 2 bytes.

Permissions: Read, Notify.

Description: actual duration (seconds) of the active mode.

1.6 Active mode remaining time

UUID: 0000AAB6-F845-40FA-995D-658A43FEEA4C

Size: 2 bytes.

Permissions: Read, Notify.

Description: remaining time (seconds) of the active mode.