Andy A / plotly

plotly interface based on ardunio sample code

Dependents:   Plotly_HelloWorld

Library for plotting a simple x/y scatter chart on the plot.ly website.

See plotly_HelloWorld for sample usage.

plotly.h@8:d4f705ba2ea5, 2014-07-29 (annotated)

Committer:
AndyA
Date:
Tue Jul 29 13:43:31 2014 +0000
Revision:
8:d4f705ba2ea5
Parent:
7:9409a72ab6c0 
Documentation tidy up and fix a stupid error in the merge between the documented and the multi-line branches.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AndyA 0:96532c59670f 1 #ifndef plotly_streaming_ethernet_h
AndyA 0:96532c59670f 2 #define plotly_streaming_ethernet_h
AndyA 0:96532c59670f 3
AndyA 0:96532c59670f 4 #include <EthernetInterface.h>
AndyA 0:96532c59670f 5 #include <TCPSocketConnection.h>
AndyA 0:96532c59670f 6
AndyA 4:33006c37c633 7 // size of the large buffer used for constructing messages.
AndyA 2:d53d74ed68ac 8 #define k_bufferSize 512
AndyA 2:d53d74ed68ac 9
AndyA 0:96532c59670f 10
AndyA 4:33006c37c633 11 /** Create a plot on plot.ly
AndyA 4:33006c37c633 12 *
AndyA 8:d4f705ba2ea5 13 * Creates a streaming X/Y scatter plot with line on the plot.ly site.
AndyA 8:d4f705ba2ea5 14 * Multiple lines can be drawn however each line currently requires a seperate network socket so you could easily run out of resources if you're not careful.
AndyA 8:d4f705ba2ea5 15 * I've only tested 1 and 2 line plots.
AndyA 4:33006c37c633 16 *
AndyA 8:d4f705ba2ea5 17 * In theory each line could be plotted by a different mbed but this would require some changes to the way charts are initalised.
AndyA 8:d4f705ba2ea5 18 *
AndyA 8:d4f705ba2ea5 19 * Update periods can be between 50ms and 60s. Anything faster will be filtered, anything slower will result in the connection getting closed.
AndyA 4:33006c37c633 20 *
AndyA 4:33006c37c633 21 * Requires an mbed with network support.
AndyA 4:33006c37c633 22 *
AndyA 8:d4f705ba2ea5 23 * Based on the Ardunio code supplied by plot.ly and provided as is, it works for me but your mileage may vary.
AndyA 8:d4f705ba2ea5 24 * Sorry, I don't have time to offer much support on this.
AndyA 4:33006c37c633 25 *
AndyA 8:d4f705ba2ea5 26 * You will need to create a plot.ly account and then go to https://plot.ly/settings to get your API key and streaming tokens.
AndyA 4:33006c37c633 27 *
AndyA 4:33006c37c633 28 * See Plotly_HelloWorld for a sample implimentation.
AndyA 4:33006c37c633 29 *
AndyA 4:33006c37c633 30 */
AndyA 2:d53d74ed68ac 31
AndyA 0:96532c59670f 32 class plotly
AndyA 0:96532c59670f 33 {
AndyA 0:96532c59670f 34 public:
AndyA 4:33006c37c633 35 /**
AndyA 4:33006c37c633 36 @param username Your plot.ly username
AndyA 4:33006c37c633 37 @param api_key Your plot.ly API key
AndyA 7:9409a72ab6c0 38 @param stream_tokens An array of plot.ly streaming token for your plot.ly account
AndyA 4:33006c37c633 39 @param filename The name of the file to save the chart as
AndyA 7:9409a72ab6c0 40 @param nTraces The number of traces (MUST match the size of stream_tokens, can be omitted for a single line)
AndyA 4:33006c37c633 41 */
AndyA 8:d4f705ba2ea5 42 plotly(const char *username, const char *api_key, const char *stream_tokens[], const char *filename, int nTraces = 1);
AndyA 7:9409a72ab6c0 43
AndyA 0:96532c59670f 44 ~plotly();
AndyA 4:33006c37c633 45
AndyA 4:33006c37c633 46 /** Initalises the chart
AndyA 6:e57d6e9313f4 47
AndyA 4:33006c37c633 48 This fucntion creates a blank chart on the plot.ly system and configures it to recieve streamed data using the specified token
AndyA 4:33006c37c633 49
AndyA 4:33006c37c633 50 Time taken for this function can vary depending on network delays.
AndyA 6:e57d6e9313f4 51
AndyA 8:d4f705ba2ea5 52 If you wish to change any of the options like max points or world readability then make sure you change them BEFORE calling this function.
AndyA 4:33006c37c633 53 */
AndyA 0:96532c59670f 54 bool init();
AndyA 4:33006c37c633 55
AndyA 4:33006c37c633 56 /**
AndyA 4:33006c37c633 57 Adds a point to the chart. The chart MUST be initalised before calling this.
AndyA 4:33006c37c633 58 Note, if the streaming network port is closed then this will attempt to open the port and re-establish the stream connection, this could block for a while.
AndyA 7:9409a72ab6c0 59 @param x The X value.
AndyA 7:9409a72ab6c0 60 @param y The y value.
AndyA 7:9409a72ab6c0 61 @param stream Which trace to add the point to counting from 0, can be omitted for charts with a single line.
AndyA 7:9409a72ab6c0 62 */
AndyA 7:9409a72ab6c0 63 void plot(unsigned long x, int y, int stream = 0);
AndyA 0:96532c59670f 64
AndyA 7:9409a72ab6c0 65 /**
AndyA 7:9409a72ab6c0 66 Adds a point to the chart. The chart MUST be initalised before calling this.
AndyA 7:9409a72ab6c0 67 Note, if the streaming network port is closed then this will attempt to open the port and re-establish the stream connection, this could block for a while.
AndyA 7:9409a72ab6c0 68 @param stream Which trace to add the point to counting from 0, can be omitted for charts with a single line.
AndyA 4:33006c37c633 69 @param x The X value.
AndyA 4:33006c37c633 70 @param y The y value.
AndyA 4:33006c37c633 71 */
AndyA 6:e57d6e9313f4 72 void plot(unsigned long x, float y, int stream = 0);
AndyA 0:96532c59670f 73
AndyA 4:33006c37c633 74 /**
AndyA 5:fc8eefeb301b 75 Adds a point to the chart. The chart MUST be initalised before calling this.
AndyA 5:fc8eefeb301b 76 Note, if the streaming network port is closed then this will attempt to open the port and re-establish the stream connection, this could block for a while.
AndyA 5:fc8eefeb301b 77
AndyA 5:fc8eefeb301b 78 @param x The X value.
AndyA 5:fc8eefeb301b 79 @param y The y value.
AndyA 7:9409a72ab6c0 80 @param stream Which trace to add the point to counting from 0, can be omitted for charts with a single line.
AndyA 5:fc8eefeb301b 81 */
AndyA 6:e57d6e9313f4 82 void plot(float x, float y, int stream = 0);
AndyA 0:96532c59670f 83
AndyA 5:fc8eefeb301b 84
AndyA 5:fc8eefeb301b 85 /**
AndyA 7:9409a72ab6c0 86 Opens all the streaming connections.
AndyA 4:33006c37c633 87
AndyA 7:9409a72ab6c0 88 Normally you'd do this after a sucessful call to init() and before starting plotting in order to avoid a connection delays when you first call plot()
AndyA 7:9409a72ab6c0 89 */
AndyA 7:9409a72ab6c0 90 void openStreams();
AndyA 7:9409a72ab6c0 91
AndyA 8:d4f705ba2ea5 92 /** Close all the streaming connections
AndyA 7:9409a72ab6c0 93
AndyA 7:9409a72ab6c0 94 Call to tidy up and free up system resources once there is no more data to send
AndyA 4:33006c37c633 95 */
AndyA 7:9409a72ab6c0 96 void closeStreams();
AndyA 7:9409a72ab6c0 97
AndyA 4:33006c37c633 98 /**
AndyA 7:9409a72ab6c0 99 Opens a specific streaming connection. Normally you would use openStreams() however if you only want to update a single line on a multi-line chart then this can save time and memory.
AndyA 7:9409a72ab6c0 100
AndyA 7:9409a72ab6c0 101 @param stream The line number (from 0) to open
AndyA 4:33006c37c633 102 */
AndyA 7:9409a72ab6c0 103 bool openStream(int stream);
AndyA 7:9409a72ab6c0 104
AndyA 7:9409a72ab6c0 105 /**
AndyA 7:9409a72ab6c0 106 Close a specific streaming connection.
AndyA 7:9409a72ab6c0 107
AndyA 7:9409a72ab6c0 108 @param stream The line number (from 0) to open
AndyA 7:9409a72ab6c0 109 */
AndyA 7:9409a72ab6c0 110 void closeStream(int stream);
AndyA 0:96532c59670f 111
AndyA 4:33006c37c633 112 /**
AndyA 4:33006c37c633 113 output message level
AndyA 4:33006c37c633 114 Messages are sent to stderr (which defaults to the mBed USB programing/debug port).
AndyA 4:33006c37c633 115 0 = Debugging, 1 = Informational, 2 = Status, 3 = Errors (default), 4 = Quiet
AndyA 4:33006c37c633 116 */
AndyA 0:96532c59670f 117 int log_level;
AndyA 4:33006c37c633 118
AndyA 4:33006c37c633 119 /**
AndyA 4:33006c37c633 120 set true to not actually connect to the network..
AndyA 4:33006c37c633 121 */
AndyA 0:96532c59670f 122 bool dry_run;
AndyA 4:33006c37c633 123
AndyA 4:33006c37c633 124 /**
AndyA 4:33006c37c633 125 Maximum points to display on the streaming chart, once you go over this old points will no longer be displayed.
AndyA 4:33006c37c633 126 Defaults to 30
AndyA 4:33006c37c633 127 */
AndyA 0:96532c59670f 128 int maxpoints;
AndyA 4:33006c37c633 129
AndyA 4:33006c37c633 130 /**
AndyA 4:33006c37c633 131 Sets whether the chart will be public or not.
AndyA 4:33006c37c633 132 Defaults to true
AndyA 4:33006c37c633 133 */
AndyA 0:96532c59670f 134 bool world_readable;
AndyA 4:33006c37c633 135
AndyA 4:33006c37c633 136 /**
AndyA 4:33006c37c633 137 Converts timestamps to the local time zone
AndyA 4:33006c37c633 138 */
AndyA 0:96532c59670f 139 bool convertTimestamp;
AndyA 4:33006c37c633 140 /**
AndyA 4:33006c37c633 141 Timezone string to use
AndyA 4:33006c37c633 142 */
AndyA 0:96532c59670f 143 char *timezone;
AndyA 4:33006c37c633 144 /**
AndyA 4:33006c37c633 145 Sets what to do if the file already exists, valid options are:
AndyA 4:33006c37c633 146 "new","overwrite" (default),"append","extend"
AndyA 4:33006c37c633 147 */
AndyA 0:96532c59670f 148 char *fileopt;
AndyA 0:96532c59670f 149
AndyA 0:96532c59670f 150 private:
AndyA 6:e57d6e9313f4 151
AndyA 7:9409a72ab6c0 152 void reconnectStream(int stream);
AndyA 4:33006c37c633 153
AndyA 6:e57d6e9313f4 154 bool print_(int d,int stream = 0);
AndyA 6:e57d6e9313f4 155 bool print_(unsigned long d,int stream = 0);
AndyA 6:e57d6e9313f4 156 bool print_(float d,int stream = 0);
AndyA 6:e57d6e9313f4 157 bool print_(char *d,int stream = 0) {return print_((const char *)d, stream);};
AndyA 6:e57d6e9313f4 158 bool print_(const char *d,int stream = 0);
AndyA 6:e57d6e9313f4 159 bool printHex_(uint16_t d,int stream = 0);
AndyA 7:9409a72ab6c0 160 bool printNetTerminator_(int stream = 0);
AndyA 7:9409a72ab6c0 161
AndyA 6:e57d6e9313f4 162 bool sendFormatedText(char* data, int size,int stream = 0);
AndyA 0:96532c59670f 163
AndyA 7:9409a72ab6c0 164 char buffer[k_bufferSize];
AndyA 7:9409a72ab6c0 165
AndyA 6:e57d6e9313f4 166 TCPSocketConnection **sockets;
AndyA 0:96532c59670f 167
AndyA 6:e57d6e9313f4 168 const char *username_;
AndyA 6:e57d6e9313f4 169 const char *api_key_;
AndyA 6:e57d6e9313f4 170 const char** stream_tokens_;
AndyA 6:e57d6e9313f4 171 const char *filename_;
AndyA 0:96532c59670f 172 int nTraces_;
AndyA 1:d532e96fca12 173
AndyA 1:d532e96fca12 174 bool initalised;
AndyA 0:96532c59670f 175
AndyA 0:96532c59670f 176 };
AndyA 0:96532c59670f 177 #endif